Huomaatko liittäväsi Claude Codeen saman tarkistuslistan joka kerta ennen julkaisua? Tai kirjoittavasi kolmatta kertaa samalla viikolla, miten projektisi API-reitit nimetään? Siinä kohtaa kannattaa tehdä skill.
Skill on kansio, jossa on SKILL.md-tiedosto. Kirjoitat ohjeen kerran, ja Claude ottaa sen käyttöön itse, kun pyyntösi sopii kuvaukseen. Voit myös ajaa sen suoraan komennolla /skillin-nimi.
Tässä oppaassa teet ensimmäisen skillin, käyt läpi frontmatterin tärkeät kentät ja näet, milloin skill on parempi valinta kuin CLAUDE.md tai hook.
Mikä on Claude Code skill?
Skill on ohje, joka laajentaa sitä, mitä Claude osaa tehdä projektissasi. Se koostuu kahdesta osasta. Alussa on YAML-frontmatter ----merkkien välissä, ja se kertoo, milloin skilliä käytetään. Sen jälkeen tulee tavallista Markdownia, eli ohjeet, joita Claude noudattaa.
Anthropicin dokumentaation mukaan skill kannattaa tehdä, kun liität samaa ohjetta, tarkistuslistaa tai monivaiheista menettelyä keskusteluun yhä uudestaan. Toinen hyvä merkki on CLAUDE.md, jonka jokin osio on kasvanut tiedosta vaiheittaiseksi ohjeeksi.
Tärkein ero CLAUDE.md-tiedostoon on lataushetki. CLAUDE.md luetaan joka istunnossa kokonaan. Skillin sisältö latautuu vasta, kun skilliä käytetään, joten pitkäkään ohje ei vie kontekstia ennen kuin sitä tarvitaan.
Claude Coden skillit noudattavat avointa Agent Skills -standardia, jota muutkin tekoälytyökalut käyttävät. Claude Code lisää standardiin omia ominaisuuksia, kuten käynnistyksen rajaamisen ja skillin ajamisen subagentissa.
Näin teet ensimmäisen skillin
Tehdään skill, joka tiivistää gitin keskeneräiset muutokset ja nostaa esiin riskit. Se on hyvä ensimmäinen skill, koska se toimii missä tahansa git-projektissa.
1. Luo kansio. Omat skillit sijaitsevat kotihakemistossa, joten ne toimivat kaikissa projekteissasi:
mkdir -p ~/.claude/skills/tiivista-muutokset
2. Kirjoita SKILL.md. Tallenna tämä tiedostoon ~/.claude/skills/tiivista-muutokset/SKILL.md:
---
description: Tiivistää gitin keskeneräiset muutokset ja nostaa esiin riskit. Käytä, kun käyttäjä kysyy mitä on muuttunut, pyytää commit-viestiä tai haluaa katselmoida diffin.
---
## Nykyiset muutokset
!`git diff HEAD`
## Ohjeet
Tiivistä yllä olevat muutokset kahteen tai kolmeen kohtaan. Listaa sen jälkeen riskit, kuten puuttuva virheenkäsittely, kovakoodatut arvot tai testit, jotka pitää päivittää. Jos diff on tyhjä, kerro ettei keskeneräisiä muutoksia ole.
Rivi !`git diff HEAD` on dynaamista kontekstia. Claude Code ajaa komennon ennen kuin Claude näkee skillin ja korvaa rivin komennon tulosteella. Claude saa siis oikean diffin eikä joudu arvaamaan.
3. Testaa. Avaa jokin git-projekti, muokkaa yhtä tiedostoa ja käynnistä Claude Code komennolla claude. Kysy sitten:
Mitä olen muuttanut?
Kysymys vastaa kuvausta, joten Claude ottaa skillin käyttöön itse. Voit myös ajaa sen suoraan:
/tiivista-muutokset
Kansion nimestä tulee komento. Jos frontmatterissa on name-kenttä, komento tulee siitä.
Mihin Claude Code skillit tallennetaan
Kansio ratkaisee, missä istunnoissa skill on käytössä:
| Sijainti | Polku | Toimii |
|---|---|---|
| Oma | ~/.claude/skills/nimi/SKILL.md | kaikissa projekteissasi tällä koneella |
| Projekti | .claude/skills/nimi/SKILL.md | tässä repossa, myös tiimiläisillä kun viet sen gitiin |
| Sisäkkäinen | alikansio/.claude/skills/nimi/SKILL.md | kun Claude työskentelee alikansion tiedostojen parissa |
| Plugin | plugin/skills/nimi/SKILL.md | missä plugin on käytössä, nimellä /plugin-nimi:nimi |
| Organisaatio | hallinnoitujen asetusten kansio | kaikilla, joille organisaatio sen jakaa |
Monorepossa Claude Code lataa projektin skillit siitä kansiosta, jossa käynnistät sen, ja jokaisesta yläkansiosta repon juureen asti. Jos käynnistät Clauden kansiossa packages/frontend, saat myös juuren skillit.
Jos kahdella skillillä on sama nimi, organisaation skill voittaa oman ja oma voittaa projektin skillin. Skill voittaa myös samannimisen tiedoston kansiossa .claude/commands.
Claude Code seuraa skillikansioita, joten kun lisäät tai muokkaat skilliä, muutos tulee käyttöön samassa istunnossa ilman uudelleenkäynnistystä. Jos luot kokonaan uuden skills-kansion, jota ei ollut istunnon alkaessa, aja /reload-skills. Komento /skills listaa kaikki käytössä olevat skillit.
SKILL.md:n frontmatter
Kaikki kentät ovat vapaaehtoisia, mutta description kannattaa kirjoittaa aina, koska sen perusteella Claude päättää, milloin skill otetaan käyttöön. Tärkeimmät kentät:
| Kenttä | Mitä se tekee |
|---|---|
name | komennon nimi /-valikossa, oletuksena kansion nimi |
description | mitä skill tekee ja milloin sitä käytetään |
when_to_use | lisää käyttötilanteita tai esimerkkipyyntöjä kuvauksen perään |
argument-hint | vihje argumenteista automaattitäydennykseen, esimerkiksi [issue-numero] |
disable-model-invocation | true estää Claudea käynnistämästä skilliä itse |
user-invocable | false piilottaa skillin /-valikosta, jolloin vain Claude käyttää sitä |
allowed-tools | työkalut, joita Claude saa käyttää kysymättä sillä vuorolla |
context | fork ajaa skillin omassa subagentissa |
agent | subagentin tyyppi, kun context: fork on käytössä |
paths | glob-kuviot, joihin osuvien tiedostojen kanssa skill latautuu itsestään |
model | malli, jota käytetään sillä vuorolla, kun skill on käytössä |
Kenttien nimet pitää kirjoittaa täsmälleen oikein. Dokumentaation mukaan Claude Code ohittaa tuntemattoman kentän ilmoittamatta virheestä, joten kirjoitusvirhe näkyy vain siinä, ettei mitään tapahdu.
Kuvauksessa avainsanat kannattaa laittaa alkuun. description ja when_to_use lyhennetään skillilistauksessa yhteensä 1 536 merkkiin, ja jos skillejä on paljon, Claude Code voi pudottaa vähiten käytettyjen skillien kuvauksia listauksesta kokonaan.
Näin kirjoitat kuvauksen, joka osuu
Kuvaus on skillin tärkein rivi. Jos se on liian yleinen, Claude ei tunnista oikeaa hetkeä, tai skill käynnistyy silloinkin, kun et sitä halua.
Vertaa näitä kahta:
description: Auttaa testien kanssa
description: Kirjoittaa Vitest-testit React-komponentille tämän projektin mallin mukaan. Käytä, kun käyttäjä pyytää testejä komponentille, kysyy testikattavuudesta tai lisää uuden komponentin kansioon src/components.
Ensimmäinen ei kerro, mitä testejä, millä työkalulla tai milloin. Toinen kertoo, mitä skill tekee, ja luettelee tilanteet niillä sanoilla, joita oikeasti käyttäisit pyytäessäsi asiaa. Dokumentaatio neuvoo juuri tätä: kuvauksessa pitää olla avainsanat, jotka käyttäjä luontevasti sanoisi.
Jos skill käynnistyy liian herkästi, tarkenna kuvausta ennen kuin estät automaattisen käytön kokonaan. Jos skill ei käynnisty, kokeile ensin sanoa pyyntösi kuvauksen sanoin. Silloin näet, onko vika kuvauksessa vai jossain muualla.
Pidä itse ohje lyhyenä
Kun skill on ladattu, sen sisältö pysyy kontekstissa koko loppukeskustelun ajan. Jokainen rivi maksaa siis tokeneita joka vuorolla. Dokumentaatio neuvoo kertomaan, mitä tehdään, eikä selittämään pitkästi miksi tai miten.
Dokumentaatio käyttää skilleille samaa testiä kuin CLAUDE.md-tiedostolle: pidä mukana vain se, mitä Claude ei pysty päättelemään koodista itse. Jos Claude osaisi asian ilman riviä, rivi voi lähteä. Pitkät taustatiedot, API-kuvaukset ja esimerkkikokoelmat kannattaa siirtää omiin tiedostoihinsa skill-kansioon, josta Claude lukee ne vain tarvittaessa.
Milloin Claude lataa skillin
Tavallisessa istunnossa Clauden kontekstissa on lista skillien nimistä ja kuvauksista. Itse ohjeet latautuvat vasta, kun skill otetaan käyttöön. Kun kysyt jotain, Claude vertaa pyyntöäsi kuvauksiin ja käyttää skilliä, jos se sopii.
Kahdella kentällä voit rajata, kuka skillin käynnistää:
| Frontmatter | Sinä voit käynnistää | Claude voi käynnistää | Mitä kontekstissa on |
|---|---|---|---|
| (oletus) | kyllä | kyllä | kuvaus aina, koko skill kun se käynnistetään |
disable-model-invocation: true | kyllä | ei itse | ei kuvausta, koko skill kun käynnistät sen |
user-invocable: false | ei | kyllä | kuvaus aina, koko skill kun se käynnistetään |
disable-model-invocation: true kuuluu kaikkiin skilleihin, joilla on sivuvaikutuksia: julkaisu, commit, viestin lähetys. Et halua Clauden päättävän julkaista, koska koodi näyttää valmiilta.
user-invocable: false sopii taustatietoon. Esimerkiksi skill, joka selittää vanhan järjestelmän toimintaa, on Claudelle hyödyllinen, mutta sinulle se ei ole komento, jota ajaisit.
Kun skill on ladattu, sen sisältö pysyy keskustelussa seuraavillakin vuoroilla. Claude Code ei lue tiedostoa uudelleen. Kirjoita siis ohjeet niin, että ne pätevät koko tehtävän ajan: "aja testit jokaisen muutoksen jälkeen" toimii paremmin kuin "aja testit".
Kontekstin tiivistyksessä Claude Code liittää käytetyt skillit takaisin tiivistelmän perään, mutta säilyttää jokaisesta vain alun, enintään 5 000 tokenia. Laita siis tärkeimmät ohjeet SKILL.md:n alkuun.
Esimerkki: julkaisuskill argumenteilla
Tämä projektin skill ajaa tarkistukset ennen julkaisua. Tallenna se tiedostoon .claude/skills/julkaise/SKILL.md:
---
name: julkaise
description: Tarkistaa ja julkaisee sovelluksen annettuun ympäristöön
argument-hint: [staging|production]
disable-model-invocation: true
allowed-tools: Bash(pnpm lint) Bash(pnpm test *) Bash(pnpm build) Bash(git status *)
---
Julkaise sovellus ympäristöön $ARGUMENTS.
1. Aja git status. Jos on committaamattomia muutoksia, pysähdy ja kerro niistä.
2. Aja pnpm lint ja pnpm build. Jos jompikumpi epäonnistuu, pysähdy ja näytä virhe.
3. Aja pnpm test. Älä ohita epäonnistuneita testejä.
4. Kerro, mitä ollaan julkaisemassa, ja odota vahvistusta ennen varsinaista julkaisua.
Nyt /julkaise staging korvaa $ARGUMENTS-kohdan sanalla staging. Jos haluat argumentit erikseen, $0 on ensimmäinen ja $1 toinen. Esimerkiksi /siirra-komponentti Hakukentta JavaScript TypeScript antaa skillille kolme arvoa.
allowed-tools antaa luvan ajaa listatut komennot kysymättä, mutta vain sillä vuorolla, jolla skill käynnistetään. Lupa päättyy, kun lähetät seuraavan viestin. Kenttä ei rajaa muita työkaluja, eli lupa-asetuksesi pätevät edelleen kaikkeen muuhun.
Esimerkki: projektin konventiot polun mukaan
Kaikki skillit eivät ole tehtäviä. Osa on tietoa, jota Claude soveltaa työnsä ohessa. Tämä skill latautuu itsestään, kun Claude käsittelee API-reittien tiedostoja:
---
name: api-konventiot
description: Tämän projektin API-reittien nimeäminen, virhemuodot ja validointi
paths: src/app/api/**
user-invocable: false
---
Kun kirjoitat tai muokkaat API-reittiä:
- Reitin nimi on monikossa ja pienillä kirjaimilla, esimerkiksi /api/tilaukset
- Virheet palautetaan muodossa { "error": "viesti" } ja oikealla HTTP-statuksella
- Jokainen POST-pyyntö validoidaan zodilla ennen käsittelyä
- Älä palauta tietokannan virheviestejä käyttäjälle
paths rajaa automaattisen latauksen tiedostoihin, jotka osuvat kuvioon. Kuviot lasketaan Clauden nykyisestä työhakemistosta.
Tukitiedostot ja skriptit
Skill-kansiossa voi olla muitakin tiedostoja kuin SKILL.md. Näin varsinainen ohje pysyy lyhyenä, ja pitkä viitemateriaali latautuu vasta, kun Claude sitä tarvitsee:
julkaise/
├── SKILL.md
├── tarkistuslista.md
└── scripts/
└── tarkista-env.sh
Kerro SKILL.md:ssä, mitä kukin tiedosto sisältää ja milloin sitä tarvitaan, esimerkiksi Katso tarkistuslista tiedostosta [tarkistuslista.md](tarkistuslista.md). Dokumentaatio suosittelee pitämään SKILL.md:n alle 500 rivissä.
Skriptiin viitataan muuttujalla ${CLAUDE_SKILL_DIR}, joka osoittaa skillin kansioon. Silloin skripti löytyy riippumatta siitä, missä kansiossa Claude on:
---
name: tarkista-env
description: Tarkistaa, että kaikki tarvittavat ympäristömuuttujat on asetettu
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/tarkista-env.sh)
---
Aja `${CLAUDE_SKILL_DIR}/scripts/tarkista-env.sh` ja raportoi puuttuvat muuttujat.
Koska sama muuttuja on sekä ohjeessa että allowed-tools-säännössä, Claude voi ajaa skriptin ilman lupakyselyä.
Skill omassa subagentissa
Kun frontmatterissa on context: fork, Claude Code käynnistää uuden subagentin ja antaa sille skillin sisällön tehtäväksi. Subagentti ei näe keskusteluhistoriaasi, joten skillin ohjeiden on oltava riittävät sellaisenaan. Kentällä agent valitaan subagentin tyyppi, esimerkiksi Explore.
Oletuksena tällainen skill ajetaan taustalla, ja voit jatkaa työtä sillä aikaa. Tulos tulee keskusteluun, kun se on valmis. Jos haluat odottaa tulosta samalla vuorolla, lisää background: false.
Tämä sopii vain skilleille, joissa on selkeä tehtävä. Pelkkiä konventioita sisältävä skill ei tee subagentissa mitään hyödyllistä, koska siinä ei ole mitään tehtävää.
Skill, CLAUDE.md vai slash-komento?
| CLAUDE.md | Skill | Vanha komentotiedosto | |
|---|---|---|---|
| Tiedosto | CLAUDE.md | .claude/skills/nimi/SKILL.md | .claude/commands/nimi.md |
| Latautuu | joka istuntoon kokonaan | kun sitä käytetään | kun ajat sen |
| Claude lataa itse tarvittaessa | luetaan aina | kyllä, ellei estetty | ei, tämä on skillien lisäominaisuus |
| Tukitiedostot | ei | kyllä | ei |
| Sopii | faktoihin, jotka pätevät aina | menettelyihin ja pitkään ohjeeseen | vanhoihin komentoihin |
Omat slash-komennot on yhdistetty skilleihin. Tiedosto .claude/commands/deploy.md ja skill .claude/skills/deploy/SKILL.md luovat molemmat komennon /deploy. Vanhat komentotiedostot toimivat edelleen ja tukevat samaa frontmatteria lukuun ottamatta kenttiä name ja paths. Uudet kannattaa tehdä skilleinä. Sisäänrakennetut komennot kuten /compact ja /help käydään läpi oppaassa Claude Code slash-komennot.
CLAUDE.md:hen kuuluvat asiat, jotka Clauden pitää tietää joka istunnossa: build-komennot, kansiorakenne, "tee aina näin" -säännöt. Ohjeita CLAUDE.md:n kirjoittamiseen on oppaassa Miten kirjoittaa hyvä CLAUDE.md.
Entä jos Claude ohittaa skillin säännön välillä, ja sen on pakko pitää aina? Siirrä sääntö hookiksi. Skill on ohje, jota Claude tulkitsee. Hook on komento, jonka Claude Code ajaa joka kerta. Hookin voi myös määritellä skillin frontmatterin hooks-kentässä, jolloin se on voimassa siitä, kun skill käynnistetään, istunnon loppuun asti.
Valmiit skillit
Claude Codessa on mukana valmiita skillejä, kuten /code-review, /debug, /batch, /loop ja /claude-api. Ne ovat ohjeita, joiden mukaan Claude tekee työn omilla työkaluillaan. Osan Claude ottaa käyttöön itse, osa toimii vain, kun käynnistät ne. Jos teet projektiin samannimisen skillin, se korvaa valmiin komennon.
Valmiiden ja omien skillien lisäksi skillejä voi asentaa plugineina, jolloin ne näkyvät muodossa /plugin-nimi:skillin-nimi.
Skillin poistaminen tai piilottaminen
Oman tai projektin skillin saa pois poistamalla sen kansion, eli ~/.claude/skills/nimi tai .claude/skills/nimi. Claude Code pudottaa sen listalta samassa istunnossa. Pluginin mukana tulleen skillin saa pois poistamalla pluginin käytöstä /plugin-valikosta tai komennolla /plugin uninstall plugin-nimi@markkinapaikka.
Aina ei kannata poistaa. Jos skill on hyödyllinen mutta Claude käynnistää sen liian innokkaasti, lisää frontmatteriin disable-model-invocation: true. Skill pysyy tallessa, mutta käynnistyy vain, kun ajat sen itse.
Komennon /skills listan saa järjestykseen tokenimäärän mukaan painamalla t. Samasta näkymästä voit muuttaa skillin näkyvyyttä Claudelle ja /-valikkoon muokkaamatta tiedostoa. Se on nopea tapa siivota, jos skillejä on kertynyt paljon.
Kun skill ei toimi
Claude ei käytä skilliä. Tarkista, että kuvauksessa on ne sanat, joita oikeasti käytät pyytäessäsi asiaa. Kysy Claudelta "What skills are available?" tai aja /skills ja katso, näkyykö skill. Kokeile ajaa se suoraan komennolla /nimi.
Frontmatter on rikki. Jos YAML ei jäsenny, skill latautuu ilman kenttiä. Silloin /nimi toimii, mutta Claude ei osaa käyttää skilliä itse, koska kuvausta ei ole. Käynnistä Claude Code --debug-lipulla, niin näet jäsennysvirheen. Frontmatter luetaan vain, jos avaava --- on tiedoston ensimmäinen rivi.
Skill käynnistyy liian usein. Tarkenna kuvausta tai lisää disable-model-invocation: true.
Claude lakkaa noudattamasta skilliä kesken istunnon. Kontekstin tiivistyksen jälkeen skillistä voi olla jäljellä vain alku. Käynnistä skill uudelleen, niin koko sisältö palaa.
Turvallisuus: lue repon skillit
allowed-tools antaa skillille luvan käyttää työkaluja kysymättä. Dokumentaation mukaan Claude Code soveltaa projektin skillin allowed-tools-kenttää myös claude -p -ajossa kansiossa, jota et ole hyväksynyt luotettavaksi. Kun avaat jonkun toisen repon, lue sen .claude/skills-kansio ennen kuin annat Clauden työskennellä siellä.
Sama koskee dynaamista kontekstia. !`komento` ajaa komennon koneellasi ennen kuin Claude edes näkee skillin.
Mistä aloittaa
Käy läpi viime viikon keskustelusi Claude Coden kanssa. Mikä ohje toistui? Mikä tarkistuslista liitettiin useammin kuin kerran? Siitä tulee ensimmäinen skill.
Aloita yhdellä omalla skillillä kansiossa ~/.claude/skills, ja kun se toimii, tee projektille oma ja vie se gittiin. Lisää aiheesta löytyy Claude Code -oppaista, ja jos MCP-palvelimet ovat vielä vieraita, aloita oppaasta Claude Code MCP.