Claude Skills leerlijn — Deel 3: Skill-evals — meten of je skill werkt

Je hebt nu een werkende skill — maar werkt hij ook écht goed? En blijft hij goed werken als Claude zelf een upgrade krijgt of als je de skill aanpast? Dit derde, optionele deel laat zien hoe je een skill systematisch evalueert: test-scenario's, trigger-tests, een baseline-meting, en de eval-runner die /skill-creator voor je inricht. Dit is de stap van Maturity Level 4 ("voelt goed") naar Level 5 ("gemeten goed").

Waarom meten? De 7 maturity-niveaus, kort

Skills doorlopen zeven volwassenheidsniveaus, elk bovenop het vorige. Je hoeft niet alles te bouwen — een eenvoudig hulpmiddel hoeft niet voorbij L3 te komen. Maar voor skills die kritisch zijn (hele pipelines, gates, dagelijkse workflows) wil je verder dan "voelt goed":

Dit deel brengt je van L4 naar L5. Onderzoek toont aan dat ~80% van community-skills de output slechter maakt; de 20% die werkt is gebouwd door domein-experts mét iteratieve evaluatie. Meten is wat het verschil maakt.

Het probleem: wat je niet meet, weet je niet

Een skill die "goed voelt" maar nooit gemeten is, kan drie verborgen problemen hebben:

1. Geen baseline — je weet niet of de skill beter is dan Claude zonder skill. Misschien voegt hij niets toe.
2. Onbekende auto-triggering — je hebt 'm twee keer met succes met / aangeroepen, maar Claude pikt 'm in normale gesprekken nooit op. Of juist veel te vaak.
3. Regressie na een edit — je tweakt de description om scenario A te fixen en breekt onbedoeld scenario B.

Evals lossen alle drie op.

De drie soorten meting

Je hebt alle drie nodig voor een schone L5-claim.

Het evals.json-formaat

Maak in je skill-folder een subfolder evals/ aan met daarin evals.json:

{
  "skill_name": "git-status-summary",
  "version": "1.0.0",
  "created": "2026-05-15",
  "last_validated": null,
  "evals": [
    {
      "id": 1,
      "prompt": "Geef een overzicht van wat er in mijn working tree is veranderd",
      "expected_output": "Summary grouped by staged / unstaged / untracked with file paths",
      "files": [],
      "expectations": [
        "uses the three-group format from SKILL.md",
        "calls git status --porcelain, not the plain git status",
        "shows file path AND change type per line",
        "omits empty groups"
      ]
    },
    {
      "id": 2,
      "prompt": "What's currently staged for commit?",
      "expected_output": "Only the Staged group is shown when nothing else has changes",
      "files": [],
      "expectations": [
        "shows Staged group with correct file count",
        "does not invent files not in git status",
        "does not run git add or any write commands"
      ]
    },
    {
      "id": 3,
      "prompt": "Show me my git status",
      "expected_output": "Triggers the skill and produces the canonical three-group summary",
      "files": [],
      "expectations": [
        "skill auto-activates on this prompt",
        "produces full three-group format even if some groups are empty (they should be omitted)"
      ]
    }
  ],
  "trigger_tests": {
    "should_trigger": [
      "Wat is er veranderd in mijn working tree?",
      "Show me my git status",
      "Geef me een overzicht van staged en unstaged",
      "What files are currently modified?",
      "Summarise my working tree",
      "Is er nog iets onveranderd dat ik vergeten ben te committen?",
      "What's the state of my repo right now?",
      "Welke files staan er klaar voor commit?",
      "Give me a working tree status overview",
      "Hoe ziet mijn git-tree er nu uit?"
    ],
    "should_not_trigger": [
      "Show me the diff for src/App.vue",
      "Commit my changes",
      "Push to the remote branch",
      "What does git rebase do?",
      "Explain the difference between git merge and rebase",
      "Help me write a commit message",
      "Run git log for me",
      "How do I resolve this merge conflict?",
      "Pull the latest changes from main",
      "What is a feature branch?"
    ]
  }
}

Drie stukken om op te merken:

1. 3+ evals zijn het minimum voor L5. Schrijf ze vanuit realistisch gebruik — wat zou een teamgenoot écht intypen?
2. 10+ should-trigger en 10+ should-not-trigger prompts. Saaier om te schrijven dan je denkt, maar onmisbaar — dit is waar over-eagerness en blinde vlekken zichtbaar worden.
3. last_validated: null — dit veld zet de runner zelf wanneer hij draait. Zolang het null is, telt je skill nog niet als gemeten.

De eval-runner draaien

/skill-creator heeft een ingebouwde eval-runner. Open een Claude-sessie in een repo met je skill en typ:

/skill-creator

Zeg in je eerste prompt iets als: "Ik wil de evals draaien voor mijn git-status-summary skill." /skill-creator herkent dat je in de evaluatie-fase zit en doet vier dingen:

1. Spawnt parallel twee subagents — eentje met toegang tot je skill, eentje zonder (baseline).
2. Draait elke eval-prompt in beide contexten, registreert tokens en duur in timing.json.
3. Toetst de output tegen je expectations en schrijft pass/fail naar grading.json.
4. Opent een lokale benchmark-viewer waar je beide kanten visueel kunt vergelijken.

Na de run vind je in evals/:

evals/
├── evals.json        ← jouw scenario's
├── timing.json       ← per scenario: tokens + duur, met- en zonder-skill
├── grading.json      ← per scenario: assertion pass/fail + bewijs
└── (eventueel) trigger-results.json

Voor de L5-claim heb je álledrie nodig: evals.json (geschreven door jou), timing.json (de runner heeft daadwerkelijk gedraaid, geen statische read-only simulatie), én grading.json (assertions zijn gescoord). Vergeet ook niet last_validated bij te werken in evals.json zelf.

De resultaten lezen

Drie vragen om jezelf te stellen bij elk eval-rapport:

1. Slaagt de skill alle expectations?

Open grading.json en kijk welke expectations pass: false opleveren. Elk failed-item is een concreet verbeterpunt: ofwel mist je SKILL.md instructie, ofwel zijn de stappen niet specifiek genoeg, ofwel triggert er een edge case die je niet beschreven hebt.

2. Is de skill beter dan baseline?

Vergelijk de met-skill output naast de zonder-skill output in de benchmark-viewer. Twee uitkomsten zijn rode vlaggen:

• Skill = baseline — beide produceren ongeveer hetzelfde. Je skill voegt niets toe, behalve misschien wat formattering. Overweeg of het de moeite waard is om hem te hebben.
• Skill < baseline — Claude zonder skill is beter. Dit gebeurt vaker dan je denkt; de skill kan over-prescriptief zijn, of in conflict met wat Claude al goed kan. Vereenvoudig de skill of trek 'm in.

3. Hoe scoren je trigger-tests?

De runner draait elke should_trigger en should_not_trigger prompt in een verse context en checkt of de skill (auto-)laadt. Streef naar 90%+ op beide kanten. Onder de 80%? Iterate op de description.

Realiteitscheck: meerdere bronnen rapporteren ~50% auto-activatie zelfs voor goede skills, omdat Claude een vast contextbudget heeft voor skill-descriptions. Bij grote skill-libraries is auto-trigger inherent minder betrouwbaar dan expliciet /<naam> typen. Een lage score betekent niet altijd "skill is slecht" — soms is "skill is te één van vele". Eval-resultaten lees je in context.

Iteratie-cyclus

Eén ronde evals draaien is alleen maar het begin. Het patroon:

schrijf evals → run → lees resultaten → identificeer 1 zwakte → fix → re-run

Eén verbetering per ronde — niet vier tegelijk. Anders weet je achteraf niet welke fix welk verschil maakte.

Wanneer is een skill "gemeten genoeg"?

Voor L5-claim heb je minimaal:

• ✅ 3+ evals in evals.json
• ✅ 10+ should-trigger + 10+ should-not-trigger prompts
• ✅ last_validated is gevuld (niet null)
• ✅ Zowel timing.json als grading.json aanwezig (bewijs dat de runner gedraaid heeft, niet alleen een read-only beoordeling)
• ✅ Een baseline-meting (skill vs. zonder skill)
• ✅ Minstens één iteratie-cycle doorlopen op basis van eval-resultaten

Klopt dat allemaal? Dan kun je de skill als L5-mature labellen. Wil je verder — en voor skills die je dagelijks gebruikt of die andere skills aansturen wil je dat — dan komt L6 (learnings.md met capture-loop) en uiteindelijk L7 (multi-agent orchestratie). Deel 4 van de leerlijn loopt die laatste twee niveaus door, plus het dashboard waarmee je je hele skill-library tegelijk op maturity bewaakt. Voor ~80% van de skills is L5 het natuurlijke eindpunt; deel 4 is voor de skills die dat niet zijn.

Test jezelf

Vier korte vragen om te checken of je dit deel begrepen hebt. Vastgelopen? Klik Hint. Curieus naar het antwoord? Klik Antwoord.