Vytvoření doplňku

Tato příručka popisuje, jak vytvořit doplněk (plugin) pro CODEXIS AI 2.0 a jak ho zveřejnit, aby si ho mohl nainstalovat kdokoli. Dozvíte se, z čeho se doplněk skládá, co patří do manifestů a co vám platforma dává k dispozici: od hooků životního cyklu po proměnné prostředí.

Nejlepším zdrojem funkčních příkladů je oficiální marketplace. Svůj doplněk tam přidávat nebudete (zveřejníte vlastní, viz níže), ale jako předloha poslouží výborně: ares je nejjednodušší doplněk typu „dovednost + jeden nástroj“, codexis je nejkomplexnější.

Doplněk je složka plugins/<name>/. Může obsahovat v libovolné kombinaci dovednosti (Markdown s pokyny, kdy a jak má AI něco udělat; jádro většiny doplňků), nástroje příkazové řádky (malé předkompilované programy v bin/, které AI spouští), hooky životního cyklu (příkazy spouštěné při instalaci, aktualizaci a odinstalaci), komponenty (vestavěné webové dashboardy) a automatizace (naplánované úlohy). Úplně nejmenší doplněk tvoří plugin.json a jediný SKILL.md; všechno ostatní je volitelné.

Jak se doplňky distribuují: váš vlastní marketplace

Doplňky se instalují vždy z marketplace, tedy z git repozitáře se seznamem jednoho nebo více doplňků. Doplněk nelze nainstalovat samostatně: i jediný doplněk se šíří jako marketplace s jedním záznamem.

Svůj doplněk nepřidáváte do oficiálního marketplace. Zveřejníte vlastní: git repozitář, který obsahuje .claude-plugin/marketplace.json a složku plugins/.

your-marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json     # seznam vašich doplňků
└── plugins/
    └── your-plugin/         # samotný doplněk (vše ostatní v této příručce)

Kdokoli si ho nainstaluje tak, že si v CODEXISu přidá váš repozitář jako marketplace: zvolí zdroj typu Git, vloží URL repozitáře (volitelně i větev nebo tag) a nainstaluje kterýkoli z nabízených doplňků. Nepotřebuje k tomu administrátorská práva ani nic od nás; každý uživatel si CODEXIS nasměruje na repozitáře, kterým důvěřuje.

Zbytek příručky popisuje soubory uvnitř plugins/<name>/ ve vašem repozitáři.

Formát doplňku a podporované komponenty

Doplňky CODEXIS používají standardní formát doplňků Claude Code: manifest .claude-plugin/plugin.json přímo ve složce doplňku a vedle něj soubory komponent v podsložkách s ustálenými názvy. Držte se těchto konvencí:

• Dovednosti a agenty definujte v Markdownu s YAML frontmatterem (hooky a MCP v JSON).
• Doplněk i každou komponentu pojmenujte malými písmeny, slova oddělte pomlčkou, bez mezer.
• U dovedností a agentů je description psaný pro model: právě podle něj se AI rozhoduje, kdy dovednost nebo agenta použít. Buďte konkrétní a nešetřete spouštěcími slovy a frázemi.
• SKILL.md udržujte krátký. Podrobnosti přesuňte do referenčních souborů, které si AI načte, až je bude potřebovat.
• Na vlastní soubory se z hooků odkazujte přes ${PLUGIN_DIR} (obdoba ${CLAUDE_PLUGIN_ROOT} z Claude Code).

Platforma ale nenačítá všechny typy komponent, které Claude Code zná. Co CODEXIS AI 2.0 skutečně čte:

Nad rámec standardního formátu platforma přidává hooky životního cyklu (postInstall / postUninstall / onUpdate), vlastní blok env doplňku, dodávané proměnné CODEXIS_USER_* / CODEXIS_PUBLIC_*, trojjazyčná metadata i18n, vestavěné dashboardy popsané souborem component.json a naplánované automatizace. Všechno popisujeme níže.

Většina doplňků si vystačí jen s dovednostmi (a nástrojem příkazové řádky v bin/). Agenty, event hooky a MCP servery přidejte, až je budete potřebovat.

Kde a jak doplněk běží

Když si uživatel váš doplněk nainstaluje, složka doplňku se zkopíruje do jeho soukromého linuxového sandboxu a tam se spustí instalační hook. Ve stejném sandboxu pak běží i každý příkaz, který AI přes váš doplněk vykoná. Na co se můžete spolehnout:

• Je to Linux. Binárky musí být linuxové, sestavené pro architekturu sandboxu (amd64 nebo arm64).
• Složka ~/.local/bin je první v PATH a můžete do ní zapisovat. Stačí do ní nástroj nakopírovat a AI ho může volat jménem, bez celé cesty a bez sudo.
• Hooky běží v plnohodnotném shellu: pracovní adresář je nastavený na složku doplňku, platí limit 5 minut a proměnná $PLUGIN_DIR na tuto složku ukazuje.
• K dispozici jsou proměnné prostředí CODEXIS_* (viz níže).
• Odchozí síť může být omezená. Administrátor může sandbox omezit jen na schválené cíle; nástroj, který volá externí API, pak může potřebovat doménu na seznamu povolených (allow-list). Nepočítejte s volným přístupem k internetu.
• Domovský adresář je sdílené úložiště (připojené přes NFS). Synchronizují se do něj vybrané složky z počítače uživatele nebo z firemního souborového serveru a vaše nástroje je čtou jako běžné cesty pod $HOME.

Když hook selže: neúspěšný postInstall přeruší instalaci; neúspěšný postUninstall nebo onUpdate se jen zapíše do logu a operaci nezastaví. Prázdný hook neudělá nic.

Rychlý start: doplněk jen s dovedností

Nejmenší užitečný doplněk naučí AI pracovní postup a neobsahuje žádný program. Stačí tři soubory:

plugins/hello-law/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── hello-law/
        └── SKILL.md

plugins/hello-law/.claude-plugin/plugin.json:

{
  "name": "hello-law",
  "version": "1.0.0",
  "description": "Example plugin that explains how to greet a legal question.",
  "author": { "name": "Your Name", "email": "you@example.com" },
  "keywords": ["example"],
  "license": "PROPRIETARY",
  "tags": ["example"],
  "i18n": {
    "cs": { "displayName": "Hello Law", "description": "Ukázkový plugin.", "tagLabels": { "example": "Ukázka" } },
    "en": { "displayName": "Hello Law", "description": "Example plugin.",  "tagLabels": { "example": "Example" } },
    "sk": { "displayName": "Hello Law", "description": "Ukážkový plugin.", "tagLabels": { "example": "Ukážka" } }
  },
  "skills": "./skills"
}

plugins/hello-law/skills/hello-law/SKILL.md:

---
uuid: 00000000-0000-0000-0000-000000000001
name: hello-law
description: Use when the user asks to test the hello-law example plugin or says "hello law".
version: 1.0.0
i18n:
  cs: { displayName: "Hello Law", summary: "Ukázková dovednost." }
  en: { displayName: "Hello Law", summary: "Example skill." }
  sk: { displayName: "Hello Law", summary: "Ukážková zručnosť." }
---

# Hello Law

When the user asks you to "test hello law", confirm the example plugin is working. Do not call any
external tools.

Pak už doplněk jen zaregistrujte ve svém .claude-plugin/marketplace.json (viz níže). Tím máte hotový doplněk připravený k instalaci.

Struktura složky doplňku

Povinný je pouze .claude-plugin/plugin.json, všechno ostatní je volitelné. Takto vypadá codexis, nejkomplexnější doplněk:

plugins/<name>/
├── .claude-plugin/
│   └── plugin.json          # POVINNÉ: manifest
├── icon.svg                 # ikona v marketplace
├── README.md                # popis pro lidi
├── skills/                  # jedna složka na dovednost
│   └── <skill>/
│       ├── SKILL.md
│       ├── icon.svg         # volitelné
│       └── references/      # volitelné dokumenty načítané podle potřeby
├── agents/                  # volitelní subagenti (jeden .md na agenta)
├── bin/                     # předkompilované nástroje (commitnuté)
├── hooks/                   # instalační / odinstalační skripty (+ volitelný hooks.json)
├── .mcp.json                # volitelné definice MCP serverů
├── lib/                     # sdílený knihovní kód pro vaše nástroje/komponenty
├── components/              # vestavěné webové dashboardy (pokročilé)
└── automations/             # naplánované úlohy

Na reálných příkladech jsou vidět tři úrovně složitosti: jen dovednosti (visualization) vystačí s plugin.json + skills/; dovednost + jeden nástroj (ares) přidává bin/, hooks/ a hooky životního cyklu; všechno (codexis) přidává ještě components/, automations/ a lib/.

Dva manifesty

.claude-plugin/marketplace.json (v hlavní složce vašeho marketplace repozitáře)

Manifest vašeho vlastního marketplace. Každý doplněk uveďte v poli plugins. Manifest je benevolentní: když name nebo uuid vynecháte, odvodí se automaticky, a doplňky se navíc samy najdou ve složce plugins/. Přesto doporučujeme každý doplněk uvést výslovně, včetně i18n:

{
  "uuid": "GENERATE-A-NEW-UUID",
  "name": "your-plugin",
  "description": "One-line English description.",
  "source": "./plugins/your-plugin",
  "category": "legal",
  "i18n": {
    "cs": { "displayName": "Český název", "description": "Český popis.", "tagLabels": { "legal": "Právo" } },
    "en": { "displayName": "English name", "description": "English description.", "tagLabels": { "legal": "Law" } },
    "sk": { "displayName": "Slovenský názov", "description": "Slovenský popis.", "tagLabels": { "legal": "Právo" } }
  }
}

• name se musí shodovat s name v plugin.json a se složkou uvedenou v source.
• source je vždy ./plugins/<name>.
• category zařadí doplněk do kategorie. Existující kategorie: legal, visualization, document-processing, media, open-data.
• tagLabels překládá klíče tagů z pole tags v plugin.json.

plugins/<name>/.claude-plugin/plugin.json

Popisuje váš doplněk. Povinná jsou pole name, version a description; ostatní přidejte podle potřeby:

{
  "name": "your-plugin",
  "version": "1.0.0",
  "description": "English description used for discovery.",
  "author": { "name": "Your Name", "email": "you@example.com" },
  "keywords": ["search", "terms"],
  "license": "PROPRIETARY",
  "tags": ["legal", "czech"],
  "i18n": {
    "cs": { "displayName": "...", "description": "...", "tagLabels": { "legal": "Právo", "czech": "Česko" } },
    "en": { "displayName": "...", "description": "...", "tagLabels": { "legal": "Law",   "czech": "Czech Republic" } },
    "sk": { "displayName": "...", "description": "...", "tagLabels": { "legal": "Právo", "czech": "Česko" } }
  },

  "skills": "./skills",
  "components": "./components",

  "env": {
    "CODEXIS_PLUGIN_YOURPLUGIN_API_URL": "https://api.example.com"
  },

  "postInstall":   "bash \"${PLUGIN_DIR}/hooks/install-binaries.sh\"",
  "postUninstall": "bash \"${PLUGIN_DIR}/hooks/uninstall-binaries.sh\"",
  "onUpdate":      "bash \"${PLUGIN_DIR}/hooks/install-binaries.sh\""
}

Jak napsat SKILL.md

Dovednost je Markdown soubor: frontmatter (blok mezi řádky ---) a za ním instrukce psané pro AI.

---
uuid: 214caaa4-3728-4d21-b379-ab4b376b7615
name: ares
description: Use for company / sole-trader lookups by IČO or name. Triggers on "ares", "ičo", "obchodní rejstřík", "živnostenský rejstřík", "plátce DPH", "vyhledej firmu", "kdo je jednatel".
version: 0.1.0
i18n:
  cs: { displayName: "ARES - registr ekonomických subjektů", summary: "Vyhledávání firem a OSVČ v ARES." }
  en: { displayName: "ARES - Czech Business Registry", summary: "Look up companies and sole traders in ARES." }
  sk: { displayName: "ARES - register ekonomických subjektov", summary: "Vyhľadávanie firiem a SZČO v ARES." }
---

# ARES - Czech Business Registry

A single tool, `ares-cli`, wraps the ARES public REST API. Assume it is installed and on `PATH`.
Do NOT call `curl` or any other tool directly.

## Commands
...

Nejdůležitější pole je description. Uživatelům se nezobrazuje; AI se podle něj rozhoduje, kdy dovednost načíst. Pište ho jako pokyn plný spouštěcích slov a frází, ne jako mlhavé shrnutí.

Tělo dovednosti je samotný návod: jaký nástroj zavolat, s jakou přesnou syntaxí, jak číst výstup a co ukázat uživateli. Buďte konkrétní: uveďte ukázkové příkazy a rozhodovací strom.

SKILL.md udržujte stručný. Delší podrobnosti přesuňte do skills/<name>/references/*.md a v dovednosti na ně jen odkažte; AI si je načte, až je bude skutečně potřebovat.

Dodání nástroje: bin/ a hooky životního cyklu

Pokud má váš doplněk spouštět nástroj příkazové řádky, dodejte ho jako předkompilovanou binárku a hookem životního cyklu ho nainstalujte do PATH sandboxu.

Binárka

Do plugins/<name>/bin/<tool> commitněte samostatný (staticky linkovaný) linuxový spustitelný soubor. Použít můžete jakýkoli jazyk, který se zkompiluje do statické linuxové binárky; stávající doplňky používají Rust. Nástroj načte vstup a výsledky vypíše na stdout, ideálně jako JSON.

Instalace do PATH

Instalační hook má jediný úkol: zkopírovat binárku do ~/.local/bin, která už je v PATH. U jediné binárky nepotřebujete ani skript; příkazy zapište přímo do plugin.json (přesně tak to dělá doplněk ocr). ${PLUGIN_DIR} se rozvine na cestu ke složce nainstalovaného doplňku:

  "postInstall":   "sudo install -m 0755 \"${PLUGIN_DIR}/bin/my-tool\" \"${HOME}/.local/bin/my-tool\"",
  "postUninstall": "sudo rm -f \"${HOME}/.local/bin/my-tool\"",
  "onUpdate":      "sudo install -m 0755 \"${PLUGIN_DIR}/bin/my-tool\" \"${HOME}/.local/bin/my-tool\""

To je celý mechanismus. Platformu zajímá jediné: váš nástroj musí skončit v PATH.

Tři hooky životního cyklu

onUpdate obvykle jen zopakuje postInstall. Na soubory doplňku odkazujte přes ${PLUGIN_DIR}; je to obdoba ${CLAUDE_PLUGIN_ROOT} z Claude Code.

Proměnné prostředí

Vaše hooky i každý příkaz, který AI spustí, vidí tři skupiny proměnných.

CODEXIS_PLUGIN_* (deklarujete je vy)

Vlastní konfigurace doplňku (URL, ID). Deklarujete ji v bloku env v plugin.json:

  "env": {
    "CODEXIS_PLUGIN_YOURPLUGIN_API_URL": "https://api.example.com"
  }

Název začněte prefixem CODEXIS_PLUGIN_ a zbytek volte jedinečně pro svůj doplněk, aby nikdy nekolidoval s proměnnou jiného doplňku. Citlivé údaje sem nepatří; hodnoty jsou uložené přímo v manifestu. Konfiguraci deklarujte v env; nevytvářejte soubory .env ani nepoužívejte export uvnitř hooků.

CODEXIS_USER_* (dodávané citlivé údaje, jen ke čtení)

Tokeny a klíče konkrétního uživatele; dodává je platforma. Pouze je čtěte: nikdy je nelogujte ani je nevkládejte napevno do binárky.

CODEXIS_PUBLIC_* (dodávaný kontext, jen ke čtení)

Údaje o prostředí, ve kterém příkaz právě běží.

Hooky instalace, odinstalace a aktualizace běží mimo chat, takže dostanou URL platformy, domovský adresář i proměnné CODEXIS_USER_*, ale ne SESSION_ID / TOOL_CALL_ID.

Překlady (i18n)

Rozhraní je dostupné v češtině (cs), angličtině (en) a slovenštině (sk). Blok i18n má každý manifest i každá dovednost.

• Technické identifikátory (name, id, klíče tagů) se nikdy nepřekládají.
• description dovednosti se nikdy nepřekládá; je to spouštěč pro AI, ne text pro rozhraní.
• Překládají se jen zobrazované texty: displayName, description v manifestu, summary dovednosti a tagLabels.

JSON manifesty:

"i18n": {
  "cs": { "displayName": "...", "description": "...", "tagLabels": { "legal": "Právo" } },
  "en": { "displayName": "...", "description": "...", "tagLabels": { "legal": "Law" } },
  "sk": { "displayName": "...", "description": "...", "tagLabels": { "legal": "Právo" } }
}

Frontmatter SKILL.md (pozor: summary, ne description):

i18n:
  cs: { displayName: "...", summary: "..." }
  en: { displayName: "...", summary: "..." }
  sk: { displayName: "...", summary: "..." }

Když překlad chybí, použije se náhrada v pořadí požadovaný jazyk → en → nepřeložený name/description. Vyplňte minimálně en; cs a sk ale důrazně doporučujeme.

Volitelné: subagenti, event hooky, MCP, komponenty, automatizace

Subagenti (agents/<name>.md)

Subagent je specializovaný asistent, kterému AI může předat část práce. Dodejte ho jako Markdown soubor ve složce agents/, s frontmatterem a tělem, které slouží jako systémový prompt:

---
name: contract-reviewer
description: Use to review a contract draft for missing clauses and risky terms.
tools: Read, Grep
model: sonnet
---

You are a contract reviewer. Analyze the provided draft for missing standard clauses, ambiguous
terms, and one-sided liability. Report findings as a prioritized list.

Stejně jako u dovedností je description spouštěčem pro model. name pište malými písmeny, slova oddělujte pomlčkou. Složku agents/ platforma najde sama; v manifestu kvůli ní nic uvádět nemusíte.

Event hooky (hooks/hooks.json)

Event hooky spouštějí příkazy automaticky při událostech v chatu (na rozdíl od hooků životního cyklu výše, které běží při instalaci). Zapište je do hooks/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell",
        "hooks": [
          { "type": "command", "command": "bash \"${PLUGIN_DIR}/hooks/guard.sh\"", "timeout": 30 }
        ]
      }
    ]
  }
}

matcher je regulární výraz, který se porovnává s názvem nástroje; příkaz hooku dostane JSON na stdin a běží v sandboxu. Platforma podporuje jen těchto pět událostí: SessionStart, Stop, PreToolUse, PostToolUse, PreCompact.

MCP servery (.mcp.json)

Pokud chcete zpřístupnit externí nástroje přes Model Context Protocol, dodejte .mcp.json (nebo .claude-plugin/.mcp.json) s mapou mcpServers:

{
  "mcpServers": {
    "my-server": {
      "command": "${PLUGIN_DIR}/bin/my-mcp-server",
      "args": ["--stdio"]
    }
  }
}

Podporované jsou transporty stdio (proces spuštěný v sandboxu), SSE i streamované HTTP; nástroje serveru se automaticky objeví v sadě nástrojů AI. Server, který se nepodaří spustit, chat nerozbije; jen se u něj zobrazí upozornění „nedostupné“.

Komponenty: vestavěné webové dashboardy

Komponenta je webová aplikace zobrazená přímo v rozhraní produktu. V manifestu uveďte "components": "./components", každé komponentě dejte vlastní components/<name>/component.json a přibalte sestavený front-end (index.html, assets/, locales/), volitelně i podpůrný skript:

{
  "id": "katastr",
  "title": "Katastr - Sledovaná řízení",
  "icon": "assets/icon.png",
  "route": "katastr",
  "description": "Track the status of cadastral proceedings.",
  "entrypoint": "index.html",
  "binary": "katastr.py",
  "i18n": {
    "cs": { "displayName": "Katastr - sledovaná řízení", "description": "..." },
    "en": { "displayName": "Cadastre - Tracked Proceedings", "description": "..." },
    "sk": { "displayName": "Kataster - sledované konania", "description": "..." }
  }
}

Automatizace: naplánované úlohy

Automatizace je Markdown soubor ve složce automations/, který obsahuje jen frontmatter:

---
uuid: b7c2f1a0-4e3d-4a6b-9c8e-2f5a1d0b6e74
type: COMMAND
title: Sync Codexis 1.0
description: Import your chats, agents and files from Codexis 1.0.
command: cdxctl codexis sync
cron: 0 3 * * *
enabled: true
---

command se spouští podle plánu v poli cron (zde každý den ve 3:00).

Reference: dokumentace dovednosti načítaná podle potřeby

Další Markdown soubory ve složce skills/<name>/references/. SKILL.md udržujte krátký a na referenční soubor v něm jen odkažte; AI si ho načte, až ho bude potřebovat (např. „Celý postup najdeš v references/czech-law-change-assessment.md“).

Kontrolní seznam

• Máte vlastní git repozitář se souborem .claude-plugin/marketplace.json a složkou plugins/.
• Doplněk je ve složce plugins/<name>/; <name> je malými písmeny, slova oddělená pomlčkou.
• plugin.json obsahuje name, version a description; name se shoduje s názvem složky i se záznamem v marketplace.json.
• Doplněk má v marketplace.json záznam s nově vygenerovaným uuid.
• Každá dovednost má vlastní SKILL.md: jedinečný uuid, name a description plný klíčových slov.
• Pokud dodáváte nástroj: linuxová binárka bin/<tool> je commitnutá, hooky jsou zapojené v plugin.json a binárka se instaluje do ~/.local/bin.
• Konfigurace je v bloku env jako proměnné CODEXIS_PLUGIN_*; tokeny a klíče se čtou z CODEXIS_USER_* a nikdy nejsou napevno v kódu.
• i18n je vyplněné (minimálně en; cs a sk doporučujeme).
• Změny jsou commitnuté a pushnuté na veřejný git hosting; doplněk se instaluje přidáním URL repozitáře jako Git marketplace.