Så skriver du en Claude-skill (SKILL.md-struktur + verkliga exempel)

Så skriver du en Claude-skill på en mening: skapa en mapp, lägg en SKILL.md-fil i den, och skriv en description som är bra nog för att Claude ska veta när den ska plockas fram. Det är hela mekaniken. Det som faktiskt avgör om skillen fungerar är 1 024 tecken långt — det är description-fältet Anthropic använder för att välja ut din skill bland de 100-plus som kan vara laddade. Vi kör 25 skills i produktion i Techsy community-biblioteket, och de som failar gör det nästan aldrig på sina instruktioner. De failar på den enda raden.

Quick summary

Så skriver du en Claude-skill: (1) skapa en mapp namngiven efter skillen, (2) lägg till en SKILL.md med YAML-frontmatter (name och description) plus instruktioner i Markdown, (3) skriv description i tredje person med tydliga triggerord, (4) håll body under 500 rader och flytta detaljer till referensfiler, och (5) testa den med riktiga uppgifter innan du litar på den.

Vad en Claude-skill faktiskt är

En skill är en mapp med en SKILL.md-fil i roten. Mer krävs inte. Filen innehåller två saker: metadata som talar om för Claude när skillen ska användas, och instruktioner som talar om för Claude hur uppgiften ska göras när den väl är aktiverad.

Anledningen till att det förblir billigt är en laddningsmodell Anthropic kallar progressive disclosure. Vid start läser Claude bara name och description för varje installerad skill, ungefär 100 tokens vardera. Den läser hela SKILL.md först när din description matchar uppgiften framför den, och den läser eventuella bifogade referensfiler bara när instruktionerna pekar dit. Så du kan skeppa en stor, detaljerad skill utan att betala för den vid varje request. Du kan se en fungerande katalog över dessa i vårt skills-bibliotek.

SKILL.md-skelettet du kan kopiera

Varje skill utgår från samma form. Här är minimiversionen som fungerar:

---
name: reviewing-pull-requests
description: Reviews pull request diffs for bugs, security issues, and style. Use when the user asks for a code review, mentions a PR, or shares a diff.
---

# Reviewing Pull Requests

1. Read the diff and summarize what changed.
2. Flag likely bugs and edge cases, most severe first.
3. Check for hardcoded secrets and injection risks.
4. Note style issues only if they hurt readability.
5. End with a short verdict: approve, or request changes.

Två ----markörer omsluter frontmatter. Under dem är body ren Markdown. Över våra 25 skills är strukturen som överlevt verklig användning tråkig och konsekvent: en enradig titel, sedan en numrerad eller punktad procedur, sedan eventuella mallar eller exempel. När vi blev fyndiga med prosa skummade Claude igenom den. När vi skrev steg följde den dem. Om du vill studera färdiga exempel är 25 skills på Techsy community-sajten alla läsbara SKILL.md-filer du kan öppna och kopiera.

Frontmatter-regler: name och description

Frontmatter har exakt två obligatoriska fält, och båda har hårda gränser värda att memorera eftersom Anthropics tooling validerar dem.

En användbar konvention från Anthropics best-practices-guide: namnge skills i gerundium-form, alltså processing-pdfs, writing-documentation, analyzing-spreadsheets. Det läses bra i en lista och beskriver aktiviteten istället för ett vagt substantiv som helper eller utils. Håll name synkat med mappnamnet så de två aldrig glider isär. För de fullständiga valideringsreglerna är Anthropics best-practices-dokument sanningen.

Skriv en description som faktiskt triggar

Det här är avsnittet de flesta tutorials hoppar över, och det är det som avgör om ditt arbete faktiskt kommer till användning. Description injiceras i systemprompten, och Claude läser den för att avgöra om den ens ska ladda din skill. En perfekt body bakom en vag description är en skill som aldrig körs.

Tre regler gör skillnaden:

Skriv i tredje person. Description beskriver skillen, inte dig och inte användaren. Första- eller andrapersonsformuleringar förvirrar urvalet.

# Good
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDFs or when the user mentions forms or document extraction.

# Avoid
description: I can help you work with your PDF files whenever you need.

Ange både vad och när. "Processes data" säger ingenting om vilken uppgift som matchar. Namnge den konkreta förmågan och de konkreta triggarna.

Inkludera orden en användare faktiskt skulle skriva. Om folk säger "PR", "diff" och "code review", lägg de termerna i description. Claude matchar mot dem. Det här är den enskilt mest verkningsfulla ändringen du kan göra på en skill, och den kostar en rad.

Progressive disclosure och filstruktur

När en skill växer förbi en skärm eller två börjar struktur spela roll. Anthropics vägledning är konkret: håll SKILL.md-bodyn under 500 rader, och flytta allt längre till separata referensfiler som body länkar till. De filerna kostar noll tokens tills Claude faktiskt läser dem.

En skill som vuxit upp ser ut så här:

reviewing-pull-requests/
├── SKILL.md            # overview + the core procedure
├── security.md         # detailed security checklist (read when needed)
├── style-guide.md      # house style rules (read when needed)
└── scripts/
    └── diff_stats.py    # executed, never loaded into context

Två regler håller det här igång. Först, håll referenser en nivå djupt: länka varje fil direkt från SKILL.md, aldrig fil-till-fil-till-fil, eftersom Claude kanske bara förhandsgranskar djupt nästlade filer med en partiell läsning och missar innehåll. För det andra, ge varje referensfil längre än 100 rader en innehållsförteckning högst upp så att en partiell läsning ändå visar hela omfattningen. Anthropics engineering-genomgång om Agent Skills förklarar arkitekturen bakom det här om du vill ha den djupare modellen. När din skill börjar orkestrera verktyg är vår MCP-katalog en användbar följeslagare för att koppla in servrar.

Frihetsgrader (och när du ska lägga till skript)

Inte varje instruktion ska vara lika strikt. Matcha hur hårt du skriptar ett steg mot hur skört det steget är.

När ett steg är deterministiskt, skeppa ett skript istället för att be Claude generera kod varje gång. Ett bifogat skript är mer pålitligt, sparar tokens och håller sig konsekvent mellan körningar. Två vanor håller skripten hederliga: hantera fel inne i skriptet istället för att skjuta över det på Claude, och motivera varje konstant så du inte har oförklarade magiska tal. Det är också här skills skiljer sig från subagents, som har sin egen tool allowlist och systemprompt; vårt automations-bibliotek samlar exempel på subagents, och du kan jämföra de två tillvägagångssätten på Techsy AI automations-sidan.

Testa den: eval-driven skillutveckling

De bästa skill-författarna skriver tester innan de skriver dokumentation. Anthropic rekommenderar att bygga evals först: kör Claude på tre representativa uppgifter utan skillen, notera exakt var den failar, och skriv sedan bara tillräckligt med instruktion för att fixa de felen. Det håller dig kvar i att lösa verkliga problem istället för att dokumentera inbillade.

En praktisk loop:

1. Välj tre riktiga uppgifter skillen ska klara av.
2. Kör dem utan någon skill laddad och notera vad som går sönder.
3. Skriv den minimala SKILL.md som fixar de sakerna.
4. Testa igen med skillen laddad, gärna över Claude Haiku, Sonnet och Opus, eftersom en skill som guidar Opus bra kan vara underspecificerad för Haiku.
5. Se hur Claude navigerar filerna. Om den ignorerar en referens är din länk inte tydlig nog. Om den läser om samma fil hela tiden hör det innehållet hemma i SKILL.md.

För en handfast genomgång som bygger en skill från början till slut har vår systersajt en fullständig Claude Skills-tutorial; den passar bra ihop med skrivreglerna här. Du kan också stämma av ditt bygge mot våra enterprise-checklistor.

Vanliga misstag som dödar en skill

De flesta trasiga skills failar av en av ett fåtal orsaker:

• En description skriven för människor. Marknadsföringstext läser fint och triggar ingenting. Skriv för modellen: förmågor och triggers.
• För många alternativ. "Use pypdf, or pdfplumber, or PyMuPDF, or..." får Claude att tveka. Ge ett default med en enda escape hatch.
• Djupt nästlade referenser. Filer som länkar till filer som länkar till filer blir bara delvis lästa. Håll allt inom ett steg från SKILL.md.
• Tidskänsliga instruktioner. "Before August, do X" ruttnar. Lägg föråldrad vägledning i en hopfälld "old patterns"-notis istället.
• Windows-stilade sökvägar. Använd alltid framåtstreck; bakstreck går sönder på Unix-runners.
• Inkonsekvent terminologi. Välj ett ord för en sak ("field", inte "field/box/element/control") och använd det genomgående.

Mönstret bakom alla sex: en skill är en instruktionsuppsättning för en mycket kapabel läsare som inte har tålamod för tvetydighet. Säg den specifika saken, en gång.

Om författaren

Mert Batur Gurbuz är medgrundare av Techsy, University of Birmingham. Han och Techsy-teamet bygger AI-agenter, automationssystem och voice/SDR-pipelines för B2B-kunder, och underhåller det 25-skill-bibliotek som refereras genom hela den här guiden. Ta kontakt på LinkedIn. Fler byggguider finns på TECHSY.community-bloggen.

Vanliga frågor

Var ligger Claude skill-filerna?

En skill är en mapp som innehåller en SKILL.md-fil. I Claude Code hamnar personliga skills i ~/.claude/skills/{skill-name}/ och projektskills i .claude/skills/{skill-name}/. På API:et och claude.ai laddar du upp skill-mappen. Mappnamnet ska matcha name-fältet i frontmatter.

Måste skillens namn matcha mappnamnet?

Ja, håll dem identiska. name-fältet får vara max 64 tecken, får bara innehålla gemener, siffror och bindestreck, och ska undvika de reserverade orden "anthropic" och "claude". Att matcha mappnamnet förhindrar att de glider isär och gör skillen enkel att referera till i konversation och dokumentation.

Hur lång kan en SKILL.md vara?

Håll SKILL.md-bodyn under 500 rader för pålitlig prestanda. Det finns ingen hård tokengräns, eftersom referensfiler och skript inte kostar något förrän de läses, men en uppsvälld huvudfil konkurrerar med allt annat i context-fönstret. När du närmar dig 500 rader, dela upp detaljer i referensfiler länkade direkt från SKILL.md.

Varför triggar inte min skill?

Nästan alltid description. Claude väljer skills genom att matcha uppgiften mot description-fältet, så om din är vag eller skriven i första person aktiveras den aldrig. Skriv om den i tredje person, ange vad skillen gör och när den ska användas, och inkludera de exakta orden en användare skulle skriva för den uppgiften.

Vad är skillnaden mellan en skill, en subagent och en MCP-server?

En skill är paketerade instruktioner Claude laddar när det är relevant. En subagent är en separat agent med sin egen tool allowlist och systemprompt som hanterar en delegerad uppgift. En MCP-server exponerar externa verktyg och data över Model Context Protocol. Skills beskriver hur arbetet ska göras; MCP-servrar tillhandahåller vad det ska agera på.

Kan en Claude-skill köra kod?

Ja. Skills kan bifoga körbara skript som Claude kör som verktyg istället för att läsa in i context, vilket är billigare och mer pålitligt för deterministiskt arbete som validering eller filkonvertering. Gör avsikten tydlig i dina instruktioner: skriv "run this script" för körning, eller "see this script" när det är referensmaterial.

Fungerar skills i både API:et och claude.ai?

Ja, även om runtime skiljer sig. På claude.ai kan kodkörningsmiljön installera paket från npm och PyPI, medan Claude API inte har någon nätverksåtkomst eller runtime-paketinstallation. Lista nödvändiga paket i din SKILL.md och bekräfta att de finns tillgängliga i målmiljön innan du förlitar dig på dem.

Hur många skills kan Claude ha laddade samtidigt?

Många, eftersom bara varje skills name och description ligger i context vid start, ungefär 100 tokens styck. Det är därför description spelar så stor roll: Claude kan välja bland 100-plus skills, och en precis description är det som gör att den kan plocka ut din rätt. Hela bodyn laddas först när skillen väl är vald.