Claude Skills leerlijn — Deel 4: Van gemeten naar lerend en orkestrerend (L6 → L7)
Hoe ga je voorbij L5? L6 zet een learnings-loop op je skill, L7 maakt er een orkestrator van die sub-agents aanstuurt. Plus een blik op het skill-level-overview dashboard waarmee je je hele skill-library in één oogopslag op maturity kunt scannen. Vierde van vier korte modules.
In deel 3 bracht je een skill van "voelt goed" naar "gemeten goed" — Maturity Level 5. Voor de meeste skills is dat genoeg. Maar voor een handvol skills die je dagelijks gebruikt of die andere skills aansturen, wil je verder: een skill die leert van zijn eigen executies (L6), en een skill die andere agents aanstuurt in een grotere workflow (L7). Dit vierde deel laat zien hoe je daar komt — én hoe je met het Hydra-dashboard je hele skill-library tegelijk op maturity bewaakt.
Recap: de 7 niveaus, en waar we nu zijn
| Level | Wat erbij komt |
|---|---|
| L1–L4 | Anatomy, golden rule, foundations, business-context |
| L5 | 3+ evals, trigger-tests, baseline — deel 3 |
| L6 | learnings.md + capture-stap, periodieke consolidatie — dit deel |
| L7 | Orkestreert sub-agents of zit in een workflow-keten — dit deel |
Belangrijk: niveaus zijn cumulatief in criteria maar niet altijd in praktijk. Een skill kan een L7-architectuur hebben (spawnt acht parallele agents) zonder L5-evals te hebben — dat heet structureel L7, maturity L4. De architectuur is er, de zelfkennis nog niet. Voor échte L7 moet je L1 t/m L6 erbij hebben.
Niveau 6: Self-Improvement — skills die leren van hun executies
Een L5-skill is gemeten, maar statisch. Elke executie verloopt los van de vorige; wat je vorige week leerde, vergeet de skill morgen. L6 lost dat op met een learnings-loop:
Executie → observaties vastleggen → learnings.md → consolidatie → SKILL.md-regels
↑ │
└──────────────────────────────┘
De ingrediënten
Drie dingen maken een skill L6-mature:
- Een
learnings.mdin de skill-folder. - Een "Capture Learnings"-stap aan het einde van
SKILL.md— Claude wordt aan het einde van elke executie expliciet gevraagd of er iets in de uitvoering opviel dat een toekomstige run kan helpen. - Een consolidatie-ritme — typisch bij 80–100 entries kijk je terug, verwijder je verouderde regels, voeg je duplicaten samen, en promoveer je gevalideerde principes naar guardrails in
SKILL.mdzelf.
Het formaat van learnings.md
Elke entry is gedateerd en atomair (één inzicht per bullet). De file kent vijf vaste secties:
# Learnings — create-pr
## Patterns That Work
- 2026-03-15: Branch protection op `main` vraagt status checks — altijd eerst verifiëren dat ze bestaan.
- 2026-03-20: GitHub issue-nummer in PR-titel verbetert traceability.
## Mistakes to Avoid
- 2026-03-18: NIET een PR maken met uncommitted changes — onduidelijk wat er meegaat.
- 2026-03-22: composer.lock-conflict → lokaal `composer update` draaien, niet één kant accepteren.
## Domain Knowledge
- 2026-03-19: Conduction-repos gebruiken `development` als primaire integratie-branch, niet `main`.
## Open Questions
- Moeten PRs reviewers auto-assignen via CODEOWNERS?
## Consolidated Principles
- (gepromoot na 3+ bevestigingen)
- Draai altijd `composer check:strict` vóór PR-aanmaak — vangt 90% van review-feedback af.
De "Capture Learnings"-stap in SKILL.md
learnings.md vult zichzelf niet — Claude doet dat alleen als je hem er expliciet om vraagt. De manier waarop is een vaste stap, helemaal onderaan in SKILL.md, na alle uitvoeringsstappen en vóór de guardrails. Hieronder een voorbeeld zoals het in Conductions create-pr-skill staat — kort, met de vijf rubrieken vooropgesteld zodat Claude ze niet vergeet:
## Capture Learnings
After execution, review what happened and append new observations to
[learnings.md](learnings.md) under the appropriate section:
- **Patterns That Work** — approaches that produced good results
- **Mistakes to Avoid** — errors encountered and how they were resolved
- **Domain Knowledge** — facts discovered during this run
- **Open Questions** — unresolved items for future investigation
Each entry must include today's date. One insight per bullet.
**Skip if nothing new was learned** — do NOT invent learnings to fill the section.
Drie dingen om op te merken:
- Het is een stap, geen suggestie. Door hem als
## Capture Learnings-sectie te formatteren staat hij in dezelfde "doe-dit"-modus als de andere genummerde stappen. Een vrijblijvende zin als "denk eraan om eventueel iets op te schrijven" wordt door Claude vaak overgeslagen. - "Skip if nothing new was learned" is cruciaal. Zonder die regel produceert Claude altíjd iets — pseudo-inzichten zoals "de skill werd succesvol uitgevoerd". Dat is precies het soort ruis dat
learnings.mdsnel vervuilt en bij elke run je context-budget opslokt. - Per sectie expliciet de bedoeling vermelden — niet alleen de naam. "Patterns That Work" alléén triggert generieke inhoud; "approaches that produced good results" stuurt Claude naar gericht observerend gedrag.
Variant voor skills met een container/headless-modus: voeg een tabel toe boven aan SKILL.md die expliciet zegt dat de Capture Learnings-stap in headless-mode wordt overgeslagen (een container-filesystem is wegwerp — schrijven naar learnings.md is verspilling). De opsx-apply-skill doet dat zo:
| Stap | Interactive mode | Headless mode (CI) |
|---|---|---|
| Capture Learnings | Append to `learnings.md` | **Skip** — container filesystem is disposable |
De two-stage buffer (sterk aanbevolen)
Het naïeve patroon — élke observatie direct in learnings.md schrijven — vult het bestand snel met ruis. Een teamgenoot meldde iets dat "vreemd voelde" maar bij nader inzien een toevallige fluctuatie was; nu staat het er, en bij elke run leest Claude het mee.
De fix is een two-stage buffer:
learning-candidates.md → (promotie-criteria gehaald?) → learnings.md → SKILL.md-regels
↓ (nee)
verwijderd na 30 dagen
Promotie-criteria zijn bewust streng:
- Observatie minstens 3 keer bevestigd in losse executies, óf
- Observatie lost een gemeten eval-failure op uit deel 3.
Zo blijft learnings.md schoon en wordt context-budget niet verspeeld aan eenmalige toevalligheden.
Wanneer consolideer je?
Bij ~80–100 entries wordt learnings.md zelf een context-last. Trigger op dat moment een consolidatie-ronde:
- Verouderd? — verwijderen (de bug is gepatcht, de regel niet meer relevant).
- Duplicaten? — samenvoegen tot één scherpere bullet.
- Cross-cutting patroon? — promoveer naar de "Consolidated Principles"-sectie.
- Gevalideerd principe? — schrijf het als guardrail of stap rechtstreeks in
SKILL.md, en haal de losse observaties die ernaar leidden uitlearnings.md.
Niveau 7: AI Workforce — skills die andere agents aansturen
L7 is geen "betere skill" — het is een andere soort skill. Een L7-skill levert geen output zelf, maar coördineert een team van sub-agents of zit zelf in een keten van skills die naar elkaar handoffen.
Criteria (boven op L6)
- Spawnt sub-agents (parallelle workers) óf wordt zelf aangeroepen door een parent-skill.
- Zit in een gedefinieerde workflow-chain met expliciete hand-off-punten:
opsx-new → opsx-ff → opsx-plan-to-issues → opsx-apply → opsx-verify → opsx-archive - Geeft context door aan de volgende skill (toont "Next step: run
/opsx-verify"). - Gebruikt geïsoleerde execution-contexten waar nodig (git worktrees, Docker, sandbox).
- Heeft autonomy binnen een gedefinieerde scope — niet alles vraagt om bevestiging.
- Doet parallel werk (acht agents tegelijk, fan-out/fan-in).
Orkestratie-patronen in Hydra
| Patroon | Voorbeeld in Hydra | Beschrijving |
|---|---|---|
| Pipeline | opsx-pipeline | Volledige lifecycle voor 1+ changes parallel via subagents |
| Fan-out/Fan-in | test-counsel, feature-counsel | N agents parallel spawnen, daarna één synthese |
| Sequential Chain | opsx-new → … → opsx-archive | Elke skill handoft naar de volgende |
| Autonomous Loop | opsx-apply-loop | Draait apply→verify-cycle met retry, auto-archive |
| Multi-perspective | test-app | Zes gespecialiseerde test-agents simultaan |
Structureel L7 ≠ mature L7
Het is verleidelijk om een orkestrator op te tuigen en je werk klaar te verklaren. Maar als die orkestrator geen evals heeft (L5) en geen learnings-loop (L6), heb je een complexe machine zonder zelfkennis. Hij dóét veel; je weet niet hoe goed.
Dat heet structureel L7, maturity L4. Het probleem: zodra hij faalt, weet niemand wáár in de keten het misging, en de fout herhaalt zich morgen weer. Voor échte L7 moet je de L5- en L6-gaten dichten — meet de keten als geheel én op handoff-punten, en laat de orkestrator zelf observaties capturen.
De hele library bewaken: het skill-level-overview-dashboard
Eén skill op L6 of L7 brengen is overzichtelijk. Maar zodra je een library van tien, twintig of (zoals in Hydra) ~70 skills hebt, wil je in één oogopslag zien welke skill op welk niveau zit — en welke achteruit kachelen.
Daarvoor zitten er in de Conduction-skill-toolchain twee bestanden onder .claude/skills/:
skill-level-overview.html— een lokaal, statisch HTML-dashboard. Eén tabel met per skill: huidige maturity (groene dots), target maturity (badge), regelaantal vanSKILL.md(gekleurd: groen ≤200, geel rond 450, rood >500), en oranje rings voor "structureel aanwezig maar nog niet mature". Sorteerbaar per kolom. Je opent 'm lokaal —xdg-openop Linux,openop macOS, of dubbelklik in de file-explorer.update-skill-overview.sh— een bash-script dat over alle skill-folders heen scant, structurele markers detecteert (frontmatter aanwezig, guardrails, evals met genoeg trigger-tests, dated learnings, agent-spawns), en de HTML up-to-date schrijft. Eén./update-skill-overview.shen je dashboard klopt weer.
Wat het script automatisch doet
Het script detecteert:
| Niveau | Wat het script meet |
|---|---|
| L1 | Frontmatter aanwezig, genummerde stappen, guardrail-secties of directieven, name: matcht foldernaam |
| L2 | SKILL.md ≤500 regels en description: is gevuld |
| L3 | Proven patterns + examples/ of references/ of templates/ aanwezig |
| L4 | NOOIT automatisch — moet je handmatig bevestigen (domein-kennis is mensenwerk) |
| L5 | evals/evals.json met 3+ scenario's, 10+ should-trigger, 10+ should-not-trigger, last_validated gevuld, plus grading.json én timing.json |
| L6 | learnings.md met gedateerde entries + "Capture Learnings"-stap in SKILL.md |
| L7 | Verwijzingen naar Agent tool, subagent of Task agents in SKILL.md |
Belangrijke ontwerpkeuze: L4 wordt nooit automatisch gezet. Domein-kennis is niet detecteerbaar uit bestandsstructuur — alleen jij kunt zeggen of een skill jouw business écht kent. Het script roept luidruchtig om aandacht als L1–L3 staan maar L4 nog niet bevestigd is.
Hoe je dit voor je eigen project opzet
De canonieke skill-level-overview.html + update-skill-overview.sh zitten in Conductions interne skill-toolchain. Twee paden om er zelf mee aan de slag te gaan:
- Vraag de bestanden op — mail ons via de CTA onderaan deze pagina; we delen de huidige versie graag met klanten en partners als startpunt. Daarna is het
cpnaar<jouw-repo>/.claude/skills/enbash .claude/skills/update-skill-overview.shdraaien. - Bouw zelf — de meet-regels uit de tabel hierboven zijn alles wat je nodig hebt. Een paar uur bash + een simpele HTML-tabel-template levert al een werkende v1.
Een natuurlijke plek om het script te draaien: vóór een release-tag, in een pre-commit hook op de skills-folder, of als wekelijkse cron. Zo zie je drift (een skill die naar 520 regels groeit en dus L2 verliest) meteen.
Test jezelf
Vier korte vragen om te checken of je dit deel begrepen hebt. Vastgelopen? Klik Hint. Curieus naar het antwoord? Klik Antwoord.
1. Waarom een two-stage buffer in plaats van direct in learnings.md schrijven?
Hint
Wat gebeurt er als élke vluchtige observatie meteen permanent wordt opgeslagen?
Antwoord
Omdat directe schrijfacties learnings.md snel verontreinigen met eenmalige toevalligheden, foutdiagnoses die later anders bleken te zijn, of observaties die alleen voor één specifieke context relevant waren. Elk daarvan blijft daarna in elke executie meegelezen worden, en eet van je context-budget.
De two-stage buffer (learning-candidates.md → learnings.md) plaatst een filter ertussen: alleen observaties die minstens 3 keer bevestigd zijn, of die een gemeten eval-failure oplossen, promoveren. De rest valt na 30 dagen vanzelf weg. Het resultaat: learnings.md blijft hoogwaardige signalen bevatten, en bij consolidatie heb je echte patronen om te promoten naar SKILL.md-guardrails.
2. Wat is het verschil tussen "structureel L7" en "mature L7", en waarom is dat verschil belangrijk?
Hint
Een skill kan architecturaal complex zijn zonder ooit gemeten of geleerd te hebben.
Antwoord
- Structureel L7 betekent dat de skill de architectuur van orkestratie heeft: spawnt subagents, zit in een keten, doet hand-offs, draait parallel.
- Mature L7 betekent dat die architectuur óók is gemeten (L5) en zichzelf verbetert (L6).
Een "structureel L7, maturity L4" skill is een complexe machine zonder zelfkennis. Hij dóét veel — je weet niet hoe goed. Zodra hij faalt is onduidelijk wáár in de keten het misging, en de fout herhaalt zich morgen.
Het verschil is belangrijk omdat orkestrators groot blast-radius hebben: ze starten meerdere agents, doen meerdere acties, raken meerdere bestanden. Als je daarbij geen evals (L5) en geen learnings (L6) hebt, schaal je fouten net zo hard mee als successen.
3. Waarom zet update-skill-overview.sh L4 nooit automatisch?
Hint
Wat onderscheidt L4 van L1, L2, L3, L5, L6 en L7 in termen van wat detecteerbaar is?
Antwoord
Omdat L4 — "Personalization / Domain Knowledge" — betekent dat de skill jouw bedrijfsspecifieke kennis bevat (ADRs, naming conventions, business-rules, "wij gebruiken development als primaire branch"). Dat is niet detecteerbaar uit bestandsstructuur, regelaantallen of frontmatter-velden.
L1 t/m L3 zijn structureel (frontmatter, guardrails, voorbeelden — een script kan ze zien). L5 t/m L7 zijn structureel óf gedrags-gerelateerd op manieren die in bestanden zichtbaar zijn (evals-json, learnings.md, agent-calls).
Maar L4 vereist een mens die zegt: "ja, deze skill kent ónze codebase, niet alleen generieke best-practices." Daarom roept het script luid om jouw input zodra L1–L3 zijn behaald maar L4 nog niet bevestigd. Tot dat moment blijft de skill op M3 hangen, ook al zijn er structureel al hogere niveaus aanwezig.
4. Een teamgenoot heeft een skill die parallel zes test-agents spawnt, maar geen evals en geen learnings.md heeft. Wat zou jij voorstellen — eerst meer orkestratie toevoegen, of eerst iets anders?
Hint
Denk aan het verschil tussen architectuur en zelfkennis.
Antwoord
Eerst niet meer orkestratie. Deze skill is structureel L7, maturity L4 — de architectuur staat er, maar er is geen meting (L5) en geen lerend gedrag (L6). Meer parallellisme of meer chain-skills toevoegen vergroot alleen de blast-radius.
De juiste volgorde:
- L5 eerst — schrijf 3+ eval-scenario's voor de hele keten en voor de hand-off-punten. Pas dan weet je of de zes parallele agents elkaar niet tegenwerken of dubbel werk doen.
- L6 daarna — voeg een
learnings.mdtoe waarin de orkestrator vastlegt welke patronen tussen agents wel/niet werken (bv. "wanneer agent A en B beide hetzelfde bestand aanraken, ontstaat conflict X"). - Pas dan L7-uitbreiding — als de keten gemeten en lerend is, kun je hem veilig uitbreiden (meer agents, langere chain, autonome loop).
Vuistregel: orkestratie zonder meting is ongeoorloofd schaalwerk. Eerst weten of de keten werkt, dan groter maken.
Volgende stap
Je hebt nu het complete spectrum gezien: van anatomy tot orkestratie, plus het dashboard om je hele library te bewaken. Dit zijn goede volgende stappen.