Skill

Co skill dělá

Spravuje vlastní skilly v ~/.claude/skills/ proti normě v ~/.claude/skills/skills.md. Čtyři režimy:

• /skill nebo /skill create – založení. Řízený rozhovor, tabulka delegací, srovnávací běh, sepsání, ověření, napojení na okolí.
• /skill extract – vytěžení konverzace. Vstupem není zadání, ale to, co se v session vyladilo. Od sepsání dál je dráha stejná jako u založení.
• /skill update [jméno] – dorovnání na dnešní normu. Jeden skill, nebo bez jména všechny. Hlavní důvod, proč je skill opakovatelný.
• /skill delete <jméno> – odstranění i se stopami.

Režim update je to, co neumí nikdo jiný. Norma se posouvá dál, hotové skilly zůstávají stát a samy o tom neřeknou – stejná vlastnost, kvůli které má /project svůj revizní krok.

Co skill nedělá

• Nedefinuje tvar skillu. Ten je v ~/.claude/skills/skills.md. Tenhle skill ho čte, neopisuje a nerozšiřuje. Ukáže-li se, že norma je špatně, opraví se norma – ne že se udělá výjimka tady.
• Neaudituje konfiguraci. Rozpory mezi soubory, mrtvé zbytky a rozejití mezi vrstvami řeší /consistency; tenhle skill se dívá jen na skilly a jen proti normě.
• Neprověřuje kvalitu práce skillu za běhu. Že skill dělá dobrou práci, ukáže jeho použití a /review. Tady se měří, jestli se vyvolá a jestli se pod tlakem dodrží.
• Nesahá na cizí skilly. Pluginy a vestavěné skilly se používají, ne udržují.
• Nemigruje zbytek skillů mimochodem. Převod na novou normu je vědomý běh režimu update, ne vedlejší efekt jiné práce.

Jak je to postavené uvnitř

Skill skládá, nepíše vše sám – je to první uplatnění pravidla Skládej, nepiš znovu z normy. Co se komu deleguje:

Volání cizích nástrojů je implementační detail, ne rozhraní. Vyměnit se smí kdykoliv. Závazné je: tvar výstupu podle skills.md, že se skill nezaloží bez odsouhlaseného zadání, že revize nic nepřepíše bez zeptání a že se po dokončení dorovná okolí.

Zadávej vnitřku kontrakt výstupu, ne kroky. „Potřebuju tři testovací prompty a vyhodnocení, jestli se skill vyvolal“ přežije upgrade pluginu; „udělej svůj krok 3“ ne.

Cizí nástroj nesmí rozhodovat o tvaru. Předej mu výslovně: sekce a jejich pořadí podle skills.md, čeština, cíl skills/<name>/SKILL.md v tomhle repozitáři. Bez toho si prosadí vlastní výchozí volbu – skill-creator i writing-skills mají každý svou a obě se od téhle normy liší.

Fáze 0 – Příprava

Společný začátek je v ~/.claude/skills/preflight.md. Kořenem projektu je tady vždycky ~/.claude. Navíc:

1. Přečti ~/.claude/skills/skills.md celou. Neopírej se o paměť – tvoje představa o tvaru je zrovna to, co může být zastaralé.
2. Udělej inventuru toho, co je k dispozici. ls ~/.claude/skills/, seznam nainstalovaných pluginů a jejich skillů, vestavěné skilly. Je to vstup pro Fázi 3 a zároveň se tím ověří, že cizí nástroje, na které skill deleguje, opravdu existují.
3. Kontrola závislostí měřicí části. Ověř dřív, než na ně pošleš práci, dvě věci: že je skill-creator opravdu nainstalovaný (plugins/installed_plugins.json, ne jen přítomný v cache marketplace – ta obsahuje i to, co nainstalované není), a že jeho skripty mají Python a svoje okolí. Chybí-li, neselhávej – řekni nahlas, co odpadá (extract, evaluace výstupu, ladění description), pokračuj bez měřicí části a zapiš do závěru, co se tím neověřilo.
4. Zjisti, na kterém skillu se pracuje, je-li v argumentu. Neexistuje-li a jde o jiný režim než create, nabídni nejbližší jména z inventury místo hlášky o chybě.

Fáze 1 – Volba režimu

Je-li režim v argumentu, jeď podle něj a jen ho oznam. Není-li, zeptej se přes AskUserQuestion.

Fáze 2 – Zadání

Ptej se postupně, jednu otázku za druhou (~/.claude/standards/rules.md, Ptej se postupně, ne všechno najednou).

Nejdřív otázka, která rozhoduje, jestli se vůbec pokračuje:

1. Má to být skill? Projdi zadání čtyřmi možnostmi z normy, Kdy vzniká skill – a kdy ne. Vyjde-li, že to patří do kontroly, do ~/.claude/standards/rules.md, do domény nebo do projektového CLAUDE.md, řekni to a skonči. Skill, který měl být pravidlem, se pak nikdy nevyvolá ve chvíli, kdy je potřeba.

Pak zbytek:

2. Co skill dělá a kdy se má vyvolat. Doslovné spouštěče i situace.
3. Stojí v Životním cyklu projektu (~/.claude/standards/rules.md)? Pokud ano, ve které vrstvě (~/.claude/standards/lifecycle.md, Kroky cyklu a jejich uspořádání): krok osy se vymezuje proti dvěma sousedům na ose, kontrolní krok proti těm, čí práci nepřebírá, a místo sousedů se u něj určí, ve kterých mezerách stojí. To je vstup pro Co skill dělá a Co skill nedělá a bez něj sekce vznikne jako prázdná negace.
4. Má režimy? Určuje argument-hint.
5. Co je jeho výstup a podle čeho se pozná, že je hotový. Vstup pro závěrečný verdikt.
6. Které doménové znalosti z ~/Context/ se na něj vztahují.

V režimu extract body 2 až 6 nevymýšlej – vytěž je z konverzace.

Prošla-li session kompaktací, nestačí to, co máš v kontextu – první polovina konverzace je pryč a bývá v ní zrovna to, co se vyladilo. Načti nejdřív transcript ze souboru; jak ho najít a jaké pasti má jeho formát, drží ~/.claude/skills/session.md. Neopisuj ho sem, řiď se jím.

Pak vyvolej skill-creator a nech ho vytěžit záměr: použité nástroje, sled kroků, opravy, kterými uživatel průběžně měnil směr. Výsledek předlož k potvrzení a doplň jen to, co v konverzaci nezaznělo.

Zadání nech odsouhlasit, než začneš psát. Skill postavený na nedomluveném zadání se zahazuje celý.

Fáze 3 – Tabulka delegací

Povinná inventura. Ke každému kroku navrženého postupu odpověz: umí to už něco? Prohledej vlastní skilly, pluginy, vestavěné skilly, hooky a deterministické nástroje z inventury ve Fázi 0.

Výstupem je tabulka, která jde rovnou do sekce Jak je to postavené uvnitř:

| Krok | Kdo | Proč zrovna on |
|---|---|---|
| <krok> | vlastní | <co je na tom naše> |
| <krok> | <nástroj> | <co už umí> |

Zapisuje se do SKILL.md, tedy jako Markdownová tabulka, ne jako mezerami zarovnaný text v bloku kódu.

Deleguje-li krok na subagenta, rozhodni rovnou jeho typ a zapiš ho do sloupce Kdo. Dělítko drží ~/.claude/skills/skills.md, Model, effort a delegace: posouzení hotového textu jde na reader, s potřebou rešerše na researcher, měření a spouštění zůstává na Explore. Neodkládej to na později – typ bez shellu si vynutí, aby zadání po agentovi nechtělo nic spouštět, a to se píše hned, ne dodatečně.

Zbylo-li po odečtení delegací jádro, pokračuj. Nezbylo-li, řekni to: je to alias, ne skill, a má se napsat jako alias.

Fáze 4 – Srovnávací běh

Změř, jak agent selže bez skillu. Bez toho se skill píše proti představě, ne proti skutečnosti – a naučí něco jiného, než je potřeba.

Vyvolej superpowers:writing-skills a předej mu úlohu: pustit agenta bez skillu na ukázkový úkol ze zadání a zapsat konkrétní racionalizace, kterými si zvolil jinou cestu. Ty jsou vstup pro Časté chyby a pro místa, kde má být pravidlo formulované tvrději.

Tvar mu nezadávej a jeho doporučení k tvaru ignoruj – ten je z normy.

Nejde-li srovnávací běh udělat (skill je čistě mechanický, nebo prostředí není k dispozici), řekni to a pokračuj – vědomá mezera se přiznává, ne obchází.

Fáze 5 – Sepsání

Nejsilnější model, xhigh (~/.claude/standards/delegation.md, Model a effort podle úkolu). Skill řídí veškerou práci, která pod ním poběží; vada v něm se násobí do každého běhu a projeví se až u posledního.

Piš sám, proti normě. Tenhle krok se nedeleguje – je to jediné místo, kudy by prosákl cizí tvar.

Projdi skills.md sekci po sekci a splň každou. Zvlášť hlídej to, co se odbývá nejčastěji:

• Co skill nedělá jmenuje souseda, ne obecnou činnost.
• Fáze 0 odkazuje na preflight.md a obsahuje jen odchylky.
• Závěrečný verdikt má obě znění, splňuje vzorec z normy a je v těle uvedený doslovně.
• Délka pod měkkou mezí; co ji přetahuje, jde do vedlejšího souboru v adresáři skillu.
• description má spouštěč i popis situace a vejde se do 1024 znaků.
• argument-hint sedí s režimy popsanými v těle.

Fáze 6 – Ověření

Tři vrstvy, každá měří něco jiného. Chybí-li nástroj pro některou, vynech ji a zapiš to do závěru jako nezkontrolované.

1. Tvar – pusť python3 -m unittest discover -s tests z ~/.claude. Je to nejlevnější kontrola a stojí nula tokenů.

2. Vyvolání – ladění description. Měří, jestli se skill chytí na situace, pro které vznikl, a nechytá se na cizí. U skillu, jehož jméno se překrývá s cizím skillem, je tenhle krok povinný.

   Neměř to skriptem run_eval.py ze skill-creatoru u skillu, který je nainstalovaný. Registruje popis jako dočasný slash command a hledá volání toho dočasného jména; model přitom zavolá skutečný nainstalovaný skill, takže se správné vyvolání počítá jako propadlé.

   Měř na skutečném kanálu: pusť každý testovací prompt přes claude -p --output-format stream-json v čistém adresáři a sleduj, jestli mezi voláními nástrojů padne Skill se jménem toho skillu.

   Nástroje měřicího běhu vyjmenuj kladně: --tools Skill,Read --strict-mcp-config. Měřený skill se spustí doopravdy, a zapisuje-li, zapíše do ostrých dat. Zákaz --disallowedTools Bash Edit Write to nezastaví – model si najde jiný nástroj, kterým zápis udělá, a zbytek sady i MCP servery mu zůstávají. Kladný výčet zápis zavře a vyvolání dál ukáže, protože volání Skill v něm je.

   Pozor: doslovný /jméno se takhle změřit nedá. Napíše-li uživatel jméno skillu s lomítkem, harness mu vloží tělo SKILL.md rovnou do zadání a model žádný nástroj Skill nevolá – není proč. Detektor postavený na volání nástroje pak hlásí propad tam, kde skill zabral spolehlivěji než jindy, protože o jeho načtení nerozhodoval model. Je to táž vada jako u run_eval.py o odstavec výš: měřidlo, které neodliší vlastní selhání od nálezu.

   Doslovné slash prompty proto měř znalostí obsahu těla – zeptej se na něco, co je jen v SKILL.md a není v description (třeba na názvy fází), a ověř, že to model zná.

   Ostatní skilly jsou přitom reálně v nabídce, takže se rovnou měří i překryv s nimi. Dva běhy na prompt, aspoň 6 pozitivních a 6 negativních – near-missy volit tak, aby braly jednotlivá slova z popisu („posbírej články konkurence“ proti režimu collect).

   Třetí vada měřidla: prompt musí mít o čem mluvit. Odkazuje-li testovací prompt na vstup („zapracuj tenhle článek“, „přepiš tuhle nahrávku“) a v adresáři, kde měření běží, žádný takový soubor není, model se doptá, místo aby jednal – a detektor to započítá jako propad. Není to vada popisu: s existujícím souborem projde týž prompt na první pokus.

   Založ proto v měřicím adresáři vstup, na který se prompty odvolávají, a propadlý pozitivní případ vždycky přeměř se souborem, než začneš přepisovat description.

   Kdyby se to nerozlišilo, opravoval by se popis kvůli propadu, který s ním nemá nic společného. Je to táž třída chyby jako obě předchozí – měřidlo, které neodliší vlastní selhání od nálezu –, a poznáš ji podle toho, že propadají jen pozitivní případy.

3. Dodržení pod tlakem – superpowers:writing-skills, tlakové scénáře. Povinné u skillu, který něco zakazuje nebo vynucuje (nesahat na testy, nepokračovat bez potvrzení, nespouštět proti produkci). U takového skillu je totiž funkce právě to omezení, a ta se tvarem ověřit nedá.

Nálezy oprav a projeď znovu – ne že je jen ohlásíš.

Fáze 7 – Okolí

Skill nežije sám. Tohle je jediné místo, kde je to napsané, takže se to jinak neudělá:

Commitni, má-li repozitář zapnutý autocommit.

Fáze 8 – Závěr

## Skill hotový

- **Soubor:** skills/<name>/SKILL.md – <N> řádků
- **Režim:** <create / extract>
- **Delegace:** <na co, nebo „na nic">

**Ověřeno**
- Tvar: <výstup testů a návratový kód>
- Vyvolání: <výsledek, nebo „neměřeno – proč">
- Tlakové scénáře: <výsledek, nebo „nepoužito – proč">

**Okolí**
- README.md · ~/.claude/standards/rules.md · tests/ · /project · decisions.md – co se dorovnalo

**Nezkontrolováno**
- [co a proč, nebo „nic"]

Vypisuj to jako Markdown, ne jako blok kódu, a řádky nezalamuj natvrdo – ~/.claude/standards/rules.md, Styl odpovědí.

Zakonči jednou z těchto vět, nikdy ničím vágním mezi tím:

• Skill je hotový a ověřený, můžeš ho pustit.
• Skill hotový není – brání tomu: <konkrétní seznam>.

Režim update

Projde skilly proti dnešní podobě normy a dorovná, co se rozešlo. Bez jména v argumentu jede přes všechny.

Normu si načti, neopisuj ji z hlavy. Rozdíl mezi skillem a tvou pamětí není nález – tvoje paměť je zrovna to, co je zastaralé.

Co se kontroluje

Poslední řádek je druhý druh rozejití vedle toho s normou a neklade ho nikdo jiný. Konfigurační vrstva roste pod nohama a starší skill o ní neví.

Jak to proběhne

Napřed skill projdi nanečisto. Pusť nad ním agenta typu reader se zadáním z ~/.claude/skills/skill/dryrun.md a se 3–5 realistickými vstupy, z toho aspoň jedním okrajovým (prázdný argument, chybějící soubor). Agent u každého vstupu vypíše kroky a nástroj, který každý potřebuje, porovná ho s allowed-tools a vrátí kroky, které provést nejdou, místa, kde musel hádat, a co by udělal slabší model. Strojová kontrola v tests/test_skills.py chytí jen nástroj jmenovaný v kódu; průchod najde i krok popsaný slovy („pusť agenta“) a mezeru, kterou skill nechává domyslet. Chybějící nástroj jde mezi nálezy jako „potřebuju rozhodnout“ – doplnit ho do hlavičky znamená rozšířit oprávnění.

Napřed vypiš nálezy, pak teprve jednej. Uživatel musí vidět rozsah dřív, než se sáhne na soubory.

- **<skill>** – <N> nálezů: <závažnost> <jednou větou> · [opravím / potřebuju rozhodnout]

Vypisuj to jako Markdown, ne jako blok kódu, a řádky nezalamuj natvrdo – ~/.claude/standards/rules.md, Styl odpovědí.

Dvourychlostní režim. Mechanické a jednoznačné oprav rovnou a jen vypiš – chybějící odkaz na preflight.md, chybějící znění závěrečného verdiktu, argument-hint bez opory. Co přepisuje nebo maže existující obsah – rozdělení dlouhého skillu, přeformulování sekce, nahrazení kroku delegací – předlož a nech potvrdit, přes AskUserQuestion a po jednom.

Přes všechny skilly nepředkládej nález po nálezu. Ukaž vzorec, počet a tři příklady, a proveď to hromadně. Padesát otázek se neodklikává, jen odsouhlasí naslepo.

Nenajdeš-li nic, řekni to a skonči. Běh bez zásahu je platný výsledek revize.

Nález, který měří test_skills_match_standard v ~/.claude/tests/test_skills.py, se odložit nedá – výjimky pro skilly mimo normu se nevedou, takže skill s takovým nálezem shodí testy, dokud se neopraví.

Datum ani otisk poslední revize nikam nezapisuj a revizi nezužuj na to, co se v normě od té doby změnilo – minula by rozejití, které se tehdy nepropsalo, protože ho nikdo nezpropagoval.

Pak pokračuj Fází 7 – i update sahá na README.md a testy.

Režim delete

Skill se buď používá, nebo neexistuje. Vypnutý skill dál nabízí funkci, kterou nikdo nemá zapnout – proto se ruší celý, ne že se odstaví.

Nejdřív vypiš, co všechno se najde, a nech to potvrdit. Teprve pak maž.

Hledej grepem přes všechny ty kořeny, ne z paměti. Po smazání projeď kontrolní průchod na jméno skillu – musí vrátit nulu mimo místa vědomě ponechaná.

Nech stopu. Do decisions.md zapiš, co bylo zrušeno a proč, i co se tím vědomě ztratilo. Bez toho se zrušený mechanismus vrátí za půl roku jako „to by šlo udělat“.

Zakonči jednou z těchto vět, nikdy ničím vágním mezi tím:

• Skill je zrušený, jeho jméno se v konfiguraci nevyskytuje.
• Skill zrušený není – brání tomu: <konkrétní seznam>.

Časté chyby

• Norma se opíše do skillu. Pak se rozejde a nikdo neví, která verze platí. Norma se čte, ne cituje.
• Cizímu nástroji se zapomene říct tvar. Prosadí vlastní – skill-creator i writing-skills mají každý svou představu o sekcích. Vždycky mu ho předej výslovně.
• Revize se pustí bez načtení normy. Pak měří proti paměti, tedy proti stavu, který je zrovna zastaralý.
• Přes všechny skilly se nálezy předkládají po jednom. Neodklikatelné; odsouhlasí se naslepo a revize ztratí smysl.
• Skill vznikne na věc, kterou chytne test nebo hook. Mechanické omezení psané textem se dodržuje hůř a stojí tokeny při každém běhu.