Så bygger jag en Claude Code Skill från grunden
En bra Claude Code Skill börjar inte med SKILL.md. Den börjar med en fråga: vilket återkommande arbete är tillräckligt stabilt för att kodifieras, men tillräckligt komplext för att det är jobbigt att förklara på nytt varje gång?
En bra Claude Code Skill börjar inte med SKILL.md. Den börjar med en fråga: vilket återkommande arbete är tillräckligt stabilt för att kodifieras, men tillräckligt komplext för att det är jobbigt att förklara på nytt varje gång?
Det är där Skills har gett mig mest. Jag använder dem inte som ett bibliotek av “superprompts”, utan som små driftmanualer för uppgifter som behöver samma workflow, regler, resurser och ibland scripts varje gång.
Anthropic beskriver, vid skrivande stund, custom Skills i Claude Code som filsystemsbaserade mappar med en obligatorisk SKILL.md, placerade projektlokalt under .claude/skills/ eller personligt under ~/.claude/skills/. Den konventionen kan ändras i takt med att dokumentationen uppdateras, så jag kontrollerar path-strukturen mot aktuella docs innan jag förlitar mig på den i ett skript. Det tekniska är enkelt. Det svåra är att göra innehållet tillräckligt fokuserat för att Claude både ska trigga rätt och följa workflowet konsekvent.
Börja med användningsfallen
Innan jag skapar filer skriver jag tre till fem konkreta prompts som Skillen ska klara.
För en content-skill kan det vara:
För en SQL-skill:
Det här gör scope konkret. Om användningsfallen kräver helt olika källor, outputs och risknivåer är det ofta två Skills, inte en.
Minsta användbara struktur
Jag börjar litet:
Sedan lägger jag bara till stödmappar när de gör workflowet bättre:
references/ är för sådant modellen kan behöva läsa. scripts/ är för deterministiska moment som bör köras likadant varje gång. assets/ är outputresurser, exempelvis mallar eller bilder, snarare än instruktioner.
Den vanligaste missen är att skapa alla mappar och sedan fylla dem för att strukturen “ska se professionell ut”. Varje fil kostar navigations- och underhållskomplexitet. Om en referens inte ändrar beteendet ska den bort.
Description är routinglogik
Frontmatter är litet men avgörande:
Jag skriver description som en kombination av:
- vad Skillen gör,
- vilken input den förväntar sig,
- när den ska användas,
- ibland vad den inte är till för om risken för feltrigger är hög.
“Helps with content” är nästan värdelöst. “Fact-check article drafts against an approved source ledger before publication” ger modellen ett tydligare routingbeslut.
SKILL.md är kontrollplanet
När Skillen triggas vill jag att entrypointen snabbt svarar på:
- Vad är uppgiften?
- Vilka inputs krävs?
- Vilken ordning ska stegen köras?
- Vilka hard-fails finns?
- Vilka resurser ska läsas när?
- Hur ser korrekt output ut?
Jag försöker därför skriva SKILL.md ungefär som en operativ manual:
Det räcker ofta. Den behöver inte innehålla en lärobok om faktagranskning.
Progressive disclosure gör Skills starkare
Anthropic beskriver Skills som dynamiskt laddade resurser. För mig betyder det att alltid-laddad kontext ska vara liten.
Om en Skill kan arbeta med fyra domäner gör jag hellre:
än en 900-raders SKILL.md som alltid följer med. Entry-pointen säger när rätt fil ska öppnas.
Samma princip gäller exempel och edge cases. Ett par representativa exempel kan ligga nära instruktionen. Ett större testbibliotek hör hemma separat.
Ett enkelt test för vad som hör hemma var
När jag är osäker på om något ska ligga i SKILL.md eller i en stödresurs ställer jag en enda fråga: behöver modellen detta för nästan varje körning? Om ja är det en kandidat för SKILL.md. Om nej hör det hemma i references/, examples/, evals/ eller ett script.
Min Humanizer-skill är ett konkret exempel. Kärnan behöver veta att fakta och säkerhetsgrad är låsta och hur redigeringsworkflowet ser ut. Den behöver inte bära hela forskningssyntesen om StoryScope i varje sakprosaredigering — den resursen laddas först när forskningsgränsen faktiskt är relevant. Det gör Skillen både mer precis och billigare i kontext.
Lägg determinism i scripts
När samma ömtåliga operation annars skulle beskrivas i naturligt språk om och om igen är ett script ofta bättre.
Exempel:
Skillen ska då säga kör scriptet, inte “återskapa ungefär samma logik i Python”.
Det ger tre vinster:
- samma regler varje gång,
- enklare testning,
- mindre tokenkostnad.
I min contentfabrik använder jag just den uppdelningen: modeller gör research, analys och redigering; scripts äger state transitions, required files och andra exakta kontroller.
Skriv hard-fails före stilpreferenser
Jag prioriterar instruktioner i ordningen:
Om Skillen både säger “skriv naturligt” och “ändra aldrig faktapåståenden” måste det vara fullständigt tydligt vilken regel som vinner.
För min Humanizer är innehållslås högre prioriterat än variation. För en finansiell Skill är verifierad data högre än att alltid leverera en rekommendation. För en content-skill är saknad evidens ett legitimt NOT READY.
Definiera ett output contract
“Ge mig en analys” är svårt att validera. Jag vill hellre ha ett kontrakt:
I textproduktion kan output fortfarande vara Markdown, men vissa delar bör vara strukturerade så att nästa steg vet vad det får lita på.
Det är extra viktigt när Skills komponeras. En researcher ska lämna ett paket som evidence auditor kan läsa utan att behöva gissa vad researchern menade.
Bygg negativa exempel
Jag tycker negativa exempel är undervärderade. De visar vad Skillen ska vägra eller lämna orört.
För en CV-skill:
För en research-skill:
En Skill som bara testats på happy paths är inte färdig.
Validera triggern separat från outputen
Jag testar två helt olika saker:
- Triggering — använder Claude Skillen när den borde?
- Execution — gör Skillen rätt sak när den väl laddats?
Om triggering är dålig ändrar jag description och scope. Om execution är dålig ändrar jag workflow, resurser eller evals. Att blanda ihop dem leder ofta till att man gör SKILL.md längre när det egentligen är metadata som är problemet.
Ett enkelt eval-bibliotek
Jag brukar skapa ett litet eval-set tidigt:
Varje verkligt fel jag hittar ska helst bli ett regressionstest. Det är så Skillen går från instruktion till förvaltad komponent.
För min contentmotor var ett sådant fel att Publisher Gate först kunde säga READY samtidigt som en obligatorisk freshness-recheck återstod. Efter post-mortem blev det en hard-fail: READY betyder publicerbar nu.
Skill vs CLAUDE.md vs subagent
Claude-ekosystemet har flera styrmekanismer. Jag använder en enkel tumregel:
CLAUDE.md— projektets alltid relevanta kontext och konventioner.- Skill — återanvändbart on-demand-workflow.
- subagent — isolerad roll med eget ansvar och ibland egna tools.
- hook/script — deterministisk kontroll eller automation.
Om en regel ska gälla varje kodändring hör den sannolikt hemma i projektkontexten. Om den gäller när jag gör en viss typ av audit är en Skill bättre. Om arbetet behöver separat kontext och tydlig handoff kan en subagent vara rätt.
Installera projektlokalt först
När jag utvecklar en Skill föredrar jag projektlokal installation:
Då versionshanteras den tillsammans med projektet, kan granskas i PR och påverkar inte alla andra repos. När beteendet är stabilt kan en mer generell Skill flyttas till personlig eller organisatorisk distribution.
Det är samma princip som med kodbibliotek: börja nära användningsfallet, generalisera efter att återanvändningen är bevisad.
Säkerhet: en Skill är exekverbar instruktion
En Skill som innehåller scripts eller verktygsinstruktioner är inte bara dokumentation. Den kan påverka vad agenten gör i miljön. Anthropic rekommenderar också försiktighet med Skills från okända källor.
Jag granskar därför minst:
- vilka scripts som körs,
- vilka paths de kan skriva till,
- vilka nätverks- eller verktygsanrop som tillåts,
- om instructions kan få agenten att läsa secrets,
- om Skillen försöker expandera sitt eget scope.
Det här är särskilt viktigt när man installerar från ett publikt repo.
Min byggordning
Min praktiska ordning är:
Jag försöker medvetet att inte börja på steg 8. Komplexitet ska förtjänas.
Vad som skiljer en Skill från en bra prompt
En bra prompt kan lösa en uppgift. En bra Skill ska kunna förvalta ett arbetssätt.
Det betyder att den måste kunna trigga rätt, veta vilka resurser som behövs, hantera edge cases, stoppa vid saknat underlag och överleva att modellen byts ut. Den blir mer som en liten programkomponent än en textsnutt.
Det är därför jag gillar Skills som format. De tvingar mig att flytta mitt eget kunnande från “jag vet ungefär hur jag brukar prompta Claude” till ett granskningsbart system av instruktioner, resurser, scripts och evals.
Hur jag felsöker en Skill som inte triggar
Om Claude inte använder Skillen börjar jag inte med att lägga fler instruktioner i body. Jag testar routing separat. Är description för vag? Överlappar den med en annan Skill? Beskriver den bara vad Skillen är, men inte när den ska användas?
Jag skapar ett litet trigger-set:
När Skillen klarar det går jag vidare till workflowet. Det sparar tid eftersom jag annars kan förbättra execution i timmar för en Skill som aldrig laddas på rätt uppgift.
Hur jag felsöker en Skill som triggar för ofta
Övertriggning är minst lika jobbigt. En bred “SEO skill” kan börja påverka varje artikel, sitemap och teknisk analys. Jag gör description smalare och delar hellre capabilityn.
De kan dela references, men de har olika triggers och outputs. Orchestratorn får komponera dem när uppgiften kräver flera steg.
Reference files behöver egna kontrakt
En referensfil ska inte bara heta notes.md. Entry-pointen ska veta varför den finns:
Det här gör progressive disclosure förutsägbart. Det minskar också risken att modellen läser en stor irrelevant fil och låter den dominera uppgiften.
Scripts behöver exit codes och tydlig stdout
Om en Skill kör scripts vill jag att de fungerar som riktiga CLI-komponenter. 0 betyder pass, icke-noll betyder fel. Maskinläsbar JSON är ofta bättre än femton rader mänsklig logg om nästa steg ska konsumera resultatet.
Agenten får då mindre utrymme att “tolka” ett valideringsfel som en rekommendation.
Skillen ska ha en stop rule
Många instruktioner beskriver vad modellen ska göra, men inte när den ska sluta. För redigering kan stop rule vara “sluta när ytterligare ändringar inte ger verifierbar tydlighets- eller kvalitetsvinst”. För research kan den vara “sluta när required claims har minst en kvalificerad primärkälla eller är explicit unresolved”.
Stop rules motverkar överarbete, överredigering och sökloopar. De är särskilt viktiga när agenten har web access eller code execution.
Release checklist
Innan jag delar en Skill vill jag att följande är sant:
Det är först där jag går från “en prompt som fungerar hos mig” till en komponent jag skulle låta någon annan installera.
Dokumentera varför Skillen finns. Jag lägger gärna en kort design note som inte laddas i varje körning men som förklarar varför capabilityn finns, vilka alternativ som avvisades och vilka risker som styrde designen. Sex månader senare är det annars lätt att se en konstig hard-fail och “förenkla” bort den utan att veta vilket verkligt fel den skapades för. Regressioner behöver kontext, inte bara testdata.
Håll examples små men representativa. Exempel styr mycket, men de kan också överstyra modellen. Jag använder hellre två tydliga exempel som demonstrerar format och boundary än tio nästan identiska outputs. Om examples-biblioteket växer flyttar jag det till evals eller references. Entry-pointen ska lära Claude principen, inte göra modellen till en nearest-neighbor-maskin mot ett stort exempelarkiv.
Vad som hör hemma i CLAUDE.md i stället
Projektets databasnamn, kodstandard, testkommando och “skriv aldrig direkt till production” är ofta alltid relevant projektkontext. Det ska inte dupliceras i varje Skill. Skillen kan hänvisa till projektkonventionen men bör bara innehålla capability-specifika regler. Duplicering skapar drift när en regel uppdateras på ett ställe men inte ett annat.
Vad som hör hemma i en subagent i stället
Om uppgiften behöver egen kontext, lång research eller separata tools kan en subagent vara bättre. Min contentfabrik är ett tydligt exempel: Researcher, Writer och Fact Checker är separata roller eftersom de inte bör dela samma arbetsminne eller permissions. Skills kan fortfarande preloada metodiken för respektive agent. Jag ser alltså inte Skill och subagent som konkurrenter; Skillen är kunskap/workflow, subagenten är en exekveringsgräns.
Varför jag håller references, evals och agents åtskilda
Mapparna svarar på tre olika frågor, inte en. references/ svarar på vad modellen behöver veta. evals/ svarar på hur jag vet att beteendet fungerar — testdata och bedömningslogik, inte instruktioner modellen ska försöka följa under normal körning. agents/ svarar på vem som äger jobbet: ansvar, verktyg, kontext och handoff, ofta med olika permissions för samma reference.
Blandar jag ihop dem uppstår dold coupling. En agentprompt som bär hela kunskapsbasen blir svår att återanvända. Eval-cases inbakade i normala instruktioner riskerar att modellen optimerar för testet snarare än för uppgiften. References som samtidigt definierar permissions gör ansvar otydligt. Mappstruktur löser inte arkitektur automatiskt, men den gör fel typ av koppling synlig.
Hur jag hanterar bakåtkompatibilitet
När Skillen används av scripts eller andra agents måste output contract versioneras. En ändring från status: PASS|FAIL till PASS|BLOCKED|FAIL kan bryta downstream-logik även om den mänskliga texten ser bättre ut. Därför behandlar jag schemaändringar som API-ändringar och ger dem tydliga versionsnoter. Det är ytterligare ett skäl att inte se Skills som bara prompts.
Hur jag namnger Skills. Namnet ska vara så kort att det går att förstå i en lista men så specifikt att det inte krockar med tio andra capabilities. Jag föredrar verb-/uppgiftsnära namn som sitemap-auditor, article-fact-checker eller sql-booking-analysis framför seo-helper eller marketing-expert. Ett bra namn gör katalogen begriplig för människor; description gör routing begriplig för modellen.
När references ska delas mellan Skills. Två Skills kan behöva samma source policy eller brandstandard. Jag undviker ändå osynliga hårda beroenden mellan kataloger om runtime inte uttryckligen stödjer dem. Ett bättre mönster är ett gemensamt, versionshanterat reference-paket som buildsteget kopierar in, eller en tydlig central projektresurs som båda Skills instrueras att läsa. Då är beroendet synligt och går att testa.
Hur jag testar efter modellbyte. En Skill som fungerade perfekt på en modellversion kan över- eller underfölja instruktioner på nästa. Därför kör jag regressionerna igen efter större modellbyte, särskilt negative evals och hard-fails. Jag behöver inte kräva identisk prosa. Jag kräver samma safety/fidelity och samma output contract. Om modellen blir bättre kan vissa kompensationsinstruktioner till och med tas bort; annars växer Skillen till ett fossil av gamla modellproblem.
Dokumentation för nästa person
En Skill är lyckad först när någon annan kan förstå varför den triggar, vilka filer som är auktoritativa och hur man reproducerar ett fel utan att fråga skaparen. Därför lägger jag en kort README eller design note bredvid själva runtime-instruktionen med utvecklingskommandon, eval-körning och releaseprocess. Den filen ska inte behöva laddas varje gång Skillen används, men den gör komponenten förvaltbar.
Den dokumentationen gör också code review enklare: förändringar kan granskas mot avsikten, inte bara mot om filen fortfarande validerar syntaktiskt.
Källor
Ett komplett mini-exempel
Anta att jag vill bygga en Skill som granskar sitemap-filer. Jag börjar inte med 300 rader SEO-teori. Jag skriver:
Sedan ett kort workflow: hämta sitemap, validera XML, jämför mot canonical inventory, flagga redirect/noindex/404, kontrollera split/size och producera åtgärdslista. Google-specifika regler hamnar i references/google-sitemap-rules.md; XML-validering hamnar i script. På så sätt kan jag uppdatera en teknisk regel utan att röra hela workflowet.
När jag delar en stor Skill
Ett tydligt tecken på att Skillen blivit för stor är att description måste räkna upp tio orelaterade triggers eller att entrypointen innehåller många “om användaren gör X, hoppa till avsnitt Y”. Då delar jag hellre efter capability. En orchestrator kan komponera flera små Skills om användaruppgiften faktiskt kräver en kedja. Det ger bättre triggering och tydligare evals än en mega-Skill som försöker vara expert på allt.
Min produktionschecklista
Jag kör samma produktionschecklista för den här typen av arbetsflöde som jag beskriver i Från research paper till fungerande AI-skill: versionerad input, provenance på externa fakta, spårbara first-hand-påståenden, uttryckbar osäkerhet och ett output som nästa komponent kan validera utan att tolka fri prosa.
- Claude Code — Extend Claude with Skills
- Claude Code — Feature overview: Skills vs subagents
- Claude Code — Create custom subagents