Een Technische Analyse van SKILL.md Frontmatter

Dit is een technische referentie voor het frontmatter-blok binnen een Claude SKILL.md-bestand. Het doel is om elk veld en het effect ervan op het gedrag van de skill uit te leggen, met name hoe het wordt geactiveerd. De informatie hier is niet theoretisch; het is gebaseerd op onze directe ervaring met het parsen, installeren en testen van 743 unieke skills die zijn ingediend bij SkillProof. Onze methodologie omvat het uitvoeren van elke skill tegen een gestandaardiseerde set van real-world programmeertaken, en een significant deel van dat proces is het eerst begrijpen van de intentie van de auteur zoals gedeclareerd in de SKILL.md.

Wat we hebben ontdekt, is dat dit kleine YAML-blok het meest kritieke en vaak verkeerd begrepen onderdeel is van de definitie van een skill. Een verkeerd geconfigureerde frontmatter kan een skill stilletjes uitschakelen, waardoor een auteur zijn script debugt terwijl het probleem in de metadata zit. Deze gids documenteert wat elk veld doet, hoe ze interacteren en welke configuraties moeten worden vermeden.

Het SKILL.md Frontmatter Blok

Elk SKILL.md-bestand begint met een YAML frontmatter-blok, afgebakend door ---. Dit is een standaardconventie in veel statische sitegeneratoren en documentatietools, maar in de context van een Claude skill is het niet alleen voor menselijke consumptie. Het model parset dit blok om de identiteit, mogelijkheden en beperkingen van de skill te begrijpen.

Deze Claude skill YAML-sectie is het controlepaneel voor je skill. Het basismodel gebruikt deze gegevens om te beslissen of, wanneer en hoe de tools die je hebt geleverd, moeten worden uitgevoerd. Het beschouwen als slechts informatieve opmerkingen is de eerste fout.

Een minimaal frontmatter-blok ziet er zo uit:

---
name: example-skill
description: A brief but precise explanation of what this skill does.
allowed-tools: [python]
---

We zullen elk van deze velden, plus de cruciale invocatiecontrole-flags, onderzoeken op basis van patronen die zijn waargenomen in de meer dan 700 bestanden die we hebben geanalyseerd.

Kernidentiteit: name en description

Deze twee velden definiëren wat de skill is voor zowel de gebruiker als het model. Ze hebben echter zeer verschillende rollen in hoe de skill wordt geactiveerd.

name

Het name-veld is een unieke string die de skill identificeert. Het wordt gebruikt voor expliciete aanroeping wanneer een gebruiker @ typt, gevolgd door de skillnaam. Bijvoorbeeld, @example-skill. De naam moet een enkele, aaneengesloten string zijn. Conventioneel is deze in kleine letters en gebruikt het kebab-case.

Hoewel belangrijk voor identificatie en directe gebruikersaanroepen, heeft de name weinig tot geen invloed op de autonome beslissing van het model om de skill te gebruiken. Het model leidt geen functionaliteit af uit de naam git-history-analyzer. Daarvoor vertrouwt het op de description.

description

Dit is het meest belangrijke veld in de gehele SKILL.md frontmatter. De description is geen commentaar. Het is de primaire instructieset die het model vertelt wanneer jouw skill het juiste hulpmiddel is voor een bepaalde taak. Het is de API-documentatie voor het model zelf.

In onze tests is de kwaliteit van de description de variabele met de hoogste correlatie met de succescore van een skill. Vage beschrijvingen leiden tot inconsistente activering, onjuist toolgebruik of het volledig negeren van de skill. Dit is een veelvoorkomende oorzaak wanneer een Claude skill niet activeert zoals verwacht.

Een slechte description: "Analyzes code."

Dit is nutteloos. Het geeft geen informatie over welk soort analyse, welke inputs het verwacht, of welke outputs het produceert. Het model heeft geen reden om deze skill te kiezen boven zijn eigen interne mogelijkheden.

Een functionele description: "Accepts a file path as input. Reads the specified file and uses the py-complexity tool to calculate the cyclomatic complexity of each function. Returns a list of functions and their complexity scores."

Dit is effectief omdat het precies en actiegericht is:

1. Inputs: Het vermeldt duidelijk dat het een bestandspad accepteert.
2. Acties: Het specificeert wat het doet (leest het bestand, berekent cyclomatische complexiteit).
3. Tools: Het hint zelfs naar de tool die het zal gebruiken (py-complexity).
4. Outputs: Het definieert het verwachte retourformaat (een lijst van functies en hun complexiteitsscores).

Wanneer het model een taak krijgt voorgelegd zoals "Kun je de complexiteit van de functies in main.py controleren?", kan het dit verzoek direct matchen met de mogelijkheden die zijn geschetst in de tweede description. De eerste description zou worden genegeerd.

Wanneer je je eigen Claude skill schrijft, besteed dan het grootste deel van je tijd aan het verfijnen van de description. Schrijf het alsof je een functie documenteert voor een andere engineer om te gebruiken, want dat is precies wat je doet.

Toolrechten: allowed-tools

Het allowed-tools-veld is een lijst van uitvoerbare bestanden die de skill mag aanroepen. Dit fungeert als een beveiligingssandbox. Het model kan onder geen enkele omstandigheid een tool aanroepen die niet expliciet in deze array is vermeld.

allowed-tools: [python, bash, jq]

Dit is een kritieke beveiligings- en betrouwbaarheidsfunctie. Het voorkomt dat een skill willekeurige code uitvoert en definieert duidelijk de operationele reikwijdte. Tijdens onze tests verifiëren we dat de vermelde tools geschikt zijn voor het aangegeven doel van de skill. Een skill die beweert een eenvoudige JSON-formatter te zijn, maar bash in allowed-tools vermeldt, is een rode vlag. Hoewel het bash zou kunnen gebruiken om naar jq te pipen, geeft het de skill ook de mogelijkheid om elke shell-opdracht uit te voeren, wat een onnodige uitbreiding van privileges is.

We hebben skills zien falen omdat ze proberen een tool aan te roepen die niet is vermeld. Omgekeerd hebben we skills gemarkeerd die te brede permissies aanvragen die niet gerechtvaardigd zijn door hun description of implementatie. Het principe van minimale privileges is van toepassing: sta alleen de exacte tools toe die nodig zijn om de skill te laten functioneren.

Aanroepcontrole: user-invocable en disable-model-invocation

Deze twee booleaanse flags zijn minder gebruikelijk, maar hebben een diepgaande invloed op het gedrag van de skill. Ze controleren de bron van de aanroep: kan een gebruiker de skill expliciet aanroepen, en kan het model besluiten deze zelf te gebruiken? De standaardwaarde voor beide is false als ze worden weggelaten, maar het effectieve standaardgedrag van een standaard skill gaat uit van user-invocable: true en disable-model-invocation: false.

Hun interactie kan verwarrend zijn, dus hier is een samenvattende tabel:

user-invocable	disable-model-invocation	Gedrag	SkillProof Oordeel
true (of weggelaten)	false (of weggelaten)	Standaard: Gebruiker kan @ vermelden; model kan autonoom aanroepen.	De verwachte configuratie voor de meeste skills.
false	false (of weggelaten)	Alleen Autonoom: Gebruiker kan niet @ vermelden; model kan aanroepen.	Voor achtergrondtaken of helperfuncties.
true	true	Alleen Expliciet: Gebruiker moet @ vermelden; model kan niet aanroepen.	Voor tools met neveneffecten of hoge kosten.
false	true	Uitgeschakeld: Noch gebruiker, noch model kan aanroepen.	Kapotte configuratie. Deze markeren we.

user-invocable

Deze flag bepaalt of een gebruiker de skill direct kan activeren met een @-vermelding. De standaardwaarde, true, is het gedrag dat de meeste gebruikers verwachten. Een user-invocable Claude skill is er een die je op aanvraag kunt aanroepen.

Het instellen van user-invocable: false betekent dat de skill alleen kan worden geactiveerd door het autonome besluitvormingsproces van het model. De gebruiker kan het niet dwingen om te draaien. Dit is een geldige keuze voor skills die fungeren als achtergrondhelpers of onderdeel zijn van een grotere keten van tools, maar het kan een belangrijke bron van verwarring zijn. We hebben verschillende skills getest waarbij deze flag op false was ingesteld zonder enige melding in de documentatie. Gebruikers die de skill probeerden te @ vermelden, zouden geen reactie zien en aannemen dat deze kapot was. Als je dit op false instelt, moet je het duidelijk documenteren.

disable-model-invocation

Deze flag is het omgekeerde van user-invocable. Het bepaalt of het model de skill proactief zelf mag kiezen.

De standaardwaarde, false, staat het model toe de skill te gebruiken wanneer de description overeenkomt met het verzoek van de gebruiker.

Het instellen van disable-model-invocation: true verbiedt het model om de skill autonoom te gebruiken. De skill kan alleen worden uitgevoerd als user-invocable ook true is en de gebruiker deze expliciet @ vermeldt. Dit is nuttig voor tools die duur zijn, aanzienlijke neveneffecten hebben (zoals het doen van een netwerkverzoek of het wijzigen van bestanden), of zeer specifieke invoer vereisen die het model mogelijk niet correct zelf kan afleiden.

De Stille Foutcombinatie

De meest problematische configuratie die we in onze tests hebben ontdekt, is de combinatie van user-invocable: false en disable-model-invocation: true. Zoals de tabel laat zien, kan een skill die op deze manier is geconfigureerd op geen enkele manier worden geactiveerd. De gebruiker is geblokkeerd om het aan te roepen, en het model is verboden om het te kiezen.

In onze beoordeling van meer dan 700 SKILL.md-bestanden hebben we skills gevonden met precies deze configuratie. Vanuit het perspectief van de gebruiker is de skill geïnstalleerd maar volledig niet-functioneel. Het is effectief dode code. In elk geval plaatsen we deze skills in de wachtrij voor handmatige inspectie. Soms is het een fout van de auteur. Andere keren lijkt het een manier om een skill tijdelijk uit te schakelen in een repository zonder deze te verwijderen. Ongeacht de reden, het verzenden van een skill met deze configuratie is een fout.

Praktische Implicaties van 743 Skill Tests

Het begrijpen van de Claude skill frontmatter is geen academische oefening. Het is de sleutel tot het bouwen van betrouwbare en effectieve skills. Onze tests van 743 skills hebben enkele belangrijke waarheden bevestigd:

1. De description is de trigger. Tijd besteed aan het verfijnen ervan is nooit verspild.
2. Standaardwaarden zijn meestal correct. De meeste skills moeten user-invocable en model-invocable zijn.
3. Afwijkingen moeten weloverwogen en gedocumenteerd zijn. Als je een skill alleen-autonoom of alleen-expliciet maakt, moeten je gebruikers weten waarom.

Dit is waarom SkillProof bestaat. Van de 743 skills die we hebben verwerkt, presteerden er 31 daadwerkelijk slechter dan het gebruik van pure Claude. Veel van deze mislukkingen waren niet te wijten aan slechte code, maar aan een slecht geconstrueerde SKILL.md frontmatter die ervoor zorgde dat de skill op het verkeerde moment werd geactiveerd, of helemaal niet. Nog eens 204 skills slaagden voor onze tests, maar vereisten een niet-voor de hand liggende setup, vaak gerelateerd aan het begrijpen hoe de aanroepflags waren ingesteld. We publiceren deze bevindingen – de successen en de mislukkingen – omdat de ware waarde van een skill wordt bepaald door de prestaties in de echte wereld, niet alleen door de code.

Het vinden van skills die dit goed doen, is het doel van onze directory. Een goed geconfigureerde skill zoals een Codebase Summarizer zal een precieze beschrijving en verstandige aanroepinstellingen hebben, waardoor het kan functioneren als een betrouwbare uitbreiding van het model.

Je kunt alle 508 skills die onze tests hebben doorstaan bekijken in onze catalogus. Elke vermelding bevat de exacte SKILL.md frontmatter die is gebruikt en ons oordeel over de effectiviteit ervan. Zie zelf hoe een goed geconfigureerde, beproefde skill eruitziet.