Claude skill se nespouští? Opravte to v 6 krocích

Nainstalovali jste skill, požádali Clauda o věc, na kterou skill je, a Claude pokračoval, jako by skill neexistoval. Žádná chyba, žádné varování, nic ke grepnutí. Jen ticho.

Vídáme to neustále. SkillProof instaluje a testuje každý skill v našem katalogu na čistém stroji a selhání spouštění je nejčastější vada, kterou nacházíme. Je také nejsnáz opravitelná: téměř každé hlášení „skill nefunguje" v našich testovacích záznamech vede k jedné ze šesti příčin a pět z nich vyloučíte za méně než minutu.

Nejdřív projděte checklist. Zbytek článku rozvádí každou kontrolu s příznakem, příčinou a opravou.

30vteřinový checklist

1. Správná složka? Soubor musí být v ~/.claude/skills/<skill-name>/SKILL.md, jedna složka na skill, název souboru přesně SKILL.md.
2. Restartovali jste? Claude skenuje skilly při startu sezení. Změny provedené uprostřed sezení jsou neviditelné, dokud nerestartujete.
3. Kolize názvů? Dva skilly se stejným name se navzájem zastiňují. Přežije jen jeden.
4. Description příliš vágní? Pokud popis nezmiňuje, o co uživatelé doslova žádají, Claude ho nikdy nespáruje. To je příčina číslo jedna.
5. Platný frontmatter? Jediný rozbitý znak YAML udělá celý skill neviditelným, potichu.
6. Konfliktní skill? Jiný nainstalovaný skill s překrývajícím se popisem může párování vyhrávat.

Pokud všech šest projde a skill se aktivuje, ale výstup se nemění, je to jiné selhání. Přeskočte na když se spustí, ale nic nedělá.

Kontrola 1: skill je ve špatné složce

Příznak. Skill se nikdy neobjeví, když se Clauda zeptáte „jaké skilly máš nainstalované?" Jako byste ho nikdy nezkopírovali.

Příčina. Claude se dívá jen na konkrétní místa: ~/.claude/skills/ pro osobní skilly a .claude/skills/ uvnitř projektu pro projektové. Uvnitř nich je uspořádání striktní: jedna složka na skill, obsahující soubor pojmenovaný přesně SKILL.md. Chyby, které při instalaci komunitních skilů k testování vídáme nejčastěji: zkopírování celého naklonovaného repozitáře (takže cesta je skills/some-repo/skills/pdf-helper/SKILL.md, o úroveň hlouběji), vhození SKILL.md přímo do ~/.claude/skills/ bez vlastní složky a malé skill.md, které některé souborové systémy odpustí a jiné ne.

Oprava. Ověřte z terminálu:

ls ~/.claude/skills/*/SKILL.md

Každý očekávaný skill by měl vypsat přesně jeden řádek. Pokud skill chybí nebo má jeho cesta zanoření navíc, přesuňte složku tak, aby SKILL.md ležel jednu úroveň pod skills/. Náš instalační návod prochází správné uspořádání pro každou platformu.

Kontrola 2: nerestartovali jste

Příznak. Struktura složek je správně, opravili jste ji před dvěma minutami, a Claude skill v téže konverzaci pořád nevidí.

Příčina. Objevování skilů probíhá jednou, při startu. Claude přečte frontmatter každého SKILL.md, který najde, a ten index si drží po celé sezení. Skill, který přidáte, přejmenujete nebo upravíte uprostřed sezení, z pohledu běžícího sezení neexistuje.

Oprava. V Claude Code ukončete a spusťte nové sezení. V desktopové aplikaci úplně skončete přes Cmd+Q na macOS (zavření okna se nepočítá) a znovu otevřete. Tohle je tak levné vyloučit, že to děláme před jakýmkoli hlubším debugováním — stejně jako byste restartovali router, než voláte poskytovateli.

Kontrola 3: kolize názvů zastiňuje váš skill

Příznak. Nainstalovali jste skill, složka je správně, restartovali jste, a seznam skilů neukazuje buď nic nového, nebo na stejné jméno odpovídá jiný skill.

Příčina. Názvy skilů musí být unikátní. Pokud osobní a projektový skill sdílejí name, nebo dva nainstalované balíčky oba obsahují skill jménem seo-audit, jeden zastíní druhý bez varování. Narazili jsme na to při vlastní práci na katalogu: dva marketingové balíčky nainstalované vedle sebe vytvořily tichý duplikát a ten, který jsme chtěli, se nikdy nenačetl.

Oprava. Vyhledejte duplikáty:

grep -h "^name:" ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | sort | uniq -d

Jakýkoli výstup znamená kolizi. Přejmenujte složku a pole name u kopie, kterou máte pod kontrolou, restartujte a zkontrolujte seznam znovu.

Kontrola 4: description nikdy neříká, kdy se spustit

Příznak. Skill se v seznamu nainstalovaných objevuje. Když ho zavoláte jménem, funguje dobře. Když o úkol požádáte vlastními slovy, nestane se nic.

Příčina. Tohle je ta velká a zaslouží si vlastní sekci, takže tady je krátká verze: Claude rozhoduje, jestli skill načíst, čtením pouze jeho pole description a porovnáním s vaším požadavkem. Pokud popis říká, co skill je, místo kdy ho použít, k párování nikdy nedojde. Skill není rozbitý. Je neinzerovaný.

Oprava. Přepište popis kolem frází, které uživatelé skutečně píší. Hloubkový rozbor níže ukazuje tři skutečné vzorce selhání a jejich přepisy.

Kontrola 5: frontmatter je neplatný

Příznak. Složka správně, restart hotový, žádná kolize názvů, a skill se v seznamu pořád vůbec neobjevuje. Vypadá to jako kontrola 1, ale cesta je v pořádku.

Příčina. Blok YAML na začátku SKILL.md se nepodařilo naparsovat a skill s neparsovatelným frontmatterem se prostě přeskočí. Obvyklí viníci z našich testovacích poznámek: chybějící uzavírací ---, dvojtečka bez uvozovek uvnitř popisu („Use for: reports" rozbije parser), typografické uvozovky vložené z blogu nebo Google Docu, tabulátory použité k odsazení a name porušující pravidla formátu (jen malá písmena, číslice a pomlčky, maximálně 64 znaků; popisy mají strop 1024).

Oprava. Otevřete soubor a blok prohlédněte, nebo prohlížení přeskočte: vložte ho do našeho validátoru skilů a ten okamžitě označí chyby parsování, porušení formátu i kontaminaci typografickými uvozovkami. Pokud frontmatter parsuje a skill se pořád skrývá, vraťte se ke kontrole 1, protože v tu chvíli je to skoro vždycky cesta.

Kontrola 6: párování vyhrává jiný skill

Příznak. Požádáte o úkol a nějaký skill se aktivuje, jen ne ten váš. Nebo se chování změní způsobem odpovídajícím instrukcím jiného skilu.

Příčina. Když požadavek věrohodně pokrývá několik popisů, Claude vybere ten, který působí jako nejlepší shoda — a širší, sebevědomější popis má tendenci porazit užší. Nainstalujte obecný skill „asistent psaní" vedle svého „formátovače release notes" a generalista může spolknout každý požadavek na psaní, včetně release notes.

Oprava. Zaostřete oba popisy, aby se jejich území nepřekrývala, a přidejte explicitní vyloučení. Řádek jako „Do NOT use for release notes or changelogs" v popisu generalisty je hrubý a funguje. Pokud problémový skill nemáte pod kontrolou, vypněte ho na dobu testování toho svého a pak se rozhodněte, jestli oba skutečně potřebujete.

Proč popisy selhávají: hloubkový rozbor

Testujeme každý skill, který zařazujeme, a problémy se spouštěním jsou důvod číslo jedna, proč skilly v našich recenzích skórují nízko. Ne rozbité skripty, ne špatné instrukce. Popisy, které se nikdy nespárují.

Mechanika vysvětluje proč. Při startu Claude načte jen name a description každého skilu, zhruba sto tokenů. Tělo, jakkoli brilantní, zůstává na disku, dokud popis nevyhraje párování s vaším požadavkem. Description je prodejní pitch přednesený modelu — a většina autorů ho píše jako muzejní popisku.

Tady jsou tři vzorce, které v hodnocení srážíme nejčastěji, s přepisy, které je v našich retestech opravily.

Vzorec 1: skromný štítek.

description: Helps with documents.

Nic tady se nenapojuje na nic, co by uživatel napsal. Srovnejte s DOCX skilem od Anthropicu, který našimi testy spouštění prošel na první běh. Jeho popis jmenuje formát souborů, akce i formulace, které ho mají aktivovat. Přepis, který sleduje stejnou logiku:

description: Create, edit, and format Word documents (.docx).
  Use when the user mentions a Word doc, .docx file, memo,
  letter, or asks for a deliverable "as a document."

Vzorec 2: interní název.

description: Runs the acme-formatter pipeline with corporate config.

Tohle popisuje implementaci. Žádný uživatel nežádá Clauda, aby „spustil acme-formatter pipeline"; žádá „ukliď tenhle report, než ho pošlu klientovi". Přepis překládá skill do slovníku uživatele:

description: Reformat rough drafts into client-ready reports using
  Acme's corporate style. Use when the user wants to clean up,
  polish, or "make presentable" a document for external sharing.

Vzorec 3: chamtivá deka.

description: Use for any writing task.

Opačné selhání. Tohle odpovídá všemu, což znamená, že koliduje s každým skilem, který se psaní jen dotýká, spouští se, když nemá — a uživatelé ho do týdne vypnou. Přepis nárok zužuje a ohraničuje okraje:

description: Write and edit marketing copy: landing pages, ads,
  and email campaigns. Do NOT use for technical docs, code
  comments, or internal memos.

Test, který při recenzích aplikujeme: přečtěte si jen popis a zeptejte se: „kdyby uživatel napsal svůj požadavek přirozeně, spárovala by se s ním tato slova?" Pište ve třetí osobě, uveďte, co skill dělá a kdy se uplatní, a zahrňte skutečná podstatná jména, která lidé používají. Pokud píšete skill od nuly, náš autorský návod to pokrývá do větší hloubky a Skill Creator od Anthropicu skládá popisy, které tímto testem projdou ve výchozím stavu.

Jak spouštění testovat pořádně

Většina lidí testuje skill tak, že ho jmenuje: „použij na tohle skill na faktury." To nedokazuje nic, protože jmenování skilu párování s popisem úplně obchází. Je to jako testovat kouřový hlásič stisknutím testovacího tlačítka a usoudit, že váš dům je ohnivzdorný.

Testujte tak, jak by se ptal uživatel, pokaždé v novém sezení. Pro skill na extrakci faktur tři formulace, které by se měly spustit:

• „Vytáhni součty z těchhle fakturových PDF."
• „Mám 30 faktur od dodavatelů, dostaň částky a data do tabulky."
• „Extrahuj položky z tohohle vyúčtování."

A dvě, které by se spustit neměly:

• „Shrň mi tohle PDF." (Obecná práce s PDF; území jiného skilu.)
• „Napiš tomuhle klientovi e-mail s fakturou." (Skládání, ne extrakce.)

Pokud formulace, která se spustit má, neudělá nic, zeptejte se Clauda přímo: „Který z tvých nainstalovaných skilů bys pro tento požadavek použil a proč?" Odpověď vám ukáže logiku párování a obvykle míří rovnou na slabé místo v popisu. Pokud se skill aktivuje i na formulace, které se spustit neměly, máte chamtivou deku a potřebujete vyloučení. Přesně tento protokol provádíme při testování katalogu a je to stejná disciplína, jakou učí skill Systematic Debugging: nejdřív reprodukuj, jedna proměnná po druhé, věř důkazům.

Když se spustí, ale nic nedělá

Předpokládejme, že skill se aktivuje. Můžete si to potvrdit tak, že se Clauda uprostřed konverzace zeptáte, zda se pro požadavek načetl nějaký skill, a on vám to řekne. Ale výstup vypadá stejně jako předtím, než jste cokoli nainstalovali.

To není problém spouštění a nic z výše uvedeného to nespraví. Je to problém těla: instrukce uvnitř skilu jsou příliš vágní na to, aby změnily chování, nebo skill odkazuje na přibalené soubory, které na očekávaných cestách neexistují, nebo volá skript, jehož závislosti nikdo nedeklaroval. Popis dostal skill do dveří a obsah se uvnitř skácel.

V našem testování je tohle druhý velký koš selhání, zhruba zrcadlový obraz vad spouštění, a je to hlavní důvod, proč asi polovina komunitních skilů neprojde našimi testy. Rychlý rozlišovač: pokud se chování nezměnilo vůbec, podezírejte spouštění; pokud se změnilo, ale špatně nebo částečně, podezírejte tělo. Debugujte podle toho, protože opravy se nepřekrývají.

Platformní zádrhely

Formát skilů je všude identický, ale objevování ne — a skill, který funguje na jednom místě, může jinde vypadat mrtvý.

Claude Code čte složky na disku: ~/.claude/skills/ pro osobní, .claude/skills/ per projekt. Načítají se obě; kolize názvů mezi oběma rozsahy se vyřeší jedním vítězem (kontrola 3). Po každé změně restartujte sezení.

Claude Desktop vaše složky se skilly nečte. Skilly se nahrávají jako zip přes Settings, v části Capabilities, a zip musí obsahovat složku skilu na nejvyšší úrovni — ne holý SKILL.md a ne obalový adresář. Skill, který se v Claude Code spouští bez problémů, bude na Desktopu prostě chybět, dokud ho tam nenahrajete zvlášť.

claude.ai používá stejnou cestu nahrání jako Desktop, se dvěma dalšími způsoby, jak prohrát: skilly potřebují na vašem plánu zapnutou funkci spouštění kódu a administrátoři workspace mohou skilly vypnout pro celou organizaci — v tom případě se nic, co nahrajete, nikdy nespustí a žádná chyba to neřekne. Zeptejte se svého admina, než strávíte večer přepisováním popisů.

Ještě jedna past napříč platformami: tělo skilu napsané pro Claude Code, které volá git nebo čte lokální projektové soubory, se na claude.ai správně spustí a pak selže uvnitř sandboxu. To je problém těla v platformním kostýmu.

Kdy přestat debugovat

Pokud je to váš vlastní skill, pokračujte, protože každá oprava výše je trvalá a validátor plus test pěti formulací vás tam dovedou. Pokud je to skill třetí strany a spálili jste víc než dvacet minut na cizím poli description, je fér vyměnit ho za takový, který už tímto checklistem prošel: každý skill na našich žebříčcích nejlepších prošel testem spouštění na čistém stroji, než jsme ho zařadili.

FAQ

Jak si potvrdím, že je skill vůbec nainstalovaný?

Zeptejte se Clauda „jaké skilly máš nainstalované?" v novém sezení. Pokud váš skill v odpovědi není, problém je v objevování (kontroly 1, 3 a 5: složka, kolize, frontmatter), ne ve spouštění. Pokud v seznamu je, ale nikdy se neaktivuje, problém je v popisu (kontroly 4 a 6).

Můžu skill prostě donutit ke spuštění tím, že ho jmenuju?

Ano. „Use the docx skill to write this memo" načte skill přímo a jako dočasné řešení při debugování je to v pořádku. Oprava to ale není: skill, který musíte pokaždé přivolávat jménem, je skill s rozbitým popisem — a zapomenete ho přivolat přesně ve chvíli, kdy na tom záleží.

Proč můj skill funguje v Claude Code, ale ne na Desktopu nebo claude.ai?

Různé cesty objevování. Claude Code čte složky na disku; Desktop a claude.ai vidí jen skilly nahrané přes Settings jako zip se složkou skilu na nejvyšší úrovni. Na claude.ai si navíc ověřte, že je zapnuté spouštění kódu a že administrátor vašeho workspace skilly úplně nevypnul.

Rozbije spouštění, když nainstaluju příliš mnoho skilů?

Přímo ne. Padesát skilů stojí pár tisíc tokenů metadat, což je levné. Skutečné riziko je překryv: čím víc popisů nainstalujete, tím pravděpodobněji si dva z nich nárokují stejné území — a pak občas vyhraje ten špatný (kontrola 6). Instalujte podle potřeby a prořezávejte skilly, které se nikdy nespouštějí.

Můj skill se včera spustil a dnes ne. Je to normální?

Občas ano. Párování řídí model, ne regex, takže hraniční popis se na jednu formulaci spustí a téměř identickou mine. Pokud je skill spíš nespolehlivý než mrtvý, berte to jako slabý popis: přidejte do pole description přesné fráze, které minuly, restartujte a otestujte znovu. Spolehlivé skilly se spouštějí na každou rozumnou formulaci — proto testujeme s pěti, ne s jednou.