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

Claude Code skills sú súbory SKILL.md s inštrukciami, ktoré si agent načíta, keď ich úloha potrebuje. Plugin zabalí skills, agentov a hooky do jedného celku, ktorý nainštalujete do mnohých repozitárov. My máme jeden plugin, wizrd (náš interný plugin a CLI pre Claude Code, nie je verejný), zapnutý v commitnutých nastaveniach repozitára, a validátor v CI zhodí repozitár, keď je niektorý skill pokazený.

K tomu nás doviedol neporiadok: kópie tých istých skills v niekoľkých repozitároch, každá trochu iná. Nižšie je, ako skills a pluginy fungujú, ako načítavame jeden plugin všade a čo sa nám cestou pokazilo.

Čo sú Claude Code skills a pluginy?

Skill je priečinok s jedným súborom, SKILL.md. Hore je frontmatter s poľami name a description, pod ním inštrukcie. Dokumentácia Claude Code to hovorí jasne: popisy skills sú v kontexte, aby Claude vedel, čo má k dispozícii, a celý obsah skillu sa načíta, až keď sa použije. Skill si môžete spustiť aj sami ako /nazov.

Plugin je priečinok so skills, agentmi, hookmi alebo MCP servermi, ktorý Claude Code nainštaluje a načíta ako jeden celok. Manifest má v .claude-plugin/plugin.json. Skills z pluginu dostanú menný priestor, takže náš review skill beží ako /wizrd:review a nikdy nekoliduje s vlastným /review projektu.

Kam ktorá časť patrí:

Najdôležitejší je posledný stĺpec. Skill agentovi povie, ako úlohu urobiť dobre. Nič nevynúti. Čo musí platiť, patrí do hooku, lint pravidla alebo CI.

Prečo sme všetky skills dali do jedného pluginu?

Naše firemné repo drží každé klientske repo a každú službu ako submodul. Session spustená v klientskom repozitári firemné skills nevidela, lebo Claude Code hľadá skills projektu len po koreň repozitára, v ktorom je.

Tak sa skills kopírovali. Viaceré klientske repá mali vlastné verzie plan, execute a review. Keď sme ich porovnali, každá kópia sa od ostatných rozišla. Nikto to nerozhodol. Stalo sa to samo, jedna malá oprava za druhou, v jednom repe áno, v ďalšom nie.

Riešením nebola väčšia disciplína. Bol to jeden plugin, ktorý sa načíta všade. Odvtedy session vo firemnom repe, v klientskom repe aj v repe služby dostane rovnaké skills, agentov a hooky. Zmena ide jedným PR a staré kópie sme zmazali v sprievodných PR.

Ako sa jeden plugin načíta v každom repozitári?

Plugin potrebuje domov, ktorý sa volá marketplace. Je to len súbor .claude-plugin/marketplace.json, ktorý vypíše pluginy a odkiaľ sa každý stiahne. Náš obsahuje jeden plugin, samotné repo:

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

Repozitár, ktorý ho používa, plugin zapne v commitnutom .claude/settings.json. Toto je skutočný blok z nášho firemného repa, kde je repo pluginu submodul v services/wizrd:

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

Poradie, ktoré by sme zopakovali:

Hooky sa šíria rovnako. Náš plugin dodáva pozdrav na SessionStart a dva PreToolUse hooky na Bash: jeden blokuje AI podpisy v commitoch a PR, druhý blokuje pushe, ktoré operátor nesmie urobiť. Ich cesty začínajú ${CLAUDE_PLUGIN_ROOT}, takže fungujú v každom repozitári. Prečo na tom záleží, je v článku Claude Code hooks: prečo naše hooky nerobili nič.

Čo skill potrebuje, aby fungoval pre tím?

Menej, ako sme si najprv mysleli. Skutočný frontmatter z nášho pluginu, popis je skrátený:

---
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 nesú tri polia:

• description so skutočnými spúšťačmi. Podľa tohto riadku model rozhoduje, či skill načíta. „Pomáha s issues“ sa načíta náhodne. Slová, ktoré ľudia naozaj píšu, ho načítajú vtedy, keď má.
• audience: human, agent alebo both. Je to naše vlastné pole, nie pole Claude Code. Skill, ktorý agent púšťa sám, nesmie nikdy čakať na človeka. Náš validátor upozorní, keď sa skill označený agent alebo both pýta cez popup alebo čaká na schválenie. Agent sa namiesto toho pýta na GitHube.
• Jasné názvy. Dva naše skills sa kedysi líšili jedným písmenom a robili opačné veci. Premenovali sme ich.

Istý čas sme v každom skille vyžadovali aj pevné sekcie: playbook, quality gate, rozhodovacie právomoci. Väčšinou len opakovali telo. Požiadavku sme zrušili a skills sme skrátili na inštrukcie, ktoré menia správanie. Validátor dnes chce len name, description a audience.

Čo sa nám cestou pokazilo?

Väčšina potichu. Veci prechádzali, hoci už nič nekontrolovali.

• Premenovanie, ktoré by v CI prechádzalo navždy. Keď nám plugin dal menný priestor, starý prefix v názve každého skillu bol zbytočný, tak sme ho zrušili. Naša kontrola odkazov na zmazané skills mala ten prefix natvrdo v regexe. Keby sme ju nechali tak, po premenovaní by nenašla nič a ostala by navždy zelená.
• Validátor označil živé skills za zastarané. Zoznam skills si skladal z lokálneho priečinka. Po presune do pluginu klientske repo, ktoré spomínalo plan alebo review, nemalo lokálne s čím porovnať a jeho CI zčervenalo. Oprava: čítať aj skills samotného pluginu.
• Skills, ktoré nikto nepoužíval. Niektoré skills nebežali celé mesiace. Každý aj tak sedel v kontexte pri každom ťahu, lebo názvy a popisy skills z pluginu sú načítané vždy. Zmazali sme ich. Tri varianty jedného skillu sa zlúčili do jedného s režimami a náš vlastný skill na písanie skills ustúpil vstavanému skill-creatoru.

Väčšinou šlo o mazanie. Ten vzorec vidíme stále: zdieľaný plugin ukáže zbytočnosti, lebo ich odrazu nosí každý v každej session.

Osobné alebo zdieľané: ktoré skills patria do pluginu?

Nie každý skill musí byť zdieľaný. Ako niekto rád pracuje, môže ostať v jeho ~/.claude/skills/. Čo potrebuje celý tím, patrí do pluginu: plánovanie, review, zakladanie issues, kroky, ktorými prechádza release pre klienta.

Náš plugin je interný, nedá sa nainštalovať. Náš verejný Claude Code production starter skills nemá. Nesie vrstvu pod nimi: pravidlá pre agenta, hooky a CI bránu. Tam by sme začali.

Čo z toho už váš tím má?

Čo patrí do pravidiel vedľa skills, rozoberáme v článku CLAUDE.md a AGENTS.md: pravidlá pre AI kód v tíme.

Chcete jedno zdieľané nastavenie pre agentov celého tímu?

Skills, hooky, pravidlá a CI nastavujeme priamo v repozitároch tímu v rámci služby AI-native SDLC pre vývojové tímy. Chýbajú vášmu tímu skôr ruky ako pravidlá? Pozrite si seniorského vývojára do vášho tímu. AI dnes píše všetok náš kód a za výsledok ručí senior. Od roku 2023 sme dodali 15+ produkčných projektov.

Ozveme sa do dvoch pracovných dní a spolu vyberieme, čo vyriešime ako prvé.

Ak sa chcete najprv porozprávať, dohodnite si meeting na 15 minút s Filipom.

Koľko kópií toho istého skillu dnes žije vo vašich repozitároch?

Časté otázky

Čo sú Claude Code skills?

Skill je priečinok so súborom SKILL.md: hore frontmatter s názvom a popisom, pod ním inštrukcie. Claude Code drží popis v kontexte a celé inštrukcie načíta, až keď ich úloha potrebuje, alebo keď skill spustíte ako /nazov.

Aký je rozdiel medzi skillom a pluginom?

Skill je jedna sada inštrukcií. Plugin je priečinok, ktorý balí skills, agentov, hooky a MCP servery ako jeden celok, s manifestom v .claude-plugin/plugin.json. Skills z pluginu majú menný priestor, naše bežia ako /wizrd:review.

Ako zdieľať Claude Code skills s tímom?

Dajte ich do pluginu, zapíšte plugin do marketplace a zapnite ho v commitnutom .claude/settings.json každého repozitára. Každý má rovnakú verziu a zmena sa dostane všade jedným PR, nie do kópií, ktoré sa rozídu.

Spomaľuje veľa skills Claude Code?

Každý skill, ktorý môže model spustiť sám, má názov a popis v kontexte pri každom ťahu. To stojí tokeny, aj keď nič nebeží. Skills, ktoré nikto nepoužíva, mažeme a popisy držíme krátke a konkrétne.

Nahradí skill hooky alebo kontroly v CI?

Nie. Skill obsahuje inštrukcie, ktoré agent môže dodržať. Čo musí platiť, patrí do hooku, lint pravidla, testu alebo CI, kde to agent nemôže preskočiť.