Slik lager du en Claude-skill: SKILL.md på 10 min

Vi tester Claude-skills for å leve, hundrevis av dem så langt, og mønsteret er nedslående: de fleste skills som stryker i vår gjennomgang, feilet ikke fordi forfatteren ikke klarte å skrive instruksjoner. De feilet fordi skillen aldri lastet, eller lastet når den ikke skulle, eller var tre skills i en trenchcoat. Alt sammen fikserbart på forfattertidspunktet, ingenting fikserbart i ettertid ved å skrive en penere README.

Dette er tutorialen vi skulle ønske hver eneste innsender hadde lest først. Innen du er ferdig har du en fungerende skill: en sjekkliste for kodegjennomgang som presser Claude forbi "ser bra ut, kanskje endre navn på denne variabelen" til å sjekke grensetilfeller, feilhåndteringsveier og død kode. Det er et reelt eksempel med hensikt. Den beste fellesskapsskillen i vår kodekategori, Code Review Checklist, gjør akkurat dette og scorer 8/10 på output. Din vil ikke slå den på dag én, men du vil forstå hvert eneste valg den skillens forfatter tok.

10-minutters-løftet er ærlig med ett forbehold. Å skrive den første fungerende versjonen tar omtrent 10 minutter. Å teste den skikkelig tar 30 til. Hopper du over den andre delen, havner du blant halvparten av publiserte skills som ikke overlever møtet med en ny økt. Vi skrev obduksjonen i hvorfor halvparten av Claude-skills ikke fungerer, og vi vil helst ikke legge din til datasettet.

Har du aldri installert en skill og vet ikke hva det er, les hva Claude-skills er og hvordan installere dem først. Dette innlegget forutsetter at du har brukt minst én.

Steg 1: avgrens til én jobb

Før du skriver en eneste linje, bestem hva skillen din gjør. Halver det så.

Den desidert største feilen vi ser i testing er skills som prøver å gjøre alt. "Hjelper med kodekvalitet" høres ut som et rimelig omfang. Det er det ikke. En slik skill vil trigge på reviews, refaktorering, testskriving, lintespørsmål og arkitekturdebatter, som i praksis betyr at Claude ikke kan avgjøre når den skal lastes, så den laster uforutsigbart eller ikke i det hele tatt. Triggerproblemer er den vanligste grunnen til at en skill scorer lavt i vår metodologi, foran dårlige instruksjoner og ødelagte installasjoner. Ikke fordi triggering er den vanskeligste delen av å skrive skills, men fordi omfangsutglidning oppstrøms gjør det uløselig nedstrøms.

Én skill, én jobb. Her er testen: kan du fullføre setningen "bruk denne skillen når brukeren ber om ___" med én konkret verbfrase? "Gjennomgå en pull request eller diff" består. "Forbedre koden sin" stryker. Har setningen din "og" eller "eller" som kobler urelaterte aktiviteter, skriver du to skills. Skriv to skills. Mapper er gratis.

For vårt eksempel er omfanget: gjennomgå en diff eller PR for korrekthetsfeil, med en fast sjekkliste, og undertrykk stilpirk. Ikke "hjelp med reviews." Ikke "gjennomgå og fiks." Gjennomgå, rapporter, stopp.

Steg 2: SKILL.md-malen

En skill er en mappe med én påkrevd fil. Vår går i ~/.claude/skills/ for personlig bruk, eller .claude/skills/ inne i et repo hvis hele teamet skal få den:

review-checklist/
  SKILL.md          ← påkrevd, og ofte alt du trenger
  reference/        ← valgfritt, lastes bare når Claude bestemmer seg for å lese det
  templates/        ← valgfritt, filer instruksjonene dine peker til

Her er den fulle SKILL.md-en vi skal bygge, kommentert. Kopier den, les så kommentarene, for to av disse linjene betyr langt mer enn resten:

---
# 'name' er en identifikator: små bokstaver, bindestreker, ingen mellomrom.
# Claude ser den, men den styrer IKKE triggering.
name: review-checklist

# 'description' er det ENESTE Claude leser når den avgjør
# om skillen skal lastes. Alt under frontmatteren er
# usynlig inntil etter den avgjørelsen. Skriv den som en
# triggerbetingelse, ikke markedsføringstekst.
description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Runs a
  correctness-focused review checklist. Do NOT use for writing
  new code, fixing bugs the user already identified, or
  general refactoring requests.
---

# Sjekkliste for kodegjennomgang

Ved gjennomgang av en diff eller PR, arbeid deg gjennom denne
sjekklisten i rekkefølge. Rapporter kun funn; ikke fiks noe
med mindre det blir bedt om.

## Prosedyre

1. Les hele diffen før du kommenterer på noen linje.
2. For hver endrede funksjon, sjekk:
   - Off-by-one-risiko ved løkkegrenser og slice-indekser
   - Null/undefined-veier: hva skjer når input er tomt?
   - Feilhåndtering: blir feil svelget eller logget og kastet på nytt?
3. Sjekk for død kode endringen skaper: ubrukte imports,
   uoppnåelige grener, foreldreløse hjelpefunksjoner.
4. Sjekk samtidighet kun hvis diffen berører delt tilstand.
5. Verifiser at ny logikk har testdekning. Manglende tester er
   et funn, ikke en blokkering.

## Rapporteringsregler

- Maks 10 funn, sortert etter alvorlighetsgrad. Fant du 30,
  rapporter de 10 verste.
- Hvert funn trenger en fil, en linjereferanse, og ett forslag
  til fiks.
- IKKE rapporter: navnepreferanser, formatering, kommentarstil,
  eller noe en linter ville fanget.
- Hvis diffen er ren, si det i én setning. Ikke finn opp funn
  for å virke grundig.

Det er hele skillen. Ingen byggetrinn, ingen manifest, ingen registrering. Restart Claude-økten din, og den er live.

Frontmatteren har nøyaktig to felt som betyr noe. name er bokføring. description avgjør alt, og her er hvorfor: Claude beholder bare navn og beskrivelse for hver installerte skill i kontekst. Selve kroppen av SKILL.md-en din eksisterer ikke så vidt modellen angår før den leser beskrivelsen din, bestemmer "dette matcher det brukeren vil," og laster resten. En strålende 200-linjers sjekkliste bak en vag beskrivelse er en strålende 200-linjers sjekkliste ingen noensinne vil kjøre. I vår scoringsrubrikk vektes triggering like tungt som outputkvalitet nettopp av denne grunnen. En skill som trigger 40 % av tiden er myntkast med ekstra steg.

Steg 3: skriv triggerbeskrivelsen

Siden beskrivelsen er en triggerbetingelse, skriv den som en. Navngi formuleringene en reell bruker faktisk ville skrevet. Ta med det negative rommet, altså de nærliggende forespørslene der skillen skal holde seg stille.

Side om side, fra reelle innsendinger vi har testet (lett anonymisert):

Dårlig:

description: A powerful skill that helps improve code quality
  and catch issues early in the development process.

Bra:

description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Do NOT
  use for writing new code or fixing already-identified bugs.

Den dårlige beskriver fordelen. Den gode beskriver øyeblikket. Claude leser ikke beskrivelsen din for å bli overtalt; den mønstermatcher mot brukerens faktiske ord. "Review this PR" deler null vokabular med "helps improve code quality," så skillen sover gjennom sin egen brukssituasjon. Vi testet en innsending nesten identisk med det dårlige eksempelet: den utløste på 1 av 8 review-formede prompts. Etter å ha omskrevet beskrivelsen til å navngi formuleringer, samme kropp, utløste den på 8 av 8.

Et annet par, denne gangen om det negative rommet:

Dårlig:

description: Use for anything related to testing.

Bra:

description: Use when the user asks to write tests for
  existing code or asks what to test. Do NOT use when the
  user is doing TDD (writing tests before implementation) or
  debugging a failing test.

"Alt relatert til testing" er hvordan du ender opp med å kapre en feilsøkingsøkt. Overtriggering er stillere enn undertriggering og like skadelig: brukeren får sjekkliste-smakende svar på spørsmål som trengte noe annet, klandrer modellen, avinstallerer skillen.

Mekaniske regler som holder seg på tvers av alt vi har testet: navngi tre til fem konkrete brukerformuleringer, inkluder minst én "ikke bruk"-klausul, hold deg under omtrent 500 tegn, og bruk aldri ordene "kraftig," "omfattende," eller "hjelper med." Disse ordene korrelerer med dårlige triggerscorer i dataene våre så konsekvent at vi nå rykker til når vi ser dem.

Steg 4: skriv en kropp Claude faktisk følger

Når skillen først laster, er kroppen instruksjonssettet. Feilmodusen her er mer subtil enn triggering, men like vanlig: instruksjoner som inspirerer i stedet for å begrense. "Skriv en grundig, gjennomtenkt gjennomgang" er en motivasjonsplakat. Claude vil allerede være grundig og gjennomtenkt; det er standardatferden du prøver å forme, ikke formen.

Skillene som topper rangeringene våre er lister med begrensninger. Test-Driven Development forbyr implementasjon før en feilende test finnes, punktum. Vårt eksempel setter tak på 10 funn og forbyr stilpirk helt. Legg merke til hvor mange av linjene som starter med "ikke." Det er bevisst. Modeller overgenererer som standard, så de mest verdifulle instruksjonene er vanligvis subtraktive.

Tommelfingerregler for kroppen:

1. Nummererte prosedyrer slår prosa. "Arbeid deg gjennom dette i rekkefølge" gir Claude en ryggrad; avsnitt gir den vibber.
2. Angi stoppbetingelsen. Vår skill sier rapporter funn, ikke fiks. Uten den linjen vil Claude hjelpsomt begynne å skrive om koden, noe ingen ba om.
3. Lovfest outputformatet. Maksgrenser, påkrevde felt, hvordan et rent resultat ser ut. "Hvis diffen er ren, si det" forhindrer oppdiktede funn, en feil vi fanger konstant i review-type skills.
4. Legg sjeldent trengt detalj i reference/-filer. Har skillen din en 300-linjers stilguide som gjelder én gang i måneden, ikke lim den inn i SKILL.md der den brenner kontekst ved hver aktivering. Lagre den som reference/style-guide.md og skriv "når brukeren spør om X, les reference/style-guide.md først." Claude laster den ved behov.

Når legger du til skript og maler? Bare når instruksjoner ikke kan gjøre jobben. En skill som genererer en spesifikk konfigurasjonsfil bør levere en templates/config.yaml og si "kopier denne, endre deretter." En skill som trenger deterministisk atferd, si parsing av et lockfile-format, bør levere et skript og instruere Claude til å kjøre det fremfor å gjenimplementere det fra minnet hver gang. Men de fleste skills trenger verken det ene eller det andre. Vårt eksempel trenger ingen av delene. Hver fil i mappen er noe du nå vedlikeholder, så fortjen hver eneste én.

Steg 5: test den lokalt

Du er ikke ferdig når den fungerer én gang. "Den fungerte da jeg prøvde den" er teststandarden til hver eneste ødelagte skill vi noensinne har underkjent. Her er minimumsbatteriet, og det speiler tett hva vår metodologi kjører på innsendinger:

1. Ny økt. Restart Claude Code fullstendig. Skills laster ved øktstart; å teste i økten der du skrev den beviser ingenting.
2. Triggertest, positiv. Prøv tre forskjellige formuleringer en reell bruker ville skrevet: "review this PR," "can you check this diff before I merge," "look over my changes." Alle tre skal aktivere skillen. Du kan se at den utløste fordi outputen følger reglene dine (en tak-begrenset, alvorlighetssortert funnliste ser ikke ut som en standard review). Er du usikker, spør Claude direkte om den brukte skillen.
3. Triggertest, negativ. Prøv tre nærliggende forespørsler som IKKE skal utløse den: "fix this bug," "write a function that parses dates," "why is this test failing?" Dukker sjekklisten din opp i en feilsøkingsøkt, trenger beskrivelsen din en "ikke bruk"-klausul.
4. Baseline-sammenligning. Kjør samme review-prompt i en økt med skillen og én uten. Klarer du ikke skille outputene fra hverandre, tjener ikke skillen sin kontekst, og du bør skjerpe begrensningene. Dette er vår favoritttest fordi den er brutal. Omtrent en tredjedel av skillene vi gjennomgår stryker på den.
5. Ren installasjonstest. Har du tenkt å publisere: kopier mappen til en annen maskin (eller slett og klon på nytt), følg din egen README ordrett, og se om det fungerer. Manglende avhengighetsnotater dør her.

Hele batteriet tar 30 minutter. Det filtrerer bort omtrent 80 % av feilene vi ser, som er god avkastning for en halvtime.

Steg 6: kjør den gjennom validatoren

Før du publiserer, lim SKILL.md-en din inn i vår gratis skill-validator. Den scorer mot samme rubrikk vi bruker i gjennomganger: beskrivelseslengde og spesifisitet, tilstedeværelse av konkrete triggerformuleringer, negativt-rom-klausuler, begrensningstetthet i kroppen, formatlovgivning, åpenbare antimønstre som "kraftig" og "alt relatert til."

Det er statisk analyse, så behandle det deretter. Den fanger opp feilene som er synlige i teksten, som etter vår erfaring er de fleste av dem, men den kan ikke kjøre skillen din mot live prompts. En validator-godkjenning pluss steg 5-batteriet er den reelle terskelen. En validator-godkjenning alene er en lintet skill som kanskje fortsatt ikke trigger.

Vil du heller ha interaktiv hjelp enn en sjekker, er Anthropics Skill Creator verktøyet vi anbefaler. Den scoret 9,6 i vår testing, setter opp mappen, og beskrivelsesoptimaliseringssteget dens forbedret triggering målbart på våre egne interne skills. Å bruke en skill for å skrive skills høres ut som en spøk og fungerer likevel.

Steg 7: publiser og send inn

Publisering er et vanlig GitHub-repo. Layout-konvensjon:

your-repo/
  README.md           ← hva den gjør, installasjonskommando, ett eksempel
  review-checklist/
    SKILL.md
    reference/

Sett installasjonskommandoen i README som en kopier-lim-blokk, standardmønsteret er git clone pluss cp -r review-checklist ~/.claude/skills/. Legg deretter til claude-skills-emneknaggen på repoet. Dette er ikke pynt: emneknaggen er hvordan krypperen vår og alle andre kataloger oppdager nye skills. Et repo uten emneknagg er i praksis usynlig.

En README verdt å skrive har fire ting: én setning om hva skillen gjør, installasjonsblokken, ett før/etter-eksempel, og eventuelle avhengigheter. Før/etter-eksempelet gjør mer for adopsjon enn alt annet til sammen, fordi det er den eneste delen som viser fremfor å påstå.

Send den så inn til SkillProof. Testing og listing er gratis. Vi kjører innsendingen gjennom samme prosess som alt annet i katalogen: ren installasjon fra README-en din, triggerbatteri, baseline-sammenligning, output-scoring. Består den, blir den listet med en score, og du kan bygge inn et "SkillProof tested"-merke i README-en din. For en ukjent forfatter med et to dager gammelt repo er en uavhengig testdom forskjellen mellom "tilfeldig SKILL.md fra internett" og noe en fremmed faktisk vil installere. Består den ikke, får du feilnotatene, fikser det, og sender inn på nytt. Mange listede skills gikk gjennom to runder.

Vanlige feil vi ser i innsendinger

Etter noen hundre gjennomganger dukker de samme fem stadig opp.

Vage beskrivelser. Fortsatt førsteplass med god margin. Kan beskrivelsen din beskrive tre andre skills, beskriver den ingen av dem.

Kjøkkenvask-skillen. Én SKILL.md som håndterer reviews, commits, refaktorering og dokumentasjon. Hver jobb utvanner triggeren for de andre. Splitt den.

Gjentar modellstandarder. En kropp som sier "vær klar, vær nøyaktig, tenk steg for steg" legger ikke til noe. Claude gjør det uansett. Ville sletting av en linje ikke endret outputen, slett linjen.

Ingen negative begrensninger. Skills som bare sier hva som skal gjøres, aldri hva som skal stoppes. "Ikke gjør dette"-linjene er der mesteparten av atferdsendringen bor.

Utestede installasjonsinstruksjoner. README-en sier kopier én mappe; skillen avhenger stille av en annen skill eller en Python-pakke. Dør på vårt rene-installasjon-steg hver gang, og det er den mest unngåelige feilen på denne listen.

Ofte stilte spørsmål

Må jeg kunne kode for å lage en Claude-skill? Nei. En SKILL.md er markdown med en YAML-header. Leverer skillen din hjelpeskript, må du skrive dem, men rene instruksjonsskills, som er de fleste, er vanlig skriving. Skillen i dette innlegget inneholder null kode.

Hvor lang bør en SKILL.md være? Så kort som mulig mens den fortsatt begrenser atferd, typisk 30 til 150 linjer. Under omtrent 20 linjer legger den vanligvis ikke til noe utover standardatferd; over noen hundre bør du flytte detaljer til reference/-filer. Lengde er en kostnad du betaler per aktivering, ikke et kvalitetssignal.

Hvorfor trigger ikke skillen min? Beskrivelsen, nesten alltid. Sjekk at den navngir formuleringer en bruker faktisk ville skrevet fremfor å beskrive fordeler, og bekreft at du restartet økten etter installasjon, siden skills laster ved øktstart. Trigger den på noen formuleringer og ikke andre, legg de manglende til i beskrivelsen eksplisitt.

Hva er forskjellen mellom en skill og en MCP-server? En skill er instruksjoner: markdown som former hvordan Claude oppfører seg, ingen kode kjører noe sted. En MCP-server er et program som gir Claude nye evner, som å spørre databasen din. Er ideen din "Claude bør nærme seg X annerledes," er det en skill. Er den "Claude trenger tilgang til Y," er det MCP. Lengre versjon i Claude-skills vs MCP.

Kan jeg ta betalt for en Claude-skill? Det finnes ingen innebygd betalingsmekanisme; skills er filer, og det offentlige økosystemet kjører på åpne repos. Noen forfattere selger private skill-pakker til team som konsulentleveranser, som fungerer fordi verdien er den kodede ekspertisen, ikke filen. Alt ment for den offentlige katalogen bør være åpent lisensiert, siden ingen installerer en skill de ikke kan lese.

Avgrens én jobb, skriv triggeren som en regex i prosaform, begrens i stedet for å inspirere, og test i en ny økt før du forteller noen. Det er hele håndverket. Resten er iterasjon, og innsendingskøen er åpen.