Claude Code skills a pluginy: jedna sada pro každé repo

Claude Code skills jsou soubory SKILL.md s instrukcemi, které si agent načte, když je úkol potřebuje. Plugin zabalí skills, agenty a hooky do jednoho celku, který nainstalujete do mnoha repozitářů. My máme jeden plugin, wizrd (náš interní plugin a CLI pro Claude Code, není veřejný), zapnutý v commitnutém nastavení repozitáře, a validátor v CI shodí repozitář, když je některý skill rozbitý.

K tomu nás dovedl nepořádek: kopie stejných skills v několika repozitářích, každá trochu jiná. Níže je, jak skills a pluginy fungují, jak načítáme jeden plugin všude a co se nám cestou rozbilo.

Co jsou Claude Code skills a pluginy?

Skill je složka s jedním souborem, SKILL.md. Nahoře je frontmatter s poli name a description, pod ním instrukce. Dokumentace Claude Code to říká jasně: popisy skills jsou v kontextu, aby Claude věděl, co má k dispozici, a celý obsah skillu se načte, až když se použije. Skill si můžete spustit i sami jako /nazev.

Plugin je složka se skills, agenty, hooky nebo MCP servery, kterou Claude Code nainstaluje a načte jako jeden celek. Manifest má v .claude-plugin/plugin.json. Skills z pluginu dostanou jmenný prostor, takže náš review skill běží jako /wizrd:review a nikdy se nepere s vlastním /review projektu.

Kam která část patří:

Nejdůležitější je poslední sloupec. Skill agentovi řekne, jak úkol udělat dobře. Nic nevynutí. Co musí platit, patří do hooku, lint pravidla nebo CI.

Proč jsme všechny skills dali do jednoho pluginu?

Naše firemní repo drží každé klientské repo a každou službu jako submodul. Session spuštěná v klientském repozitáři firemní skills neviděla, protože Claude Code hledá skills projektu jen po kořen repozitáře, ve kterém je.

Tak se skills kopírovaly. Několik klientských rep mělo vlastní verze plan, execute a review. Když jsme je porovnali, každá kopie se od ostatních rozešla. Nikdo to nerozhodl. Stalo se to samo, jedna malá oprava za druhou, v jednom repu ano, v dalším ne.

Řešením nebyla větší disciplína. Byl to jeden plugin, který se načte všude. Od té doby session ve firemním repu, v klientském repu i v repu služby dostane stejné skills, agenty a hooky. Změna jde jedním PR a staré kopie jsme smazali v doprovodných PR.

Jak se jeden plugin načte v každém repozitáři?

Plugin potřebuje domov, kterému se říká marketplace. Je to jen soubor .claude-plugin/marketplace.json, který vypíše pluginy a odkud se každý stáhne. Náš obsahuje jeden plugin, samotné repo:

{
  "name": "digitaliko",
  "plugins": [{ "name": "wizrd", "source": "./" }]
}

Repozitář, který ho používá, plugin zapne v commitnutém .claude/settings.json. Tohle je skutečný blok z našeho firemního repa, kde je repo pluginu submodul v services/wizrd:

{
  "enabledPlugins": { "wizrd@digitaliko": true },
  "extraKnownMarketplaces": {
    "digitaliko": { "source": { "source": "directory", "path": "services/wizrd" } }
  }
}

Pořadí, které bychom zopakovali:

Hooky cestují stejně. Náš plugin dodává pozdrav na SessionStart a dva PreToolUse hooky na Bash: jeden blokuje AI podpisy v commitech a PR, druhý blokuje pushe, které operátor nesmí udělat. Jejich cesty začínají ${CLAUDE_PLUGIN_ROOT}, takže fungují v každém repozitáři. Proč na tom záleží, je v článku Claude Code hooks: proč naše hooky nedělaly nic.

Co skill potřebuje, aby fungoval pro tým?

Méně, než jsme si nejdřív mysleli. Skutečný frontmatter z našeho pluginu, popis je zkrácený:

---
name: issue
description: Create GitHub issues at the right level following the canonical labels and issue-body spec. Triggers on /wizrd:issue, gh issue, file issue, create issue, log a task.
allowed-tools: Bash, Read
audience: both
---

Váhu nesou tři pole:

• description se skutečnými spouštěči. Podle tohoto řádku model rozhoduje, jestli skill načte. „Pomáhá s issues“ se načte náhodně. Slova, která lidé opravdu píšou, ho načtou tehdy, kdy má.
• audience: human, agent nebo both. Je to naše vlastní pole, ne pole Claude Code. Skill, který agent pouští sám, nesmí nikdy čekat na člověka. Náš validátor upozorní, když se skill označený agent nebo both ptá přes popup nebo čeká na schválení. Agent se místo toho ptá na GitHubu.
• Jasné názvy. Dva naše skills se kdysi lišily jedním písmenem a dělaly opačné věci. Přejmenovali jsme je.

Nějakou dobu jsme v každém skillu vyžadovali i pevné sekce: playbook, quality gate, rozhodovací pravomoci. Většinou jen opakovaly tělo. Požadavek jsme zrušili a skills zkrátili na instrukce, které mění chování. Validátor dnes chce jen name, description a audience.

Co se nám cestou rozbilo?

Většinou potichu. Věci procházely, i když už nic nekontrolovaly.

• Přejmenování, které by v CI procházelo navždy. Když nám plugin dal jmenný prostor, starý prefix v názvu každého skillu byl zbytečný, tak jsme ho zrušili. Naše kontrola odkazů na smazané skills měla ten prefix natvrdo v regexu. Kdybychom ji nechali být, po přejmenování by nenašla nic a zůstala by navždy zelená.
• Validátor označil živé skills za zastaralé. Seznam skills si skládal z lokální složky. Po přesunu do pluginu klientské repo, které zmiňovalo plan nebo review, nemělo lokálně s čím porovnat a jeho CI zčervenalo. Oprava: číst i skills samotného pluginu.
• Skills, které nikdo nepoužíval. Některé skills neběžely celé měsíce. Každý přesto seděl v kontextu při každém tahu, protože názvy a popisy skills z pluginu jsou načtené vždy. Smazali jsme je. Tři varianty jednoho skillu se sloučily do jednoho s režimy a náš vlastní skill na psaní skills ustoupil vestavěnému skill-creatoru.

Většina těchto oprav bylo mazání. Ten vzorec vidíme pořád: sdílený plugin ukáže zbytečnosti, protože je najednou nosí každý v každé session.

Osobní, nebo sdílené: které skills patří do pluginu?

Ne každý skill musí být sdílený. Jak kdo rád pracuje, může zůstat v jeho ~/.claude/skills/. Co potřebuje celý tým, patří do pluginu: plánování, review, zakládání issues, kroky, kterými prochází release pro klienta.

Náš plugin je interní, nainstalovat si ho nedá. Náš veřejný Claude Code production starter skills nemá. Nese vrstvu pod nimi: pravidla pro agenta, hooky a CI bránu. Tam bychom začali.

Co z toho už váš tým má?

Co patří do pravidel vedle skills, rozebíráme v článku CLAUDE.md a AGENTS.md: pravidla pro AI kód v týmu.

Chcete jedno sdílené nastavení pro agenty celého týmu?

Skills, hooky, pravidla a CI nastavujeme přímo v repozitářích týmu v rámci služby AI-native SDLC pro vývojové týmy. Chybí vašemu týmu spíš ruce než pravidla? Podívejte se na seniorního vývojáře do vašeho týmu. AI dnes píše veškerý náš kód a za výsledek ručí senior. Od roku 2023 jsme dodali 15+ produkčních projektů.

Ozveme se do dvou pracovních dnů a společně vybereme, co vyřešíme jako první.

Pokud si chcete nejdřív promluvit, domluvte si meeting na 15 minut s Filipem.

Kolik kopií stejného skillu dnes žije ve vašich repozitářích?

Časté otázky

Co jsou Claude Code skills?

Skill je složka se souborem SKILL.md: nahoře frontmatter s názvem a popisem, pod ním instrukce. Claude Code drží popis v kontextu a celé instrukce načte, až když je úkol potřebuje, nebo když skill spustíte jako /nazev.

Jaký je rozdíl mezi skillem a pluginem?

Skill je jedna sada instrukcí. Plugin je složka, která balí skills, agenty, hooky a MCP servery jako jeden celek, s manifestem v .claude-plugin/plugin.json. Skills z pluginu mají jmenný prostor, naše běží jako /wizrd:review.

Jak sdílet Claude Code skills s týmem?

Dejte je do pluginu, zapište plugin do marketplace a zapněte ho v commitnutém .claude/settings.json každého repozitáře. Každý má stejnou verzi a změna se dostane všude jedním PR, ne do kopií, které se rozejdou.

Zpomaluje hodně skills Claude Code?

Každý skill, který může model spustit sám, má název a popis v kontextu při každém tahu. To stojí tokeny, i když nic neběží. Skills, které nikdo nepoužívá, mažeme a popisy držíme krátké a konkrétní.

Nahradí skill hooky nebo kontroly v CI?

Ne. Skill jsou instrukce, které agent může dodržet. Co musí platit, patří do hooku, lint pravidla, testu nebo CI, kde to agent nemůže přeskočit.