Jak vytvořit Claude skill: napiš SKILL.md za 10 minut

Testujeme Claude skilly už roky, stovky jich, a vzorec je skličující: většina skillů, které u nás neprojdou recenzí, neselhala proto, že by autor neuměl napsat instrukce. Selhaly proto, že se skill nikdy nenačetl, nebo se načetl, když neměl, nebo to byly tři skilly v jednom kabátě. Všechno opravitelné ve fázi psaní, nic z toho se nedá zachránit dodatečně hezčím README.

Tohle je tutoriál, který bychom si přáli, aby si přečetl každý, kdo nám něco posílá. Na konci budeš mít funkční skill: checklist na code review, který posune Clauda za "vypadá to dobře, možná přejmenuj tuhle proměnnou" ke kontrole hraničních podmínek, chybových větví a mrtvého kódu. Je to reálný příklad záměrně. Nejlepší komunitní skill v naší kategorii programování, Code Review Checklist, dělá přesně tohle a má 8/10 za výstup. Tvůj ho první den nepřekoná, ale pochopíš každé rozhodnutí, které autor toho skillu udělal.

Slib "10 minut" je poctivý s jednou hvězdičkou. Napsat první funkční verzi trvá zhruba 10 minut. Pořádně ji otestovat trvá dalších 30. Přeskoč tu druhou část a přidáš se k polovině publikovaných skillů, které nepřežijí kontakt s čerstvou session. Pitevní zprávu jsme sepsali v článku proč polovina Claude skillů nefunguje a nechtěli bychom přidat ten tvůj do datasetu.

Pokud jsi nikdy skill nenainstaloval/a a nevíš, co to je, přečti si nejdřív co jsou Claude skilly a jak je nainstalovat. Tenhle článek předpokládá, že jsi aspoň jeden použil/a.

Krok 1: zaměř ho na jednu práci

Než napíšeš jediný řádek, rozhodni, co tvůj skill dělá. Pak to rozděl napůl.

Největší selhání, které v testování vidíme, jsou skilly, které se snaží dělat všechno. "Pomáhá s kvalitou kódu" zní jako rozumný rozsah. Není. Takový skill se chce spouštět u review, refaktoringu, psaní testů, dotazů na linting a debat o architektuře, což v praxi znamená, že Claude nepozná, kdy ho má načíst, takže se načítá nepředvídatelně nebo vůbec. Problémy se spouštěním jsou číslo jedna důvod, proč skill dostane nízké skóre v naší metodologii, před špatnými instrukcemi i rozbitou instalací. Ne proto, že by spouštění bylo nejtěžší část psaní skillu, ale proto, že rozlézání rozsahu o krok dřív dělá spouštění dál po proudu neřešitelným.

Jeden skill, jedna práce. Tady je test: dokážeš dokončit větu "použij tento skill, když uživatel žádá o ___" jedním konkrétním slovesným spojením? "Zkontrolovat pull request nebo diff" projde. "Zlepšit jejich kód" ne. Pokud tvá věta má "a" nebo "nebo" spojující nesouvisející činnosti, píšeš dva skilly. Napiš dva skilly. Složky jsou zadarmo.

Pro náš příklad je rozsah: zkontrolovat diff nebo PR kvůli chybám v logice, podle pevného checklistu, s potlačením stylistických připomínek. Ne "pomoct s review". Ne "zkontrolovat a opravit". Zkontrolovat, nahlásit, stop.

Krok 2: šablona SKILL.md

Skill je složka s jedním povinným souborem. Náš půjde do ~/.claude/skills/ pro osobní použití, nebo .claude/skills/ uvnitř repozitáře, pokud ho má dostat celý tým:

review-checklist/
  SKILL.md          ← povinný, a často jediné, co potřebuješ
  reference/        ← volitelné, Claude to načte jen když se rozhodne to přečíst
  templates/        ← volitelné, soubory, na které tvé instrukce odkazují

Tady je celý SKILL.md, který postavíme, s komentáři. Zkopíruj si ho, pak si přečti anotace, protože dva z těchto řádků jsou důležitější než všechno ostatní:

---
# 'name' je identifikátor: malá písmena, pomlčky, žádné mezery.
# Claude ho vidí, ale NEROZHODUJE o spouštění.
name: review-checklist

# 'description' je JEDINÉ, co Claude čte při rozhodování,
# jestli tento skill načíst. Všechno pod frontmatterem je
# neviditelné, dokud tohle rozhodnutí nepadne. Piš ho jako
# spouštěcí podmínku, ne jako marketingový text.
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.
---

# Checklist pro code review

Při review diffu nebo PR projdi tento checklist v pořadí.
Nahlas jen zjištění; nic neoprávuj, pokud o to nikdo nepožádá.

## Postup

1. Přečti celý diff, než okomentuješ jakýkoli řádek.
2. U každé změněné funkce zkontroluj:
   - Riziko off-by-one na hranicích smyček a indexech
   - Cesty pro null/undefined: co se stane, když je vstup prázdný?
   - Zpracování chyb: jsou selhání potlačena, nebo logována a znovu vyhozena?
3. Zkontroluj mrtvý kód, který změna vytváří: nepoužité importy,
   nedosažitelné větve, osiřelé pomocné funkce.
4. Souběžnost kontroluj jen pokud diff sahá do sdíleného stavu.
5. Ověř, že nová logika má pokrytí testy. Chybějící testy jsou
   zjištění, ne blokující problém.

## Pravidla pro reporting

- Max 10 zjištění, seřazených podle závažnosti. Pokud jsi jich
  našel/a 30, nahlas 10 nejhorších.
- Každé zjištění potřebuje soubor, odkaz na řádek a jednořádkový
  návrh opravy.
- NEhlas: preference pojmenování, formátování, styl komentářů
  ani nic, co by odchytil linter.
- Pokud je diff čistý, řekni to jednou větou. Nevymýšlej si
  zjištění, aby to vypadalo důkladně.

To je celý skill. Žádný build krok, žádný manifest, žádná registrace. Restartuj Claude session a je live.

Frontmatter má přesně dvě pole, na kterých záleží. name je administrativa. description rozhoduje o všem, a tady je proč: Claude drží v kontextu jen jméno a popis každého nainstalovaného skillu. Tělo tvého SKILL.md pro model neexistuje, dokud nepřečte tvůj popis, nerozhodne "tohle odpovídá tomu, co uživatel chce" a nenačte zbytek. Skvělý 200řádkový checklist za vágním popisem je skvělý 200řádkový checklist, který nikdy nikdo nespustí. V našem hodnoticím systému má spouštění stejnou váhu jako kvalita výstupu přesně z tohoto důvodu. Skill, který se spustí ve 40 % případů, je hod mincí s extra kroky navíc.

Krok 3: napiš spouštěcí popis

Protože popis je spouštěcí podmínka, piš ho tak. Pojmenuj formulace, které by opravdu napsal skutečný uživatel. Zahrň i negativní prostor, tedy blízké požadavky, u kterých má skill mlčet.

Vedle sebe, ze skutečných příspěvků, které jsme testovali (lehce anonymizované):

Špatně:

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

Dobře:

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.

Špatný popis popisuje přínos. Dobrý popisuje okamžik. Claude tvůj popis nečte, aby se nechal přesvědčit; hledá shodu se skutečnými slovy uživatele. "Zkontroluj tenhle PR" nesdílí žádnou slovní zásobu s "pomáhá zlepšit kvalitu kódu", takže skill prospí svůj vlastní use case. Testovali jsme příspěvek téměř identický s tím špatným příkladem: spustil se u 1 z 8 promptů typu review. Po přepsání popisu tak, aby pojmenovával formulace, se stejným tělem, se spustil u 8 z 8.

Ještě jedna dvojice, tentokrát o negativním prostoru:

Špatně:

description: Use for anything related to testing.

Dobře:

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.

"Cokoli souvisejícího s testováním" je způsob, jak nakonec unesete debugovací session. Nedostatečné spouštění je hlasitější, přílišné spouštění je tišší a stejně škodlivé: uživatel dostane odpovědi ve stylu checklistu na otázky, které potřebovaly něco jiného, obviní model a skill odinstaluje.

Mechanická pravidla, která platí napříč vším, co jsme testovali: pojmenuj tři až pět konkrétních formulací uživatele, zahrň aspoň jednu klauzuli "NE-", drž se pod zhruba 500 znaky a nikdy nepoužívej slova "výkonný", "komplexní" nebo "pomáhá s". Tahle slova tak konzistentně korelují se špatným skóre za spouštění v našich datech, že už při jejich spatření mrkneme podezřívavě.

Krok 4: napiš tělo, které Claude opravdu dodržuje

Jakmile se skill načte, tělo je instrukční sada. Selhání je tu jemnější než u spouštění, ale stejně časté: instrukce, které inspirují, místo aby omezovaly. "Napiš důkladné, promyšlené review" je motivační plakát. Claude už chce být důkladný a promyšlený; to je výchozí chování, které se snažíš tvarovat, ne tvar samotný.

Skilly, které vedou naše žebříčky, jsou seznamy omezení. Test-Driven Development zakazuje implementaci před existencí selhávajícího testu, tečka. Náš ukázkový skill omezuje počet zjištění na 10 a přímo zakazuje stylistické připomínky. Všimni si, kolik jeho řádků začíná "ne-". Je to záměrné. Modely mají tendenci generovat víc, než je potřeba, takže nejcennější instrukce jsou obvykle ty, které odebírají.

Pravidla pro tělo skillu:

1. Číslované postupy porážejí prózu. "Projdi to v tomto pořadí" dá Claudovi páteř; odstavce dávají jen dojmy.
2. Uveď podmínku pro zastavení. Náš skill říká nahlásit zjištění, ne opravit. Bez toho řádku Claude ochotně začne kód přepisovat, o což nikdo nežádal.
3. Předepiš formát výstupu. Maximální počty, povinná pole, jak vypadá čistý výsledek. "Pokud je diff čistý, řekni to" brání vymýšlení zjištění, což je selhání, které u review skillů vídáme neustále.
4. Zřídka potřebné detaily dej do souborů v reference/. Pokud má tvůj skill 300řádkový styleguide, který se použije jednou za měsíc, nevkládej ho do SKILL.md, kde spaluje kontext při každé aktivaci. Ulož ho jako reference/style-guide.md a napiš "když se uživatel ptá na X, nejdřív si přečti reference/style-guide.md". Claude ho načte na vyžádání.

Kdy přidávat skripty a šablony? Jen když instrukce samy nestačí. Skill, který generuje konkrétní konfigurační soubor, by měl přibalit templates/config.yaml a napsat "zkopíruj tohle, pak uprav". Skill, který potřebuje deterministické chování, řekněme parsování formátu lockfile, by měl přibalit skript a nařídit Claudovi ho spustit, místo aby ho pokaždé znovu vytvářel z paměti. Ale většina skillů nepotřebuje ani jedno. Náš příklad nepotřebuje ani jedno. Každý soubor ve složce je něco, co teď udržuješ, takže si ho zaslouž.

Krok 5: otestuj ho lokálně

Nejsi hotov/a, když to funguje jednou. "Fungovalo to, když jsem to zkusil/a" je testovací standard každého rozbitého skillu, který jsme kdy zamítli. Tady je minimální sada testů a docela přesně kopíruje to, co spouští naše metodologie u příspěvků:

1. Čerstvá session. Restartuj Claude Code úplně. Skilly se načítají na začátku session, takže testování v session, kde jsi ho napsal/a, nic neprokazuje.
2. Test spouštění, pozitivní. Zkus tři různé formulace, které by napsal skutečný uživatel: "zkontroluj tenhle PR", "můžeš mrknout na tenhle diff, než to mergnu", "podívej se na moje změny". Všechny tři by měly skill aktivovat. Poznáš, že se spustil, podle toho, že výstup dodržuje tvá pravidla (seznam zjištění s omezeným počtem a seřazený podle závažnosti nevypadá jako výchozí review). Pokud si nejsi jistý/á, zeptej se Clauda přímo, jestli skill použil.
3. Test spouštění, negativní. Zkus tři blízké požadavky, které by se NEMĚLY spustit: "oprav tenhle bug", "napiš funkci, která parsuje data", "proč tenhle test padá?". Pokud se tvůj review checklist objeví v debugovací session, popis potřebuje klauzuli "NE-použij".
4. Porovnání se základem. Spusť stejný prompt na review v session se skillem a bez něj. Pokud nepoznáš výstupy od sebe, skill si nezasluhuje svůj kontext a měl/a bys zpřísnit omezení. Tohle je náš oblíbený test, protože je nemilosrdný. Zhruba třetina skillů, které recenzujeme, jím propadne.
5. Test čisté instalace. Pokud plánuješ publikovat: zkopíruj složku na jiný stroj (nebo smaž a naklonuj znovu), postupuj podle vlastního README doslova a podívej se, jestli to funguje. Chybějící poznámky o závislostech umírají přesně tady.

Celá sada trvá 30 minut. Odfiltruje zhruba 80 % selhání, která vídáme, což je silná návratnost za půl hodiny.

Krok 6: pusť ho přes validátor

Než publikuješ, vlož svůj SKILL.md do našeho bezplatného validátoru skillů. Hodnotí podle stejného systému, jaký používáme v recenzích: délka a specifičnost popisu, přítomnost konkrétních spouštěcích formulací, klauzule negativního prostoru, hustota omezení v těle, předpis formátu, zjevné antivzorce jako "výkonný" a "cokoli souvisejícího s".

Je to statická analýza, tak k tomu tak přistupuj. Odchytí chyby, které jsou viditelné v textu, což je podle naší zkušenosti většina z nich, ale nedokáže spustit tvůj skill proti živým promptům. Průchod validátorem plus sada z kroku 5 je skutečná laťka. Samotný průchod validátorem je jen skill s vylintovaným textem, který se pořád nemusí spouštět.

Pokud chceš raději interaktivní pomoc než checker, nástroj Skill Creator od Anthropicu je to, co doporučujeme. V našem testování dostal 9,6, vytvoří celou složku a jeho krok optimalizace popisu měřitelně zlepšil spouštění u našich vlastních interních skillů. Používat skill na psaní skillů zní jako vtip a funguje to i tak.

Krok 7: publikuj a přihlas

Publikování je obyčejný GitHub repozitář. Konvence pro strukturu:

your-repo/
  README.md           ← co dělá, instalační příkaz, jeden příklad
  review-checklist/
    SKILL.md
    reference/

Dej instalační příkaz do README jako blok pro zkopírování, standardní vzorec je git clone plus cp -r review-checklist ~/.claude/skills/. Pak přidej k repozitáři tag claude-skills. Tohle není dekorace: tag je způsob, jak náš crawler i každý jiný katalog objevuje nové skilly. Neoznačený repozitář se skillem je v praxi neviditelný.

README, které stojí za napsání, má čtyři věci: jednu větu o tom, co skill dělá, instalační blok, jeden příklad před/po a jakékoli závislosti. Příklad před/po dělá pro adopci víc než všechno ostatní dohromady, protože je to jediná část, která ukazuje, místo aby jen tvrdila.

Pak ho přihlas do SkillProof. Testování a zařazení jsou zdarma. Projedeme ho stejným procesem jako všechno ostatní v katalogu: čistá instalace z tvého README, baterie testů spouštění, porovnání se základem, hodnocení výstupu. Pokud projde, dostane se do listingu se skóre a můžeš do README vložit odznak "SkillProof tested". Pro neznámého autora s dva dny starým repozitářem je nezávislý testovací verdikt rozdílem mezi "náhodný SKILL.md z internetu" a něčím, co si cizí člověk skutečně nainstaluje. Pokud neprojde, dostaneš poznámky k selhání, opravíš to a přihlásíš znovu. Spousta zařazených skillů prošla dvěma koly.

Časté chyby, které vídáme v příspěvcích

Po pár stovkách recenzí se pořád opakuje stejných pět.

Vágní popisy. Pořád na prvním místě, s velkým náskokem. Pokud by tvůj popis mohl popisovat tři jiné skilly, nepopisuje žádný z nich.

Skill jako kuchyňský dřez. Jeden SKILL.md pro review, commity, refaktoring i dokumentaci. Každá práce ředí spouštění těch ostatních. Rozděl to.

Opakování výchozího chování modelu. Tělo, které říká "buď jasný, buď přesný, mysli krok za krokem", nepřidává nic. Claude to dělá tak jako tak. Pokud by smazání řádku nezměnilo výstup, smaž ten řádek.

Žádná negativní omezení. Skilly, které říkají jen, co dělat, nikdy co přestat dělat. Řádky "ne-" jsou tam, kde žije většina změny chování.

Netestované instalační instrukce. README říká zkopíruj jednu složku; skill potichu závisí na druhém skillu nebo Python balíčku. Umírá na našem testu čisté instalace pokaždé, a je to nejsnáze odstranitelné selhání na tomto seznamu.

Časté dotazy

Potřebuju umět programovat, abych vytvořil/a Claude skill? Ne. SKILL.md je markdown s YAML hlavičkou. Pokud tvůj skill přibaluje pomocné skripty, budeš je muset napsat, ale skilly jen s instrukcemi, což je většina z nich, jsou obyčejné psaní. Skill v tomto článku neobsahuje jediný řádek kódu.

Jak dlouhý má být SKILL.md? Tak krátký, jak to jde, aniž by přestal omezovat chování, typicky 30 až 150 řádků. Pod zhruba 20 řádky obvykle nepřidává nic nad rámec výchozího chování; nad pár stovek by ses měl/a přesunout s detaily do souborů reference/. Délka je cena, kterou platíš při každé aktivaci, ne signál kvality.

Proč se můj skill nespouští? Skoro vždy je to popis. Zkontroluj, jestli pojmenovává formulace, které uživatel opravdu píše, místo aby popisoval přínosy, a ověř, že jsi po instalaci restartoval/a session, protože skilly se načítají na začátku session. Pokud se spouští u některých formulací a u jiných ne, přidej ty chybějící do popisu explicitně.

Jaký je rozdíl mezi skillem a MCP serverem? Skill je instrukce: markdown, který tvaruje, jak se Claude chová, žádný kód nikde neběží. MCP server je program, který Claudovi dává nové schopnosti, třeba dotazování tvé databáze. Pokud je tvůj nápad "Claude by měl k X přistupovat jinak", je to skill. Pokud je to "Claude potřebuje přístup k Y", je to MCP. Delší verze v Claude skilly vs. MCP.

Můžu za Claude skill nechat platit? Neexistuje žádný vestavěný platební mechanismus; skilly jsou soubory a veřejný ekosystém běží na otevřených repozitářích. Někteří autoři prodávají soukromé sady skillů týmům jako konzultační dodávku, což funguje, protože hodnota je zakódovaná expertiza, ne samotný soubor. Cokoli určeného pro veřejný katalog by mělo mít otevřenou licenci, protože nikdo si nenainstaluje skill, který si nemůže přečíst.

Zaměř se na jednu práci, piš spouštěcí popis jako regex v próze, omezuj místo inspirace a otestuj to v čerstvé session, než to komukoli řekneš. To je celé řemeslo. Zbytek je iterace a fronta na přihlášení je otevřená.