Skills & Subagents: bouw je eigen AI-team

Een jaar geleden gebruikte ik Claude Code als een slimme autocomplete. Nu heb ik een team van gespecialiseerde AI-assistenten die parallel werken, elk met hun eigen expertise en verantwoordelijkheden.

Het verschil? Skills en subagents.

Dit zijn niet zomaar features. Dit is het verschil tussen "AI die helpt" en "AI die systematisch meewerkt". In mijn James setup zijn ze de kern van alles.

Waarom skills en subagents zo belangrijk zijn

Zonder skills en subagents loop je tegen twee problemen aan:

1. Context vervuiling

Alles wat Claude moet weten staat in CLAUDE.md. Maar hoe meer je daarin zet, hoe minder effectief het wordt. Context rot is reëel.

2. Gebrek aan specialisatie

Eén generalist-AI die alles moet kunnen, is nergens echt goed in. Net als bij menselijke teams: specialisten presteren beter dan generalisten op hun domein.

Skills en subagents lossen beide problemen op:

• Skills: kennis die alleen laadt wanneer relevant
• Subagents: geïsoleerde specialists met eigen context window

Het resultaat: minder context verspillen, betere output, sneller werken.

Skills: domeinkennis on-demand

Een skill is een instructieset die Claude automatisch laadt wanneer relevant. In plaats van alles in CLAUDE.md te proppen, maak je gerichte skills voor specifieke domeinen.

Hoe het werkt

~/.claude/skills/
├── laravel/
│   ├── SKILL.md           # Hoofdinstructies
│   ├── conventions.md     # Laravel conventies
│   └── multitenancy.md    # Spatie multitenancy specifiek
├── php/
│   ├── SKILL.md
│   └── 8.5-features.md
└── review/
    └── SKILL.md

De SKILL.md bevat frontmatter die bepaalt wanneer Claude de skill laadt:

---
name: laravel
description: Laravel development. USE WHEN writing Laravel code.
skills: php  # Laadt ook de php skill
---

# Laravel

Check composer.json voor project versie.

## Detect Mode
Check composer.json voor `livewire/livewire`:
- IF Livewire present → Livewire-first mode
- IF no Livewire → Traditional mode (lees traditional.md)

Waarom dit werkt

1. Automatisch laden - Claude ziet "USE WHEN writing Laravel code" en laadt de skill wanneer je aan Laravel werkt
2. Cascading - skills: php zorgt dat PHP kennis automatisch meekomt
3. Progressive disclosure - SKILL.md verwijst naar detail-bestanden die Claude alleen leest wanneer nodig

Mijn skills (James)

Ik heb tientallen skills gebouwd over de jaren. Hier zijn de belangrijkste categorieën:

Framework skills:

• laravel - Laravel 12 patterns, detecteert automatisch Livewire vs traditional mode
• php - PHP 8.5 conventies, nieuwe features, deprecations
• livewire-development - Livewire 4 specifieke patterns
• filament - Filament v5 admin panels
• tailwindcss-development - Tailwind CSS v4

Workflow skills:

• docs - Project documentatie management met routing naar sub-workflows
• feature - Complete feature workflow met Linear integratie en plan mode
• done - End-of-session wrap up, commits alles netjes

Tool skills:

• browser - Playwright automatisering voor screenshots en testing
• sentry - Sentry error tracking integratie
• postman - Postman collections beheer

Elke skill is gespecialiseerd. Claude laadt alleen wat relevant is voor de huidige taak.

Skill patterns die werken

1. Routing naar sub-workflows

Mijn docs skill is een voorbeeld van progressive disclosure:

---
name: docs
description: Project documentation. USE WHEN "what are the conventions", "update docs".
---

# Docs Skill

| User intent | Workflow |
|-------------|----------|
| Starting work | workflows/read.md |
| Update documentation | workflows/update.md |
| Record a decision | workflows/adr.md |

Claude leest alleen de SKILL.md (klein), bepaalt welke workflow relevant is, en leest alleen die. Geen onnodige context.

2. Framework detection

Mijn laravel skill detecteert automatisch de project setup:

## Detect Mode

Check composer.json voor `livewire/livewire`:

**IF Livewire present** → Livewire-first mode
- Validation in components, NOT Form Requests

**IF no Livewire** → Traditional mode
- Read [traditional.md](traditional.md)

Eén skill, twee gedragingen, automatisch gekozen.

3. Tool wrapping

Mijn browser skill wraps Playwright in simpele commands:

## Quick Commands

browser screenshot <url>   # Screenshot
browser errors <url>       # Check console errors
browser pdf <url>          # Generate PDF

Claude hoeft niet te weten hoe Playwright werkt. De skill abstraheert dat weg.

Subagents: gespecialiseerde assistenten

Subagents zijn een level hoger. Waar skills kennis toevoegen, zijn subagents complete assistenten met:

• Eigen context window (geïsoleerd van je hoofdgesprek)
• Eigen tools (beperkt tot wat ze nodig hebben)
• Eigen model (Haiku voor snelle taken, Opus voor complexe)
• Eigen skills (automatisch geladen)

Waarom subagents?

Anthropic's best practices zijn duidelijk: "Telling Claude to use subagents to verify details or investigate particular questions tends to preserve context availability."

Subagents houden je hoofdcontext schoon. Ze doen hun werk, returnen alleen het resultaat. De details blijven in hun eigen context.

Mijn agents (James)

Ik heb meerdere gespecialiseerde agents gebouwd. Hier zijn er een paar:

tester

---
name: tester
description: Runs tests and reports failures.
tools: Read, Glob, Bash, Task
model: haiku
---

Draait tests, detecteert automatisch het framework (Pest, Jest, pytest), spawnt fixer bij failures. Max 2 fix attempts per failure, dan escaleren.

researcher

---
name: researcher
description: Gathers context for a feature.
tools: Read, Glob, Grep, WebFetch, WebSearch
model: opus
skills: php, laravel, fluxui, vendor-docs
---

Read-only research. Verzamelt project conventies, bestaande patterns, framework docs. Returnt een compact rapport, geen raw docs.

code-reviewer

---
name: code-reviewer
description: Reviews code for security, logic issues, test gaps.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Read-only review. Scant op SQL injection, XSS, missing auth, N+1 queries. Geeft severity levels (CRITICAL, HIGH, MEDIUM, LOW) en blocking recommendations.

documenter

Evalueert uncommitted changes, bepaalt of documentatie nodig is, update alleen .docs/. Nooit applicatiecode.

Agent patterns die werken

1. Scope restriction

Elke agent heeft een CRITICAL SCOPE RESTRICTION sectie:

## CRITICAL SCOPE RESTRICTION

**YOU ONLY RUN TESTS. NOTHING ELSE.**

**NEVER run:**
- ./vendor/bin/phpstan
- ./vendor/bin/pint
- git commands

**ONLY run:**
- ./vendor/bin/pest
- php artisan test

Agents die hun scope overschrijden maken fouten. Wees expliciet.

2. Read-only waar mogelijk

Research en review agents hebben geen Edit/Write tools. Ze kunnen niets kapot maken. Best practices van PubNub bevestigen dit: "Read-only agents (reviewers, auditors) get Read, Grep, Glob - analyze without modifying."

3. Spawn chains

Mijn tester spawnt fixer:

## On Failure: Spawn Fixer

When tests fail:
1. Report failure details
2. Spawn fixer agent via Task tool
3. Track attempts (max 2 per failure)
4. After 2 failed attempts: STOP and report to user

Agents kunnen andere agents spawnen. Maar subagents kunnen geen subagents spawnen.

4. Clear output formats

Elke agent heeft een gedefinieerd output format. Geen ambiguïteit over wat de agent terug moet geven.

Skills vs Subagents: wanneer wat?

Situatie	Gebruik
Domeinkennis toevoegen	Skill
Geïsoleerde taak uitvoeren	Subagent
Automatisch laden op basis van context	Skill
Expliciet spawnen voor specifieke taak	Subagent
Kleine context footprint	Skill
Eigen context window nodig	Subagent

Vuistregel: Skills voor kennis, subagents voor taken.

Aan de slag

Start simpel:

1. Eén skill voor iets dat je vaak doet - Maak een SKILL.md met je review checklist of coding conventions
2. Eén agent voor een repetitieve taak - Een tester of reviewer is een goede start
3. Test een week, pas aan, voeg toe

De awesome-claude-code repo heeft voorbeelden om mee te beginnen. En VoltAgent's subagents collection heeft 100+ voorbeelden.

Dit is de toekomst

Skills en subagents zijn niet optioneel meer. Ze zijn het verschil tussen "Claude Code gebruiken" en "Claude Code beheersen".

Met de juiste setup heb je een team van specialisten die parallel werken. Een researcher die context verzamelt. Een tester die tests draait. Een reviewer die code checkt. Een documenter die docs bijwerkt.

Allemaal met hun eigen expertise, eigen context, eigen verantwoordelijkheden. Net als een echt development team, maar dan 24/7 beschikbaar.

Volgende stap

Dit was een overzicht. Wil je dieper?

• James AI assistant - Mijn complete setup
• Context engineering - Waarom dit allemaal nodig is
• CLAUDE.md mastery - De basis goed doen

Een voorbeeld van een krachtige skill is de playground plugin. Hiermee genereer je interactieve HTML visualisaties waar je in speelt en een prompt terugkrijgt. Zie Interactive Playgrounds.

In mijn AI trainingen bouw je je eigen skills en agents van scratch. Of bekijk hoe ik dit toepas bij AI implementatie projecten.

Vragen? Neem contact op.