En teknisk dissekering av SKILL.md Frontmatter

Detta är en teknisk referens för frontmatter-blocket i en Claude SKILL.md-fil. Dess syfte är att förklara varje fält och dess inverkan på skillens beteende, särskilt hur den triggas. Informationen här är inte teoretisk; den baseras på vår direkta erfarenhet av att parsning, installation och testning av 743 unika skills som skickats in till SkillProof. Vår metodologi innebär att vi kör varje skill mot en standardiserad uppsättning verkliga programmeringsuppgifter, och en betydande del av den processen är att först förstå författarens avsikt som deklarerats i SKILL.md.

Vad vi har funnit är att detta lilla YAML-block är den mest kritiska och ofta missförstådda delen av en skills definition. En felkonfigurerad frontmatter kan tyst inaktivera en skill, vilket leder till att en författare felsöker sitt skript när problemet ligger i metadata. Denna guide dokumenterar vad varje fält gör, hur de interagerar och vilka konfigurationer som bör undvikas.

SKILL.md Frontmatter-blocket

Varje SKILL.md-fil börjar med ett YAML frontmatter-block, avgränsat av ---. Detta är en standardkonvention i många statiska webbplatsgeneratorer och dokumentationsverktyg, men i kontexten av en Claude skill är det inte bara för mänsklig konsumtion. Modellen parsar detta block för att förstå skillens identitet, förmågor och begränsningar.

Denna Claude skill YAML-sektion är kontrollpanelen för din skill. Basmodellen använder denna data för att bestämma om, när och hur de verktyg du har tillhandahållit ska exekveras. Att betrakta det som bara informationskommentarer är det första misstaget.

Ett minimalt frontmatter-block ser ut så här:

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

Vi kommer att granska vart och ett av dessa fält, plus de kritiska flaggorna för anropskontroll, baserat på mönster som observerats i de över 700 filer vi har analyserat.

Kärnidentitet: name och description

Dessa två fält definierar vad skillen är för både användaren och modellen. De har dock mycket olika roller i hur skillen triggas.

name

Fältet name är en unik sträng som identifierar skillen. Det används för explicit anrop när en användare skriver @ följt av skillens namn. Till exempel, @example-skill. Namnet måste vara en enda, icke-mellanslagad sträng. Konventionellt är det gemener och använder kebab-case.

Även om det är viktigt för identifiering och direkta användaranrop, har name liten eller ingen inverkan på modellens autonoma beslut att använda skillen. Modellen härleder inte förmåga från namnet git-history-analyzer. Den förlitar sig på description för det.

description

Detta är det enskilt viktigaste fältet i hela SKILL.md frontmatter. description är inte en kommentar. Det är den primära instruktionsuppsättningen som talar om för modellen när din skill är det lämpliga verktyget för en given uppgift. Det är API-dokumentationen för modellen själv.

I våra tester är kvaliteten på description den variabel med högst korrelation till en skills framgångspoäng. Vaga beskrivningar leder till inkonsekvent triggning, felaktig verktygsanvändning eller att skillen ignoreras helt. Detta är en frekvent grundorsak när en Claude skill inte triggas som förväntat.

En dålig description: "Analyzes code."

Detta är värdelöst. Det ger ingen information om vilken typ av analys, vilka indata den förväntar sig, eller vilka utdata den producerar. Modellen har ingen anledning att välja denna skill framför sina egna interna förmågor.

En funktionell 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."

Detta är effektivt eftersom det är precist och handlingsorienterat:

1. Indata: Det anges tydligt att den accepterar en filväg.
2. Åtgärder: Det specificerar vad den gör (läser filen, beräknar cyklomatisk komplexitet).
3. Verktyg: Det antyder till och med vilket verktyg den kommer att använda (py-complexity).
4. Utdata: Det definierar det förväntade returformatet (en lista över funktioner och deras komplexitetspoäng).

När modellen presenteras med en uppgift som "Kan du kontrollera komplexiteten hos funktionerna i main.py?", kan den matcha denna förfrågan direkt med de förmågor som beskrivs i den andra description. Den första description skulle ignoreras.

När du skriver din egen Claude skill, lägg större delen av din tid på att förfina description. Skriv den som om du dokumenterar en funktion för en annan ingenjör att använda, för det är precis vad du gör.

Verktygsbehörigheter: allowed-tools

Fältet allowed-tools är en lista över exekverbara filer som skillen får anropa. Detta fungerar som en säkerhetssandlåda. Modellen kan under inga omständigheter anropa ett verktyg som inte uttryckligen listas i denna array.

allowed-tools: [python, bash, jq]

Detta är en kritisk säkerhets- och tillförlitlighetsfunktion. Den förhindrar en skill från att exekvera godtycklig kod och definierar tydligt dess operativa omfång. Under våra tester verifierar vi att de listade verktygen är lämpliga för skillens angivna syfte. En skill som påstår sig vara en enkel JSON-formaterare men listar bash i allowed-tools är en varningssignal. Även om den kan använda bash för att skicka data till jq, ger den också skillen förmågan att köra vilket skal-kommando som helst, vilket är en onödig utökning av privilegier.

Vi har sett skills misslyckas eftersom de försöker anropa ett verktyg som inte är listat. Omvänt har vi flaggat skills för att begära alltför breda behörigheter som inte motiveras av deras description eller implementering. Principen om minsta möjliga privilegium gäller: tillåt endast de exakta verktyg som är nödvändiga för att skillen ska fungera.

Anropskontroll: user-invocable och disable-model-invocation

Dessa två booleska flaggor är mindre vanliga men har en djupgående inverkan på skillens beteende. De kontrollerar källan till anropet: kan en användare explicit anropa skillen, och kan modellen bestämma sig för att använda den på egen hand? Standardvärdet för båda är false om de utelämnas, men det effektiva standardbeteendet för en standard skill antar user-invocable: true och disable-model-invocation: false.

Deras interaktion kan vara förvirrande, så här är en sammanfattande tabell:

user-invocable	disable-model-invocation	Beteende	SkillProof Bedömning
true (eller utelämnad)	false (eller utelämnad)	Standard: Användare kan @ nämna; modellen kan anropa autonomt.	Den förväntade konfigurationen för de flesta skills.
false	false (eller utelämnad)	Endast autonom: Användare kan inte @ nämna; modellen kan anropa.	För bakgrundsuppgifter eller hjälpfunkioner.
true	true	Endast explicit: Användare måste @ nämna; modellen kan inte anropa.	För verktyg med sidoeffekter eller hög kostnad.
false	true	Inaktiverad: Varken användare eller modell kan anropa.	Trasig konfiguration. Vi flaggar dessa.

user-invocable

Denna flagga avgör om en användare direkt kan trigga skillen med en @-mention. Standardvärdet, true, är det beteende de flesta användare förväntar sig. En user-invocable claude skill är en du kan anropa vid behov.

Att sätta user-invocable: false innebär att skillen endast kan triggas av modellens autonoma beslutsprocess. Användaren kan inte tvinga den att köras. Detta är ett giltigt val för skills som fungerar som bakgrundshjälpare eller en del av en större kedja av verktyg, men det kan vara en stor källa till förvirring. Vi har testat flera skills där denna flagga var satt till false utan någon notis i dokumentationen. Användare som försökte @ nämna skillen skulle inte se något svar och anta att den var trasig. Om du sätter detta till false, måste du dokumentera det tydligt.

disable-model-invocation

Denna flagga är inversen av user-invocable. Den avgör om modellen får proaktivt välja skillen på egen hand.

Standardvärdet, false, tillåter modellen att använda skillen när dess description matchar användarens begäran.

Att sätta disable-model-invocation: true förbjuder modellen att använda skillen autonomt. Skillen kan endast köras om user-invocable också är true och användaren explicit @ nämner den. Detta är användbart för verktyg som är dyra, har betydande sidoeffekter (som att göra en nätverksförfrågan eller modifiera filer), eller kräver mycket specifik indata som modellen kanske inte kan härleda korrekt på egen hand.

Den tysta felförkombinationen

Den mest problematiska konfigurationen vi har upptäckt i våra tester är kombinationen av user-invocable: false och disable-model-invocation: true. Som tabellen visar kan en skill konfigurerad på detta sätt inte triggas på något sätt. Användaren blockeras från att anropa den, och modellen är förbjuden att välja den.

I vår granskning av över 700 SKILL.md-filer har vi hittat skills med exakt denna konfiguration. Ur användarens perspektiv är skillen installerad men helt icke-funktionell. Det är i praktiken död kod. I varje fall köar vi dessa skills för manuell inspektion. Ibland är det ett författarmisstag. Andra gånger verkar det vara ett sätt att tillfälligt inaktivera en skill i ett repository utan att ta bort den. Oavsett anledning är det ett fel att leverera en skill med denna konfiguration.

Praktiska implikationer från 743 skill-tester

Att förstå Claude skill frontmatter är ingen akademisk övning. Det är nyckeln till att bygga tillförlitliga och effektiva skills. Våra tester av 743 skills har förstärkt några viktiga sanningar:

1. description är triggern. Tid som läggs på att förfina den är aldrig bortkastad.
2. Standardinställningarna är oftast korrekta. De flesta skills bör vara användaranropbara och modell-anropbara.
3. Avvikelser måste vara avsiktliga och dokumenterade. Om du gör en skill endast autonom eller endast explicit, måste dina användare veta varför.

Det är därför SkillProof existerar. Av de 743 skills vi har behandlat presterade 31 faktiskt sämre än att använda vanlig Claude. Många av dessa misslyckanden berodde inte på dålig kod, utan på en dåligt konstruerad SKILL.md frontmatter som gjorde att skillen triggades vid fel tidpunkt, eller inte alls. Ytterligare 204 skills klarade våra tester men krävde icke-uppenbar konfiguration, ofta relaterad till att förstå hur anropsflaggorna var inställda. Vi publicerar dessa fynd – framgångarna och misslyckandena – eftersom en skills verkliga värde bestäms av dess prestanda i verkliga världen, inte bara dess kod.

Att hitta skills som gör detta rätt är syftet med vår katalog. En välkonfigurerad skill som en Codebase Summarizer kommer att ha en precis beskrivning och förnuftiga anropsinställningar, vilket gör att den kan fungera som en pålitlig utökning av modellen.

Du kan bläddra bland alla 508 skills som klarade våra tester i vår katalog. Varje listning inkluderar den exakta SKILL.md frontmatter som användes och vår bedömning av dess effektivitet. Se själv hur en välkonfigurerad, stridstestad skill ser ut.