Slik skriver du en Claude-skill (SKILL.md-struktur + ekte eksempler)

Slik skriver du en Claude-skill på én setning: lag en mappe, legg en SKILL.md-fil i den, og skriv en beskrivelse god nok til at Claude vet når den skal ta den i bruk. Det er hele mekanismen. Delen som faktisk avgjør om skillen din fungerer, er 1 024 tegn lang — det er description-feltet Anthropic bruker for å plukke ut skillen din blant de 100-pluss som kan være lastet inn. Vi kjører 25 skills i produksjon i Techsy-fellesskapsbiblioteket, og de som feiler, feiler nesten aldri på instruksjonene. De feiler på den ene linjen.

Rask oppsummering

For å skrive en Claude-skill: (1) lag en mappe oppkalt etter skillen, (2) legg til en SKILL.md med YAML-frontmatter (name og description) pluss Markdown-instruksjoner, (3) skriv beskrivelsen i tredje person med tydelige utløserord, (4) hold hoveddelen under 500 linjer og flytt detaljer til referansefiler, og (5) test den med reelle oppgaver før du stoler på den.

Hva en Claude-skill egentlig er

En skill er en mappe med en SKILL.md-fil i roten. Mer trengs ikke. Filen inneholder to ting: metadata som forteller Claude når skillen skal brukes, og instruksjoner som forteller Claude hvordan oppgaven skal gjøres når den er aktivert.

Grunnen til at dette holdes billig, er en innlastingsmodell Anthropic kaller progressive disclosure. Ved oppstart leser Claude bare name og description for hver installerte skill, omtrent 100 tokens hver. Den leser hele SKILL.md-filen først når beskrivelsen din matcher oppgaven foran den, og den leser eventuelle vedlagte referansefiler bare når instruksjonene peker på dem. Slik kan du levere en stor, detaljert skill uten å betale for det ved hver eneste forespørsel. Du finner et fungerende katalog over disse i vårt Skills-bibliotek.

SKILL.md-skjelettet du kan kopiere

Hver skill starter fra samme form. Her er minimumsversjonen som fungerer:

---
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.

To ----markører omslutter frontmatteren. Under dem er hoveddelen ren Markdown. På tvers av våre 25 skills er strukturen som har overlevd reell bruk, kjedelig og konsekvent: én linje med tittel, deretter en nummerert eller punktvis prosedyre, deretter eventuelle maler eller eksempler. Når vi ble kreative med prosatekst, skummet Claude gjennom den. Når vi skrev steg, fulgte den dem. Hvis du vil studere ferdige eksempler, er de 25 skillsene på Techsy-fellesskapssiden alle lesbare SKILL.md-filer du kan åpne og kopiere.

Frontmatter-regler: navn og beskrivelse

Frontmatteren har nøyaktig to obligatoriske felt, og begge har harde grenser verdt å huske fordi Anthropics verktøy validerer dem.

En nyttig konvensjon fra Anthropics beste-praksis-guide: gi skills navn i gerundiumsform, altså processing-pdfs, writing-documentation, analyzing-spreadsheets. Det leses godt i en liste og beskriver aktiviteten i stedet for et vagt substantiv som helper eller utils. Hold name identisk med mappenavnet slik at de to aldri sklir fra hverandre. For de fullstendige valideringsreglene er Anthropics beste-praksis-dokument den autoritative kilden.

Skriv en beskrivelse som faktisk utløses

Dette er avsnittet de fleste veiledninger hopper over, og det er det som avgjør om arbeidet ditt faktisk blir brukt. Beskrivelsen settes inn i systemprompten, og Claude leser den for å avgjøre om skillen din i det hele tatt skal lastes inn. En perfekt hoveddel bak en vag beskrivelse er en skill som aldri kjører.

Tre regler avgjør forskjellen:

Skriv i tredje person. Beskrivelsen beskriver skillen, ikke deg og ikke brukeren. Første- eller andrepersonsformulering forvirrer utvelgelsen.

# 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.

Angi både hva og når. «Processes data» forteller Claude ingenting om hvilken oppgave som matcher. Navngi den konkrete kapasiteten og de konkrete utløserne.

Ta med ordene en bruker faktisk ville skrevet. Hvis folk sier «PR», «diff» og «code review», bruk de begrepene i beskrivelsen. Claude matcher på dem. Dette er den enkeltendringen med størst effekt du kan gjøre på en skill, og den koster én linje.

Progressiv avdekking og filstruktur

Når en skill vokser forbi en skjerm eller to, begynner strukturen å bety noe. Anthropics anbefaling er konkret: hold SKILL.md-hoveddelen under 500 linjer, og flytt alt som er lengre, til separate referansefiler som hoveddelen lenker til. Disse filene koster null tokens inntil Claude faktisk leser dem.

En skill som har vokst seg stor, ser slik ut:

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

To regler holder dette fungerende. For det første: hold referanser ett nivå dypt — lenk hver fil direkte fra SKILL.md, aldri fil-til-fil-til-fil, fordi Claude kanskje bare forhåndsviser dypt nøstede filer med en delvis lesing og går glipp av innhold. For det andre: gi enhver referansefil på over 100 linjer en innholdsfortegnelse øverst, slik at en delvis lesing likevel viser hele omfanget. Anthropics tekniske gjennomgang av Agent Skills forklarer arkitekturen bak dette hvis du vil ha den dypere modellen. Når skillen din begynner å orkestrere verktøy, er vårt MCP-katalog en nyttig følgesvenn for å koble til servere.

Frihetsgrader (og når du bør legge til skript)

Ikke alle instruksjoner bør være like strenge. Tilpass hvor stramt du skripter et steg, til hvor sårbart det steget er.

Når et steg er deterministisk, lever et skript i stedet for å be Claude generere kode hver gang. Et medfølgende skript er mer pålitelig, sparer tokens og holder seg konsekvent mellom kjøringer. To vaner holder skript ærlige: håndter feil inne i skriptet i stedet for å overlate det til Claude, og begrunn hver konstant slik at du ikke har uforklarte magiske tall. Dette er også der skills skiller seg fra subagenter, som har sin egen verktøytillatelsesliste og systemprompt; vårt automasjonsbibliotek samler subagent-eksempler, og du kan sammenligne de to tilnærmingene på Techsys AI-automasjonsside.

Test den: evalueringsdrevet skill-utvikling

De beste skill-forfatterne skriver tester før de skriver dokumentasjon. Anthropic anbefaler å bygge evalueringer først: kjør Claude på tre representative oppgaver uten skillen, noter nøyaktig hvor den feiler, og skriv deretter bare nok instruksjon til å rette de feilene. Det holder deg til å løse reelle problemer i stedet for å dokumentere innbilte.

En praktisk løkke:

1. Velg tre reelle oppgaver skillen skal håndtere.
2. Kjør dem uten at skillen er lastet inn, og noter hva som går galt.
3. Skriv den minimale SKILL.md som retter de feilene.
4. Test på nytt med skillen lastet inn, helst på tvers av Claude Haiku, Sonnet og Opus, siden en skill som veileder Opus godt, kan være underspesifisert for Haiku.
5. Følg med på hvordan Claude navigerer i filene. Hvis den ignorerer en referanse, er lenken din ikke fremtredende nok. Hvis den leser den samme filen om og om igjen, hører innholdet hjemme i SKILL.md.

For en praktisk gjennomgang som bygger en skill fra start til slutt, har søstersiden vår en full Claude Skills-veiledning; den passer godt sammen med skrivereglene her. Du kan også følge byggingen din mot våre sjekklister for bedriftsbygging.

Vanlige feil som ødelegger en skill

De fleste ødelagte skills feiler av én av noen få grunner:

• En beskrivelse skrevet for mennesker. Markedstekst leser fint og utløser ingenting. Skriv for modellen: kapasiteter og utløsere.
• For mange alternativer. «Bruk pypdf, eller pdfplumber, eller PyMuPDF, eller …» får Claude til å nøle. Gi ett standardvalg med én enkelt reserveløsning.
• Dypt nøstede referanser. Filer som lenker til filer som lenker til filer, blir bare delvis lest. Hold alt én hopp unna SKILL.md.
• Tidsavhengige instruksjoner. «Før august, gjør X» blir foreldet. Legg utdatert veiledning i en sammenslått «gamle mønstre»-notis i stedet.
• Windows-stil stier. Bruk alltid skråstreker fremover; omvendte skråstreker bryter på Unix-kjørere.
• Inkonsekvent terminologi. Velg ett ord for én ting («felt», ikke «felt/boks/element/kontroll») og bruk det gjennomgående.

Mønsteret bak alle seks: en skill er et instruksjonssett for en svært dyktig leser som ikke har tålmodighet for tvetydighet. Si det spesifikke, én gang.

Om forfatteren

Mert Batur Gurbuz er medgründer av Techsy, University of Birmingham. Han og Techsy-teamet bygger AI-agenter, automasjonssystemer og voice/SDR-pipelines for B2B-kunder, og vedlikeholder biblioteket med 25 skills som det vises til gjennom hele denne guiden. Ta kontakt på LinkedIn. Flere byggeguider finnes på TECHSY.community-bloggen.

Ofte stilte spørsmål

Hvor ligger Claude-skillfilene?

En skill er en mappe som inneholder en SKILL.md-fil. I Claude Code legges personlige skills i ~/.claude/skills/{skill-name}/ og prosjektskills i .claude/skills/{skill-name}/. På API-et og claude.ai laster du opp skillmappen. Mappenavnet bør stemme overens med name-feltet i frontmatteren.

Må skillnavnet stemme overens med mappenavnet?

Ja, hold dem identiske. name-feltet må være 64 tegn eller kortere, bruke bare små bokstaver, tall og bindestreker, og unngå de reserverte ordene «anthropic» og «claude». Å la det stemme overens med mappenavnet forhindrer at de sklir fra hverandre, og gjør skillen enkel å referere til i samtale og dokumentasjon.

Hvor lang kan en SKILL.md være?

Hold SKILL.md-hoveddelen under 500 linjer for pålitelig ytelse. Det finnes ingen hard tokengrense, fordi referansefiler og skript ikke koster noe før de leses, men en oppblåst hovedfil konkurrerer med alt annet i kontekstvinduet. Når du nærmer deg 500 linjer, splitt detaljene i referansefiler som lenkes direkte fra SKILL.md.

Hvorfor utløses ikke skillen min?

Nesten alltid beskrivelsen. Claude velger skills ved å matche oppgaven mot description-feltet, så hvis din er vag eller skrevet i første person, aktiveres den aldri. Skriv den om i tredje person, angi hva skillen gjør og når den skal brukes, og ta med de eksakte ordene en bruker ville skrevet for den oppgaven.

Hva er forskjellen mellom en skill, en subagent og en MCP-server?

En skill er ferdigpakkede instruksjoner Claude laster inn når det er relevant. En subagent er en separat agent med sin egen verktøytillatelsesliste og systemprompt som håndterer en delegert oppgave. En MCP-server eksponerer eksterne verktøy og data over Model Context Protocol. Skills beskriver hvordan arbeidet skal gjøres; MCP-servere leverer hva det skal handles på.

Kan en Claude-skill kjøre kode?

Ja. Skills kan pakke med kjørbare skript som Claude kjører som verktøy i stedet for å lese inn i konteksten, noe som er billigere og mer pålitelig for deterministisk arbeid som validering eller filkonvertering. Gjør intensjonen eksplisitt i instruksjonene dine: skriv «kjør dette skriptet» for utførelse, eller «se dette skriptet» når det er referansemateriale.

Fungerer skills både i API-et og på claude.ai?

Ja, selv om kjøretidsmiljøet er forskjellig. På claude.ai kan kjøremiljøet for kode installere pakker fra npm og PyPI, mens Claude API ikke har nettverkstilgang eller pakkeinstallasjon under kjøring. List opp nødvendige pakker i SKILL.md-filen din, og bekreft at de er tilgjengelige i målmiljøet før du stoler på dem.

Hvor mange skills kan Claude ha lastet inn samtidig?

Mange, fordi bare hver skills navn og beskrivelse ligger i konteksten ved oppstart, omtrent 100 tokens per stykk. Det er derfor beskrivelsen betyr så mye: Claude kan velge blant 100-pluss skills, og en presis beskrivelse er det som gjør at den velger din riktig. Hele hoveddelen lastes først inn når skillen er valgt.