Claude skillek: így írjon SKILL.md fájlt, amely a megfelelő pillanatban töltődik be

A Claude skill egy mappa, amelynek gyökerében SKILL.md fájl van. A fájl YAML-frontmatterrel (fejlécblokkal) kezdődik, amely leírja, mit csinál a skill és mikor kell használni, ezt Markdown-utasítások követik. Claude a frontmattert induláskor olvassa be, az utasításokat akkor tölti be, amikor egy kérés illeszkedik a skillre, a csatolt fájlokat pedig csak akkor nyitja meg, ha egy lépés ezt igényli. A Claude Code, a Claude API és a claude.ai is támogatja az erre a formátumra épülő skilleket; a Claude Code az Agent Skills nyílt szabványon túlmenő mezőket is hozzáad.

A téma iránt nagy az érdeklődés. A SkillGild által elemzett Ahrefs-adatok szerint a „claude skills” és a „claude code skills” kifejezésekre egyenként mintegy 10 000 amerikai keresés érkezik havonta, a 2026. október 6-i exportálás szerint. Az oldalon már szerepel, miért érdemes skilleket használni, a kódoló ügynökök skill-munkafolyamatáról szóló cikkben. Ez az útmutató a készítésről szól: a könyvtárszerkezetről, minden frontmatter-mezőről a korlátaival, arról, hogyan dönti el a leírás, mikor töltődik be egy skill, hol vannak a skillek, hogyan működnek az argumentumok és az eszközjogosultságok, és hogyan tesztelhető egy skill. Minden korlát a Claude dokumentációból vagy a hivatkozott nyílt szabványból származik.

Mi a skill, és miben különbözik a prompttól?

A skill újrafelhasználható, fájlrendszer-alapú erőforrás, amely fachspecifikus tudást ad Claude-nak. A prompt egyetlen feladatra szóló, beszélgetésszintű útmutatás. A skill igény szerint töltődik be, így ugyanazt az útmutatást nem kell minden beszélgetésbe újra bemásolni (Agent Skills áttekintés). A skillek, a projektszabályok és az MCP-eszközök közötti választáshoz olvassa el a döntési mátrixról szóló cikket.

Az érdeklődés a magyarázatoktól a gyakorlati kérdések felé fordult. A SkillGild szerint a „claude skills” keresési volumene az Agent Skills 2025 októberi indítása után erősen nőtt, 2026 januárjában érte el a csúcsot, azóta pedig mintegy 62 százalékkal csökkent. A gyakorlati keresések viszont nőttek: a „how to create a claude skill” és változatai együtt havi mintegy 10 200 keresést tesznek ki (SkillGild-elemzés). A saját beállításomban mintegy 20 ügynök-skill van a ~/.agents/skills mappában, és ezek egyike a jev-decide.

Mit tartalmaz egy skill-könyvtár?

Csak a SKILL.md kötelező. A nyílt szabvány három opcionális könyvtárat határoz meg: a scripts/ futtatható kódnak való, a references/ az olyan dokumentációnak, amelyet Claude igény szerint olvas, az assets/ pedig sablonoknak, képeknek és adatfájloknak. Egy skill ezen kívül más fájlokat és könyvtárakat is tartalmazhat (Agent Skills specifikáció).

Az útmutató három szabálya formálja az elrendezést. Minden referenciafájl legyen fókuszált, mert az ügynökök igény szerint töltik be őket, a kisebb fájlok pedig kevesebb kontextust használnak. A fájlhivatkozások legfeljebb egy szinttel legyenek mélyebben a SKILL.md-nél: ha egy hivatkozott fájl egy másikra mutat, Claude csak részlegesen olvashatja, és információ maradhat ki. Az útvonalakban perjelet használjon, Windows alatt is, a fájlokat pedig a tartalmukról nevezze el, például form_validation_rules.md legyen a doc2.md helyett (legjobb gyakorlatok).

Milyen frontmatter-mezők vannak, és mik a korlátaik?

A nyílt szabvány két mezőt követel meg, a name-et és a description-t; a többi mező opcionális. A Claude Code minden mezőt opcionálisnak tekint, a description-t ajánlja, és saját mezőket ad a hívásra, az argumentumokra és az alügynökökre (subagent). A táblázat a leggyakrabban használt mezőket sorolja fel a specifikáció és a dokumentáció korlátaival.

A name szabályai szigorúak: 1–64 karakter kisbetűkből, számjegyekből és kötőjelekből, kötőjel nélkül az elején és a végén, és dupla kötőjel nélkül. A specifikáció azt is megköveteli, hogy a név megegyezzen a szülőkönyvtár nevével. A Claude Code engedékenyebb: a deploy-staging nevű könyvtár name: deploy beállítással /deploy néven hívható, vagyis a mező a parancs nevét adja meg (Claude Code dokumentáció).

Két részlet okozza a legtöbb néma hibát. A Claude Code a fel nem ismert mezőt hibaüzenet nélkül figyelmen kívül hagyja, így az elírt allowed-tools nem tesz semmit. A frontmattert csak akkor olvassa be, ha a nyitó --- a fájl első sora; ha a YAML nem értelmezhető, a skill üres metaadatokkal töltődik be, és Claude nem találja meg a leírása alapján. A specifikáció referenciakönyvtára, skills-ref validate ./my-skill formában futtatva, a frontmattert és a névszabályokat ellenőrzi.

Hogyan tartja olcsón a fokozatos betöltés a skilleket?

Claude három szakaszban tölti be a skillt, és minden szakasz csak akkor kerül kontextusba, ha szükség van rá. A metaadatok, skillenként mintegy 100 token, induláskor töltődnek be. A SKILL.md szövege, amelynek ajánlott mérete 5000 token alatt van, akkor töltődik be, amikor a skill aktiválódik. A csatolt fájlok addig nem kerülnek költségbe, amíg egy feladat be nem olvassa vagy nem futtatja őket (Agent Skills áttekintés).

Ebből az következik, hogy a telepített skillek olcsók, a hosszú skillek viszont nem. Tartsa az utasítástörzset 500 sor alatt, és a részleteket tegye referenciafájlokba, ahogy a specifikáció és a legjobb gyakorlatokat összefoglaló útmutató is javasolja. Az Anthropic Agent Skillsről szóló mérnöki bejegyzése a felépítést és a valós alkalmazásokat részletesebben tárgyalja.

Hosszú munkamenetekben két működés számít. A Claude Code a későbbi körökben nem olvassa újra a fájlt, ezért az egész feladatra érvényes szabályt állandó utasításba kell írni. A beszélgetés tömörítése után a Claude Code minden skill legutóbbi meghívását újracsatolja, skillenként az első 5000 tokent megtartva, 25 000 tokenes közös keretben. Ezért a legfontosabb utasításokat a fájl elejére tegye (Claude Code dokumentáció).

A skill-listának saját kerete van, a modell kontextusablakának 1 százalékához mérve. Ha sok skill túllépi, a Claude Code először a legritkábban meghívott skillek leírásait hagyja el, a description és a when_to_use együttes szövegét pedig a kerettől függetlenül 1 536 karakternél vágja le.

Hogyan kell megírni a leírást, hogy a skill aktiválódjon?

A leírás az egyetlen rész, amelyet Claude a skill többi részének betöltése előtt elolvas, ezért meg kell mondania, mit csinál a skill és mikor kell használni. Harmadik személyben írja, és használja azokat a szavakat, amelyeket a felhasználó ténylegesen beír. Claude a leírások alapján választ a potenciálisan 100 vagy több skill közül, ezért mindegyik leírásnak elég részletesnek kell lennie ehhez (legjobb gyakorlatok).

A harmadik személy szabálya azért van, mert a leírás bekerül a rendszerpromptba, és az egységtelen nézőpont ronthatja a felfedezhetőséget. Az útmutató példái megmutatják a különbséget. A „Processes Excel files and generates reports” jó; az „I can help you process Excel files” és a „You can use this to process Excel files” nem az. A homályos sorok, mint a „Helps with documents”, a „Processes data” vagy a „Does stuff with files”, semmit sem adnak Claude-nak az egyeztetéshez. Ugyanennek az útmutatónak a PDF-példája nevezi meg a műveleteket és az indítókat: „Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.”

Ha a skill nem aktiválódik, ellenőrizze, hogy a leírás tartalmazza-e a felhasználók szavait, kérdezze meg Claude-tól, mely skillek érhetők el, fogalmazza át a kérést, és hívja meg /skill-name formában, hogy kizárja a névvel kapcsolatos hibát. Az alapvető felhasználási esetet tegye az elejére, mert a lista levágja a hosszú szöveget. Ugyanez a szabály érvényes az ügynököknek szánt eszközökre; lásd: eszközök tervezése AI-ügynökökhöz.

Hol vannak a skillek, és mely munkamenetek töltik be őket?

Az határozza meg, mely munkamenetek töltik be a skillt, hogy hol van mentve. A ~/.claude/skills/ alatti személyes skill az adott gépen minden projektben betöltődik. A .claude/skills/ alatti projektskill az adott tárolóban töltődik be; commitolja, hogy a csapat is megkapja. A plugin-skill mindenhol betöltődik, ahol a plugin engedélyezve van. A Claude Code a projektskilleket abból a könyvtárból olvassa, ahonnan elindította, és minden szülőkönyvtárból a tároló gyökeréig.

A beágyazott skillek akkor töltődnek be, amikor Claude először olvas vagy szerkeszt egy fájlt a könyvtárukban, a munkamenet közbeni módosítások pedig újraindítás nélkül érvényesülnek. Két mappanév foglalt: a synced és az anthropic-skills.

A többi felületnek saját szabályai vannak. A claude.ai-n a skillt ZIP-fájlként tölti fel a Settings > Features menüponton keresztül; ehhez Pro, Max, Team vagy Enterprise csomag kell, bekapcsolt kódfuttatással, a skillek pedig az egyes felhasználókhoz tartoznak, nem a szervezethez. A Claude API a skilleket a /v1/skills végpontokon keresztül fogadja, és munkaterület-szinten megosztja őket. A skillek a felületek között nem szinkronizálódnak, ezért mindegyiket oda töltse fel, ahol használni szeretné (Agent Skills áttekintés).

Hogyan működik a hívás, az argumentum és az eszközjogosultság?

Alapértelmezés szerint Ön és Claude is meghívhat egy skillt. A disable-model-invocation: true csak kézzel hívhatóvá teszi, a user-invocable: false csak Claude számára hívhatóvá, az allowed-tools engedélyezi az eszközöket az őket meghívó körre, a context: fork pedig alügynökben futtatja a skillt. Az alábbi példa három funkciót használ: egy argument-hint mezőt, előre engedélyezett git-parancsokat és a $ARGUMENTS helyőrzőt.

---
name: summarize-changes
description: Summarizes uncommitted changes and flags risks. Use when the user asks what changed, wants a commit message, or asks to review their diff.
argument-hint: [focus-area]
allowed-tools: Bash(git diff *) Bash(git status *)
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points. Focus area, if one was given: $ARGUMENTS

List the risks you notice, such as missing error handling, hardcoded values, or tests that need updating.

If the diff is empty, say there are no uncommitted changes.

Az argumentumok a $ARGUMENTS helyőrzőn, vagy egyedi pozíciókban a $0, $1 stb. helyőrzőkön keresztül érkeznek. Több szavas értéket idézőjelbe kell tenni, hogy egy argumentumként kezelje; így a /my-skill "hello world" second a $0 értékét hello world-ra állítja. Ha a skillben nincs helyőrző arra, amit beírt, a Claude Code ARGUMENTS: <value> formában csatolja hozzá, így Claude látja a bemenetet.

Az allowed-tools csak az őt meghívó körre ad engedélyt, és a jogosultság megszűnik, amint elküldi a következő üzenetét. Nem korlátozza az eszközöket; a jogosultsági beállításai továbbra is érvényesek mindenre, amit a lista nem nevez meg. A munkaterület-megbízhatóság nem köti ehhez a mezőhöz, így egy projektskill allowed-tools mezője még olyan mappában is érvényes, amelyet soha nem bíztak meg. Tárolóból származó skillnél ellenőrizze ezt a mezőt.

A példában szereplő shell-injekciós sor a git diff HEAD parancsot futtatja, mielőtt Claude látja a skillt, a kimenet pedig a helyőrzőt helyettesíti. A beillesztett parancsok nem kérnek megerősítést, de előbb ellenőrzi őket a jogosultsági szabályai. Az automatikus módon kívül a hívást megszakítja az, ha egy parancs ellenőrzése nem „engedélyezett” eredményt ad, és egy sikertelen parancs az egész skillt megszakítja, nem csak a saját sorát. Ezért engedélyezi a példa előre a git-parancsokat.

A context: fork az agent mezőben megadott típusú alügynököt indít, és a skillt adja neki promptként. Az alügynök nem látja a beszélgetést, ezért a skillnek önmagában is működnie kell. A dokumentáció szerint a beállítás a világos utasítású skilleknek való; egy csak irányelveket tartalmazó skill semmi hasznosat nem ad. A forkolt skillek a háttérben futnak, hacsak nem állítja be a background: false értéket.

Hogy Claude mely skilleket hívhatja meg, olyan szabályokkal szabályozhatja, mint a Skill(commit), amely pontosan egy nevet fed le, vagy a Skill(deploy *), amely bármilyen argumentumokkal használható név. A Skill eszköz letiltása a /permissions alatt az összes skillt kikapcsolja.

Hogyan érdemes szkripteket és referenciafájlokat csatolni?

Szkriptet akkor csatoljon, ha az eredménynek minden alkalommal azonosnak kell lennie, és hagyja, hogy Claude futtassa, ne olvassa. Claude a csatolt szkripteket bash-on keresztül futtatja, és csak a kimenetüket látja (Agent Skills áttekintés).

A legjobb gyakorlatok útmutatója mércét állít: kezelje a hibaesetet, ahelyett hogy elbukna és Claude-ra bízná a találgatást, és indokolja minden konstansát. Egy 30 másodperces időtúllépés indokoló megjegyzéssel dokumentált; az indoklás nélküli szám „voodoo-konstans”. A specifikáció kiegészíti, hogy a szkriptek legyenek önállóak vagy dokumentálják a függőségeiket, adjanak hasznos hibaüzenetet, és kezeljék a szélsőséges eseteket (specifikáció).

A szkriptre a ${CLAUDE_SKILL_DIR} változóval hivatkozzon, amely a skill SKILL.md fájlját tartalmazó könyvtárra bővül. Ha ugyanezt a változót használja az utasításokban és az allowed-tools mezőben, a szkript jogosultság-kérés nélkül fut. A dokumentáció ezt a mintát mutatja:

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

Az, hol fut a skill, meghatározza, mit érhet el. A Claude API-n a skilleknek nincs hálózati hozzáférésük, és futás közben nem telepíthetnek csomagokat, ezért minden függőségnek már a környezetben kell lennie. A claude.ai-n a hálózati hozzáférés a felhasználói és adminisztrátori beállításoktól függ. A Claude Code-ban a skill ugyanazt a hálózati hozzáférést kapja, mint a gépen futó bármely más program, de a csomagok globális telepítése nem ajánlott.

Kezelje a skillt úgy, mint a telepített szoftvert. Csak olyan skilleket használjon, amelyeket Ön írt, vagy az Anthropictól szerzett be; ellenőrizzen minden csatolt fájlt, és különösen óvatos legyen a külső tartalmat lekérő skillekkel, mert a lekért szöveg utasításokat hordozhat. Az áttekintés arra is figyelmeztet, hogy még egy megbízható skill is kompromittálódhat, ha külső függőségei megváltoznak.

Hogyan tesztelhet és javíthat egy skillt?

Két dolgot külön teszteljen: azt, hogy Claude a megfelelő promptokra betölti-e a skillt, és azt, hogy a kimenet helyes-e, ha betöltődött. Hogy egy skill aktiválódik, az csak az elsőt mutatja meg. Futtasson néhány valósághű promptot friss munkamenetekben, a skillel és skill nélkül is, mert a skill írásából maradt kontextus elfedi a hiányosságokat (Claude Code dokumentáció).

A legjobb gyakorlatok útmutatója dokumentáció előtt értékeléseket kér. Állapítsa meg, hol hibázik Claude a skill nélkül, írjon legalább három értékelést ezekre a hiányosságokra, rögzítsen kiindulási alapot, majd adja hozzá a legkisebb mennyiségű utasítást, amely átmegy rajtuk. Teszteljen minden olyan modellel, amelyet használni szeretne. Az útmutató ellenőrzőlistája a Haiku, a Sonnet és az Opus modelleket nevezi meg, és jelzi, hogy ami az Opusnak elég, a Haikunak több részletet igényelhet.

Személyes vagy projektskill esetén állítsa a skillOverrides beállításban "off" értékre, hogy a skill nélküli kiindulási futtatást megkapja. A skill-creator plugin automatizálja a ciklust: a teszteseteket az evals/evals.json fájlban tárolja, minden esetet külön alügynökben futtat, az állításokat a grading.json fájlba értékeli, a sikerarányt és a tokeneket a benchmark.json fájlba összesíti, a leírást pedig az aktiválódó és a nem aktiválódó promptok alapján finomhangolhatja. A formátuma nem azonos azzal, amelyet a claude plugin eval használ pluginekhez. Az agentskills.io értékelési útmutatója ismerteti az iterációs munkafolyamatot.

Két parancs olyan problémákat talál meg, amelyeket egyébként nehéz észrevenni. A claude plugin validate jelzi azokat a SKILL.md fájlokat, amelyek frontmatterje nem értelmezhető (a Claude Code 2.1.233-as vagy újabb verziójától). A /skill-doctor megmutatja, mibe kerül az egyes skillek a listában, és megjelöli azokat, amelyeket soha nem hívnak meg (a 2.1.252-es vagy újabb verziótól).

Végül figyelje, hogyan használja Claude a skillt. A legjobb gyakorlatok útmutatója négy jelet sorol fel: váratlan olvasási sorrend, olyan hivatkozások, amelyeket Claude nem követ, egy referenciafájl, amelyet minden feladatnál elolvas, és csatolt fájlok, amelyeket soha nem nyit meg. Mindegyik szerkezeti javításra utal, például egyértelműbb hivatkozásra vagy egy gyakran használt fájl áthelyezésére a SKILL.md-be. Ha csapatnak készít skilleket vagy ügynökfolyamatokat, nézze meg mesterséges intelligencia-fejlesztési munkámat.

Források

1. Claude Code documentation: skills
2. Agent Skills overview, Claude API documentation
3. Skill authoring best practices, Claude API documentation
4. Agent Skills specification
5. Evaluating skill output quality, Agent Skills documentation
6. Equipping agents for the real world with Agent Skills, Anthropic engineering blog
7. The state of Claude skills in 2026, SkillGild analysis of Ahrefs data