Validera SKILL.md-filer för AI-agenter

Standarden Agent Skills definierar ett enkelt format för att ge AI-agenter modulära förmågor och arbetsflöden. En färdighet paketeras normalt i en egen mapp där filen SKILL.md utgör navet. Filen består av två huvudsakliga delar: ett YAML-metadatahuvud (frontmatter) överst och en textkropp formaterad i Markdown under avgränsaren.

När en AI-agent startar läser den inte hela filens instruktioner omedelbart. I stället läser agenten endast namnet och beskrivningen från frontmatter för att förstå vad färdigheten gör och i vilka situationer den ska användas. Först när en specifik användarfråga matchar beskrivningen läses hela Markdown-kroppen in i agentens sammanhangsfönster. Detta sparar kontextutrymme och gör det möjligt att installera dussintals olika färdigheter utan att överbelasta modellen med onödig text.

Ett korrekt formaterat metadatahuvud måste inledas och avslutas med tre bindestreck. Inom detta block granskar SKILL.md-validerare att syntaxen följer standarden och att datatyperna stämmer överens med specifikationen. Vid behov av att konvertera datastrukturer kan verktyg som konverterare från JSON till YAML eller YAML till JSON underlätta arbetet.

Fältet name måste matcha namnet på mappen som filen ligger i om ett mappnamn anges vid valideringen. Otillåtna tecken, som versaler eller understreck, leder direkt till ett valideringsfel.

Beskrivningen i description är den enskilt viktigaste raden i hela filen eftersom den fungerar som agentens beslutsgrund. Om beskrivningen är för vag eller saknar tydliga villkor kommer agenten sällan eller aldrig att ladda färdigheten.

En robust beskrivning innehåller två komponenter: vad verktyget utför och när agenten ska anropa det. Valideraren varnar om beskrivningen är kortare än 60 tecken och ger en notis om den saknar uttryck för användningssituationer, såsom engelska "use when" eller motsvarande instruktioner.

• Svag beskrivning: Kör tester och bygger projektet.
• Bra beskrivning: Kör enhetstester och bygger applikationen. Använd denna färdighet när användaren ber om testkörning, felanalys av kodbasen eller förberedelse inför release.

Genom att vara specifik kring filtyper, kommandon och scenarier minimeras risken för att agenten missar färdigheten när den behövs.

När agenten aktiverar en färdighet läses hela Markdown-kroppen in. För att inte förbruka för stor del av modellens sammanhangsfönster rekommenderar specifikationen att instruktionerna hålls under 500 rader och cirka 5 000 uppskattade tokens, beräknat schablonmässigt som fyra tecken per token.

Om arbetsflödet kräver omfattande dokumentation, API-scheman eller långa kodexempel bör detaljerna flyttas ut till undermappen references/. Referenser i texten ska alltid vara relativa och hållas på en nivå, till exempel references/schema.json.

Valideraren kontrollerar även att texten innehåller minst 20 ord och larmar om platshållare som TODO eller Lorem Ipsum finns kvar i dokumentet.

Standarden Agent Skills är skapad för att fungera över flera olika agentmiljöer, men vissa verktyg stödjer utökade fält. Claude Code kan exempelvis läsa nycklar som model och hooks direkt i frontmatter.

SKILL.md-validerare markerar dessa fält med informativa notiser i stället för fel. Det innebär att filen fungerar felfritt i Claude Code, men utvecklaren uppmärksammas på att andra agenter ignorerar fälten. Vill man spara egna anpassade parametrar utan att bryta mot standarden ska de placeras under fältet metadata.

Fältet allowed-tools är experimentellt i specifikationen och ska anges som en blankstegsseparerad sträng, inte som en YAML-lista. Valideraren varnar om fältet är felaktigt strukturerat.

Resultatet från SKILL.md-validerare presenteras i tre nivåer:

1. Fel (Errors): Direkta brott mot specifikationen, till exempel ogiltig YAML-syntax, saknat namn, felaktigt format på fältnamn eller att textkroppen är tom. En fil med fel laddas inte av kompatibla agenter.
2. Varningar (Warnings): Avvikelser från bästa praxis, såsom en mycket kort beskrivning, filstorlekar över 500 rader, absoluta länkar eller kvarlämnade platshållare.
3. Notiser (Notes): Information om verktygsspecifika tillägg eller saknade nyckelord i beskrivningen.

Ett godkänt resultat innebär noll fel. Valideringen sker uteslutande lokalt i webbläsaren, vilket innebär att inga instruktioner, konfidentiella interna rutiner eller API-nycklar skickas till externa servrar.