Marktmannen wiki Coderen met AI

Skills Bouwen — Zeven Bijgewerkte Regels

Laatst bijgewerkt

TL;DR: Anthropic's best-practices-gids voor skills bevat zeven structuurregels — van een inhoudsopgave boven 100 regels tot per-model testen — mede omdat Claude een lang of genest referentiebestand soms maar gedeeltelijk inleest (bijvoorbeeld de eerste 100 regels).

Claude opent een lang referentiebestand binnen een skill niet altijd volledig. Volgens Anthropic's docs kan Claude bij geneste verwijzingen een bestand gedeeltelijk lezen, bijvoorbeeld met head -100; de video maakt daar een standaardgedrag van ("eerst ongeveer de eerste 100 regels scannen"), wat de docs niet zo stellen. Regels die buiten dat deel vallen, bestaan dan in de praktijk niet voor Claude, tot het besluit het bestand toch volledig te lezen. Anthropic's best-practices-gids — volgens de video recent bijgewerkt, wat niet aantoonbaar is; de inhoud staat er wel in — geeft daarvoor zeven regels, los van en aanvullend op de vier praktijken in Skills Verbeteren — Vier Praktijken.

1. Contentlijst boven de 100 regels

Elk referentiebestand langer dan 100 regels krijgt een inhoudsopgave boven aan, met exact de koppen die daaronder staan — zodat Claude het hele bestand leest, of meteen naar de juiste sectie springt.

2. Degrees of freedom per stap

Niet elke stap in een skill verdient dezelfde precisie. Drie niveaus:

  • Hoog — platte instructies, de aanpak mag variëren (bijv. een code review, of voor niet-coders: een LinkedIn-post reviewen).
  • Middel — een voorkeurssjabloon met instelbare variatie (bijv. een wekelijks klantrapport).
  • Laag — een exact commando of script zonder ruimte voor afwijking (bijv. een database-migratie, of alles wat met geld of verwijderen te maken heeft).

Eén skill mag niveaus mixen per stap. Vraag bij elke stap: wat gebeurt er als Claude het anders doet? Weinig gevolgen → geef het meer vrijheid. Consequenties → een script, geen platte tekst.

3. Test op elk model dat je gaat gebruiken

Het detailniveau dat een skill nodig heeft, verschilt per model. Volgens de video is dat de afgelopen maanden omgedraaid: oudere modellen hadden expliciete, benadrukte instructies nodig; nieuwere, sterker redenerende modellen zouden vaak slechter presteren met te prescriptieve skills (niet bevestigd in de docs). Anthropic's testvraag per model: werkt de skill voor Haiku met genoeg richting, is hij voor Sonnet duidelijk en efficiënt, en vermijdt hij bij Opus overbodige uitleg?

Let op bij het modelveld: de video adviseert het beoogde model in de YAML-frontmatter te documenteren, maar model: in de skill-frontmatter is in Claude Code geen documentatieveld — het is een override: de skill draait dan op dat model.

4. Referenties maximaal één niveau diep

Wijst skill.md naar advance.md, en advance.md weer naar details.md, dan leest Claude vaak alleen het eerste deel van details.md — het head-100-probleem, maar dan door een extra laag heen. Oplossing: elk referentiebestand wordt rechtstreeks vanuit skill.md gelinkt, nooit via een ander referentiebestand.

5. Checklists voor meerstaps-processen

Voor complexe skills: een checklist die Claude overneemt in zijn antwoord en afvinkt terwijl het werkt — vooral waar de volgorde ertoe doet. Een losse stap krijgt een korte alinea; de laatste stap in een onderzoeksproces is vaak "verifieer citaties": controleer dat elke claim naar de juiste bron verwijst, en ga terug naar een eerdere stap als dat niet klopt — dat voorkomt dat een mislukte stap toch wordt afgevinkt.

6. Self-correction loops

Patroon: voer een check uit, herstel wat niet klopt, herhaal tot de check slaagt. De check hoeft geen code te zijn — een merkstijlgids waartegen Claude zijn eigen concept beoordeelt, elk probleem benoemt, herschrijft en herbeoordeelt, werkt net zo goed. Eigen invulling van de video: faalt een concept op iets dat nog niet in de stijlgids staat, laat Claude dan aan het eind een nieuwe regel voorstellen; na akkoord gaat die het document in en wordt de volgende run daar ook tegen gecontroleerd.

7. Afhankelijkheden expliciet

Een skill die stilletjes aanneemt dat een package al geïnstalleerd is, breekt op een nieuwe machine of bij een teamgenoot. Zet daarom bij elk script in de skill een installatie-instructie met de exacte pakketnaam. Volgens de video slaat Claude die stap vanzelf over als het pakket al geïnstalleerd is (niet bevestigd). Houd er rekening mee dat pakketbeschikbaarheid per omgeving verschilt, bijvoorbeeld tussen claude.ai en de API, waar skills zonder netwerktoegang draaien.

Harde grenzen uit de docs

Aanvullend op de zeven regels noemen Anthropic's docs:

  • Frontmatter-limieten: name max. 64 tekens, description max. 1.024 tekens. In Claude Code worden description + when_to_use samen in de skill-lijst afgekapt op 1.536 tekens.
  • SKILL.md onder de 500 regels; meer inhoud naar referentiebestanden.
  • Description in de derde persoon ("Verwerkt Excel-bestanden…", niet "Ik help je…").
  • Minimaal drie evaluaties per skill, zodat je kunt meten of een wijziging helpt.

Open vragen

  • Hoe verhoudt regel 3 (per-model testen) zich tot skills die al specifiek voor Claude 5-modellen zijn afgeslankt — en waar leg je het beoogde model vast, nu model: in de frontmatter een override is en geen documentatieveld?
  • De bron noemt geen harde regel over wie de contentlijst (regel 1) actueel houdt als een referentiebestand wordt bewerkt — risico op een inhoudsopgave die niet meer bij de koppen past.

Verwante concepten

  • Skills Verbeteren — Vier Praktijken — vier praktijken over de kwaliteit van skills (DRY, descriptions, correcties, verificatie); dit artikel gaat over de bestandsstructuur eromheen, met regel 6 als structurele tegenhanger van praktijk 4
  • Skills en Plugins — wat een skill of plugin is; deze zeven regels zijn de onderhoudscheck voor élke skill daaruit
  • Skill Systems — regel 4 (referenties één niveau diep) is de bestandsstructuur-tegenhanger van hetzelfde progressive-disclosure-argument tegen mega-skills

Bronnen

#skills #werkwijze #context

Backlinks