Skills: jak agentovi nasadit hotovou dovednost

Některou prosbu opakujete pořád dokola: podívej se na změny, zkontroluj tyhle soubory, udělej to takhle a sem nelez. Pokaždé vysvětlujete postup znovu a trošku jinak.

Výsledek kolísá spolu s formulací. Dnes to vyšlo skvěle, zítra jste zapomněli polovinu podmínek a agent poctivě udělal, co slyšel.

Řešením není paměť agenta, ale složka s instrukcí. Skill je jednou zapsaný postup, který Claude Code může připojit sám nebo na váš příkaz. Ukážeme si, kde ta složka leží, jak ověřit, že se skill načetl, a co zkontrolovat před prvním spuštěním.

Co je to skill

Než se pustíme do souborů a polí, nejdřív trochu intuice.

Představte si truhláře. Jednou si sepsal svůj obvyklý pracovní postup, připravil si poznámky, šablony a program pro stroj. Teď stačí krátce: "ukliď všechno, naostři vrták, pak židle pro kočku - spusť CNC šablonu". Spustil - a jede se.

Zapsaný postup drží celou práci pohromadě:

• Udržuje pořádek podle vašich pravidel. Uklidí ponk, rozloží nářadí - pokaždé stejně, přesně jak jste zvyklí.
• Dodržuje zapsané hranice. Pila se ještě točí - nesahá na ni. Bezpečnou část práce udělá hned, bez zbytečných otázek.
• Kouká do poznámek, když je potřeba. Je třeba naostřit vrták - otevře si pravidlo pro ostření. Nedrží ho v hlavě dopředu, vytáhne ho, až když ho potřebuje.
• Má šablony pro různé práce. Přešli jste od stolů k židlím - vezme hotové schéma přípravy.
• Spouští složité věci jedním příkazem. Program opakovaných řezů už leží připravený vedle. Stačí říct: "najdi šablonu Židle pro kočku a pusť ji na CNC" - stroj dodrží vůle i pořadí operací.

Skill funguje stejně. Není to další nástroj v rukou agenta, je to zabalený postup. Hlavní instrukce drží pořadí a hranice, příručky dodávají detaily, když jsou potřeba, šablony uchovávají polotovary a skripty spouštějí opakovanou mechaniku. Jednou jste to popsali - pak se to jenom volá.

Samotný formát skillu nic neizoluje. Instrukce může práci omezit jen na vzhled, ale technická zeď mezi CSS a logikou neexistuje. Dobrý skill jasně pojmenuje oblast práce; po spuštění se podíváte na změněné soubory a zkontrolujete chování stránky. "Funguje" a "vypadá" jsou různé vrstvy a jistotu dává kontrola, ne formát.

Kde se skill nachází

Tady není žádné cloudové kouzlo. Skill je složka na disku, ve vašem projektu:

.claude/skills/web-design/SKILL.md

Cestu si rozeberme po částech: pomocná složka .claude, v ní skills, v ní složka samotného skillu (jméno vymýšlíte vy) a v ní soubor SKILL.md. Obyčejný textový soubor, otevřete ho čímkoli.

U skillů v projektu a v domovské složce se z názvu adresáře stává příkaz s lomítkem, pokud samotný soubor neurčuje jiné jméno (o tom níže). Vymýšlejte ho proto rovnou s ohledem na to, jak bude vypadat v chatu.

Teď oprava nejčastější představy: skill není jeden soubor, je to složka. Vedle SKILL.md tam může být cokoli.

.claude/
└── skills/
    └── web-design/
        ├── SKILL.md      # hlavní soubor: popis a instrukce
        ├── palettes.md   # příručka, agent ji otevře, když ji bude potřebovat
        └── scripts/
            └── check.py  # skript, který je možné spustit

Pro automatický výběr má agent k dispozici jméno a krátký popis skillu, ne celé tělo. SKILL.md se načítá při spuštění, sousední příručky až podle potřeby. Dlouhý tahák proto nezabírá kontext předem.

Pro běžnou lokální práci jsou důležité tři zdroje skillů:

Symbol ~ znamená domovskou složku uživatele. V příkazech se nechává tak, jak je; pokud složku otevíráte ručně, přejděte do svého domovského adresáře.

Rozdíl mezi prvními dvěma místy je jednoduchý a vyplatí se ho pochopit hned.

Dali jste složku do projektu - skill funguje jen v tomto projektu. Otevřete vedlejší projekt a tam už není.

Skill v domovské složce je dostupný ve všech projektech. Pro obecný postup je to pohodlné, jenže se může zapnout i tam, kde ho nečekáte. Univerzální věci patří domů, projektové zůstávají v projektu.

Pokud je Claude Code spuštěný se samostatným učebním profilem ~/.claude-codegym/, osobní skilly leží v jeho složce skills/. Projektová cesta .claude/skills/ se s profilem nemění.

Description rozhoduje, kdy se skill spustí

Typický příběh: složku jste přidali, soubor je na místě, a agent se chová přesně jako dřív. Nic není rozbité - jen nepoznal, že se sem tento skill hodí.

Podívejte se, co má agent v okamžiku výběru k dispozici. Tělo samotného skillu ještě nečetl: načtený je jen seznam jmen a popisů. Rozhoduje se tedy podle popisu a podle ničeho jiného.

Sestavme si minimální skill pro projekt od začátku do konce. Jmenuje se web-design - tak se jmenuje složka a z ní vzniká i příkaz /web-design. Zvlášť do souboru tady jméno nepíšeme, složka ho už určila:

.claude/skills/web-design/SKILL.md

A uvnitř je tohle, nic dalšího není potřeba:

---
description: Dá webové rozhraní do pořádku - moderní CSS, plynulé přechody,
  sladěná paleta. Použít, když uživatel chce, aby to vypadalo hezky nebo stylově.
---

# Webový design

Používej jemné stíny, plynulé přechody a promyšlenou typografii.
Paletu drž sladěnou, animace - na najetí myší a zobrazení prvků.

Nahoře mezi trojitými pomlčkami je pomocný blok, dole běžný text instrukce. Povinná pole nejsou, ale description se vyplatí psát vždycky: bez něj agent hádá účel skillu podle prvního odstavce těla, a to je loterie.

Dobrý popis odpovídá na dvě otázky: co skill dělá a kdy ho použít. A to slovy, kterými své požadavky opravdu píšete.

# mlčí: není jasné, kdy ho použít
description: Pomáhá se vzhledem

# funguje: říká, co dělá i kdy
description: Dá rozhraní do pořádku - CSS, typografie, paleta.
  Použít, když uživatel chce, aby to vypadalo hezky, stylově, nebo chce opravit layout.

Popis rozhoduje o tom, kdy se skill spustí sám. Není to ale jediný vstup: skill má jméno a podle něj ho můžete zavolat ručně. Napíšete /web-design - a popis vůbec nehraje roli, soubor se přečte a provede.

V hotových skillech často narazíte na pole name. U skillů v projektu a v domovské složce toto pole určuje příkaz, který se zobrazí v menu po zadání /: složka deploy-staging s name: deploy se volá jako /deploy. Název adresáře přitom funguje dál. V pluginu name může určit poslední část příkazu za názvem pluginu.

Cesty ke spuštění jsou tedy dvě, a všechno za nimi už je stejné.

Levá větev je automatická: požadavek se shodoval s popisem a agent si skill vzal. Pravá je ruční: zadali jste /web-design a skill se spustil nezávisle na popisu.

Skilly se objevují ve stejné nabídce po / jako vestavěné příkazy. Soubor .claude/commands/deploy.md a skill .claude/skills/deploy/SKILL.md vytvoří jeden příkaz /deploy; pokud existují oba, vyhraje skill.

Instalace a kontrola

Složku jste přidali. Jak poznat, že ji agent opravdu vidí, a soubor jen neleží na disku?

/skills

Příkaz otevře seznam skillů a ukáže jejich zdroj. Napište pár písmen - seznam se zúží. Našli jste jméno své složky a stav on - Claude Code vidí skill a povoluje jeho spuštění.

Jméno, zdroj a stav on potvrzují, že skill je dostupný

Claude Code obvykle načte nový nebo změněný SKILL.md za běhu. Pokud jméno v seznamu není, zkuste postupně:

Skill v seznamu je, ale sám se nezapne? Opětovné načtení tady nepomůže. Zkontrolujte description a pole disable-model-invocation: true - to nechává jen ruční spuštění. Přeformulujte prosbu nebo zavolejte skill jménem. Ruční volání funguje - instalace je tedy v pořádku.

Co zkontrolovat, než skillu začnete věřit

Tady je potřeba trochu zchladit nadšení. Skill není vzhledový motiv ani obrázek, který nasadíte a zase sundáte. Jsou to instrukce, které váš agent provede ve vašem projektu.

Kontrolovat je třeba nejen hlavní soubor, ale celou složku. Začněte čtyřmi věcmi:

• popis - odpovídá tomu, co od skillu čekáte, a nespouští se příliš široce;
• tělo a odkazy v něm - co skill agentovi nařizuje a které sousední soubory chce otevřít;
• složka scripts/, pokud existuje - jaké příkazy se v ní spouštějí a na jaké soubory a síťové adresy sahají;
• pole allowed-tools - které nástroje skill předem povoluje používat bez samostatného dotazu.

---
name: pre-commit-style
description: Před commitem sjednotí styl projektu
allowed-tools: Read, Write, Edit, Glob
---

Pole allowed-tools tu nepopisuje plán práce a neomezuje celou sadu agentových možností. Jen předem schvaluje uvedené nástroje pro ten krok, ve kterém byl skill vyvolán. Jména se čtou jednoduše:

• Read - čtení souborů;
• Write - vytváření nových souborů a přepisování existujících celých;
• Edit - úpravy uvnitř existujícího souboru;
• Glob - hledání souborů podle masky, tedy procházení projektu a zjišťování, co v něm vůbec je.

První a poslední se jen dívají. Write a Edit umí soubory měnit: pokud k takové akci instrukce povede, samostatný dotaz v tomto kroku přijít nemusí. Oprávnění ale neznamená, že ho agent nutně využije. Obecná pravidla přístupu v projektu přitom platí dál.

Samo pole není nic zlého: ruší zbytečná potvrzení tam, kde přesně to chcete. Sadu ale vybíral autor skillu, a proto se na ni vyplatí podívat před prvním spuštěním.

A nakonec něco méně strašidelného, zato mnohem častějšího. Skill agenta usměrňuje, ale výsledek nezaručuje. Po spuštění se podívejte na změněné soubory a zkontrolujte výsledek: skill na vzhled může stránku zkrášlit, ale funkčnost tlačítka za něj nikdo nepotvrdí.

Kde vzít hotové

Abyste si skilly vyzkoušeli, nemusíte psát SKILL.md od nuly. Hotové skilly se nejčastěji najdou v otevřených repozitářích nebo přijdou spolu s pluginy.

Nejkratší cesta je požádat agenta, ať najde vhodnou variantu, ale neinstaluje ji naslepo. Zadání může vypadat třeba takhle:

Najdi skill na úpravu vzhledu rozhraní. Ukaž zdroj, SKILL.md a skripty,
vysvětli, jaké soubory a nástroje používá. Dokud to nepotvrdím,
nic neinstaluj.

Zdroj a obsah jste prošli - pak agenta požádejte, ať složku uloží do .claude/skills/ projektu, a výsledek ověřte přes /skills.

Pro vlastní hledání se hodí dotaz Claude skills marketplace. Katalog pomáhá najít varianty, ale není zárukou bezpečnosti: obsah se stejně čte před instalací.

SKILL.md se řídí otevřeným standardem Agent Skills, takže základní struktura se přenáší mezi různými agenty. Ale Claude Code přidává vlastní pole a způsoby spouštění. Přenesli jste skill do jiného nástroje - zkontrolujte, které jeho možnosti tam opravdu fungují.

Vlastní skill můžete sestavit s agentem

Chvíli, kdy je čas založit vlastní skill, poznáte i bez teorie: stejný postup vysvětlujete už potřetí. Ne úkol, ale právě pořadí kroků - podívej se na tohle, zkontroluj tamto, udělej to takhle, sem nelez. Opakuje se to - tak to dozrálo.

A teď dobrá zpráva. Psát SKILL.md od prázdné stránky nemusíte. Koncept může sestavit agent, od vás je potřeba vysvětlit, o jaký postup jde a co od něj chcete. Vypadá to jako běžný rozhovor:

Udělej skill na přípravu commitu. Má se podívat, co se změnilo,
zkontrolovat, jestli se do commitu nedostaly zbytečné soubory, a napsat zprávu
podle naší šablony. Spouštět ho budu ručně, až budu chtít.
Pokud ti chybí požadavky, nejdřív se zeptej.

Všimněte si, že jste nejmenovali ani jedno pole a do struktury souboru jste nezasahovali. Požadavky jste řekli slovy, převést je do polí je práce agenta.

Když údaje chybí, agent se zeptá. Bez takové prosby může rovnou něco předpokládat, proto je potřebný řádek už v příkladu. Až koncept dostanete, zkontrolujte soubory, najděte skill přes /skills a udělejte zkušební spuštění.

Pokud se dá postup projít ručně, udělejte to s agentem ještě před zabalením. Jeden commit krok za krokem ukáže, kde bylo potřeba ho opravit a co ve vysvětlení chybělo. Skill podle živého průchodu je přesnější než podle vzpomínek.

Když se SKILL.md rozrůstá

První vlastní skill skoro vždycky vyjde jako jeden soubor a je to v pořádku. Těsno začne být později: postup obroste detaily, dovnitř se nastěhuje převodní tabulka, seznam pravidel, tři dlouhé příklady, a jednoho dne otevřete soubor na čtyři obrazovky.

Skládat všechno na jedno místo nemusíte a důvod už padl výše: jakmile se skill pustí do práce, tělo se načte celé. Čtyři obrazovky příručky se tak do práce dostanou i tehdy, když z nich potřebujete jediný řádek.

Proto se detaily přesouvají do sousedních souborů a v SKILL.md zůstává odkaz: v takové a takové situaci otevři takový soubor. Složku s palettes.md a scripts/ jste už viděli, takhle vypadá zevnitř:

## Příručky

- Palety a kombinace barev - v [palettes.md](palettes.md)
- Hotové ukázky značkování - v [examples.md](examples.md)
- Kontrola kontrastu: spusť scripts/check.py

Příručku agent otevře, až ji bude potřebovat. Skript lze spustit, aniž by se celý jeho zdrojový kód automaticky načetl do konverzace, takže velikost souboru kontext skoro nezatěžuje. Cizí skript si ale před prvním spuštěním stejně přečtěte: je to spustitelný kód a jeho výstup se dostane do agentovy práce.

Rozdělit obsah se hodí podle účelu:

• SKILL.md - samotný postup: co dělat, v jakém pořadí, co nedělat. Před vyvoláním agent vidí jeho popis, tělo načte při spuštění;
• příručky - tabulky, pravidla, dlouhé příklady, zkrátka vše, co není potřeba při každém spuštění;
• scripts/ - to, co je snazší provést, než popsat slovy. V cizím skillu se tyto soubory kontrolují před spuštěním;
• šablony - soubory, které skill vezme jako základ a upraví podle úlohy.

Odtud plyne i opačný závěr, tentokrát o cizích skillech. Krátký SKILL.md neznamená "jednoduchý skill". Podívejte se, co leží ve složce vedle něj.

Co to mění v práci

Když to celé shrneme do pár řádků:

• opakovaná prosba se mění ve složku. Jednou popíšete pořadí práce - a dál se opakuje stejně, v každé relaci a v kterýkoli den;
• vlastní skill nemusíte psát od nuly. Vysvětlíte postup slovy, požádáte o doplňující otázky a zkontrolujete sestavený koncept;
• při automatickém spuštění se skill vybírá podle description, při ručním podle jména s lomítkem. Když mlčí, zjistěte nejdřív, jestli je vidět v seznamu a jestli má povolené automatické spuštění;
• /skills odpoví na otázku "načetl se vůbec?". Půl minuty kontroly ušetří půl hodiny hádání;
• cizí skill se čte před instalací a spuštěním, spolu se souvisejícími soubory a skripty;
• skill mění, jak agent dělá práci, ale neizoluje oblast úprav a neruší kontrolu výsledku.