Vytvorenie doplnku

Táto príručka popisuje, ako vytvoriť doplnok (plugin) pre CODEXIS AI Agent a ako ho zverejniť, aby si ho mohol nainštalovať ktokoľvek. Dozviete sa, z čoho sa doplnok skladá, čo patrí do manifestov a čo vám platforma dáva k dispozícii: od hookov životného cyklu po premenné prostredia.

Najlepším zdrojom funkčných príkladov je oficiálny marketplace. Svoj doplnok tam pridávať nebudete (zverejníte vlastný, viď nižšie), ale ako predloha poslúži výborne: ares je najjednoduchší doplnok typu „zručnosť + jeden nástroj“, codexis je najkomplexnejší.

Doplnok je priečinok plugins/<name>/. Môže obsahovať v ľubovoľnej kombinácii zručnosti (Markdown s pokynmi, kedy a ako má AI niečo urobiť; jadro väčšiny doplnkov), nástroje príkazového riadka (malé predkompilované programy v bin/, ktoré AI spúšťa), hooky životného cyklu (príkazy spúšťané pri inštalácii, aktualizácii a odinštalovaní), komponenty (zabudované webové dashboardy) a automatizácie (naplánované úlohy). Úplne najmenší doplnok tvorí plugin.json a jediný SKILL.md; všetko ostatné je voliteľné.

Ako sa doplnky distribuujú: váš vlastný marketplace

Doplnky sa inštalujú vždy z marketplace, teda z git repozitára so zoznamom jedného alebo viacerých doplnkov. Doplnok nie je možné nainštalovať samostatne: aj jediný doplnok sa šíri ako marketplace s jedným záznamom.

Svoj doplnok nepridávate do oficiálneho marketplace. Zverejníte vlastný: git repozitár, ktorý obsahuje .claude-plugin/marketplace.json a priečinok plugins/.

your-marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json     # zoznam vašich doplnkov
└── plugins/
    └── your-plugin/         # samotný doplnok (všetko ostatné v tejto príručke)

Ktokoľvek si ho nainštaluje tak, že si v CODEXISe pridá váš repozitár ako marketplace: zvolí zdroj typu Git, vloží URL repozitára (voliteľne aj vetvu alebo tag) a nainštaluje ktorýkoľvek z ponúkaných doplnkov. Nepotrebuje na to administrátorské práva ani nič od nás; každý používateľ si CODEXIS nasmeruje na repozitáre, ktorým dôveruje.

Zvyšok príručky popisuje súbory vnútri plugins/<name>/ vo vašom repozitári.

Formát doplnku a podporované komponenty

Doplnky CODEXIS používajú štandardný formát doplnkov Claude Code: manifest .claude-plugin/plugin.json priamo v priečinku doplnku a vedľa neho súbory komponentov v podpriečinkoch s ustálenými názvami. Držte sa týchto konvencií:

• Zručnosti a agentov definujte v Markdowne s YAML frontmatterom (hooky a MCP v JSON).
• Doplnok aj každú komponentu pomenujte malými písmenami, slová oddeľte pomlčkou, bez medzier.
• Pri zručnostiach a agentoch je description písaný pre model: práve podľa neho sa AI rozhoduje, kedy zručnosť alebo agenta použiť. Buďte konkrétni a nešetrite spúšťacími slovami a frázami.
• SKILL.md udržujte krátky. Podrobnosti presuňte do referenčných súborov, ktoré si AI načíta, až ich bude potrebovať.
• Na vlastné súbory sa z hookov odkazujte cez ${PLUGIN_DIR} (obdoba ${CLAUDE_PLUGIN_ROOT} z Claude Code).

Platforma však nenačítava všetky typy komponentov, ktoré Claude Code pozná. Čo CODEXIS AI Agent skutočne číta:

Nad rámec štandardného formátu platforma pridáva hooky životného cyklu (postInstall / postUninstall / onUpdate), vlastný blok env doplnku, dodávané premenné CODEXIS_USER_* / CODEXIS_PUBLIC_*, trojjazyčné metadáta i18n, zabudované dashboardy popísané súborom component.json a naplánované automatizácie. Všetko popisujeme nižšie.

Väčšina doplnkov si vystačí len so zručnosťami (a nástrojom príkazového riadka v bin/). Agentov, event hooky a MCP servery pridajte, až ich budete potrebovať.

Kde a ako doplnok beží

Keď si používateľ váš doplnok nainštaluje, priečinok doplnku sa skopíruje do jeho súkromného linuxového sandboxu a tam sa spustí inštalačný hook. V rovnakom sandboxe potom beží aj každý príkaz, ktorý AI cez váš doplnok vykoná. Na čo sa môžete spoľahnúť:

• Je to Linux. Binárky musia byť linuxové, zostavené pre architektúru sandboxu (amd64 alebo arm64).
• Priečinok ~/.local/bin je prvý v PATH a môžete doň zapisovať. Stačí doň nástroj nakopírovať a AI ho môže volať menom, bez celej cesty a bez sudo.
• Hooky bežia v plnohodnotnom shelle: pracovný adresár je nastavený na priečinok doplnku, platí limit 5 minút a premenná $PLUGIN_DIR na tento priečinok ukazuje.
• K dispozícii sú premenné prostredia CODEXIS_* (viď nižšie).
• Odchádzajúca sieť môže byť obmedzená. Administrátor môže sandbox obmedziť len na schválené ciele; nástroj, ktorý volá externé API, potom môže potrebovať doménu v zozname povolených (allow-list). Nepočítajte s voľným prístupom k internetu.
• Domovský adresár je zdieľané úložisko (pripojené cez NFS). Synchronizujú sa doň vybrané priečinky z počítača používateľa alebo z firemného súborového servera a vaše nástroje ich čítajú ako bežné cesty pod $HOME.

Keď hook zlyhá: neúspešný postInstall preruší inštaláciu; neúspešný postUninstall alebo onUpdate sa len zapíše do logu a operáciu nezastaví. Prázdny hook neurobí nič.

Rýchly štart: doplnok len so zručnosťou

Najmenší užitočný doplnok naučí AI pracovný postup a neobsahuje žiadny program. Stačia tri súbory:

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.

Potom už doplnok len zaregistrujte vo svojom .claude-plugin/marketplace.json (viď nižšie). Tým máte hotový doplnok pripravený na inštaláciu.

Štruktúra priečinka doplnku

Povinný je iba .claude-plugin/plugin.json, všetko ostatné je voliteľné. Takto vyzerá codexis, najkomplexnejší doplnok:

plugins/<name>/
├── .claude-plugin/
│   └── plugin.json          # POVINNÉ: manifest
├── icon.svg                 # ikona v marketplace
├── README.md                # popis pre ľudí
├── skills/                  # jeden priečinok na zručnosť
│   └── <skill>/
│       ├── SKILL.md
│       ├── icon.svg         # voliteľné
│       └── references/      # voliteľné dokumenty načítané podľa potreby
├── agents/                  # voliteľní subagenti (jeden .md na agenta)
├── bin/                     # predkompilované nástroje (commitnuté)
├── hooks/                   # inštalačné / odinštalačné skripty (+ voliteľný hooks.json)
├── .mcp.json                # voliteľné definície MCP serverov
├── lib/                     # zdieľaný knižničný kód pre vaše nástroje/komponenty
├── components/              # zabudované webové dashboardy (pokročilé)
└── automations/             # naplánované úlohy

Na reálnych príkladoch sú vidieť tri úrovne zložitosti: len zručnosti (visualization) vystačí s plugin.json + skills/; zručnosť + jeden nástroj (ares) pridáva bin/, hooks/ a hooky životného cyklu; všetko (codexis) pridáva ešte components/, automations/ a lib/.

Dva manifesty

.claude-plugin/marketplace.json (v hlavnom priečinku vášho marketplace repozitára)

Manifest vášho vlastného marketplace. Každý doplnok uveďte v poli plugins. Manifest je benevolentný: keď name alebo uuid vynecháte, odvodí sa automaticky, a doplnky sa navyše samy nájdu v priečinku plugins/. Napriek tomu odporúčame každý doplnok uviesť výslovne, vrátane 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 sa musí zhodovať s name v plugin.json a s priečinkom uvedeným v source.
• source je vždy ./plugins/<name>.
• category zaradí doplnok do kategórie. Existujúce kategórie: legal, visualization, document-processing, media, open-data.
• tagLabels prekladá kľúče tagov z poľa tags v plugin.json.

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

Popisuje váš doplnok. Povinné sú polia name, version a description; ostatné pridajte podľa potreby:

{
  "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\""
}

Ako napísať SKILL.md

Zručnosť je Markdown súbor: frontmatter (blok medzi riadkami ---) a za ním inštrukcie písané pre 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
...

Najdôležitejšie pole je description. Používateľom sa nezobrazuje; AI sa podľa neho rozhoduje, kedy zručnosť načítať. Píšte ho ako pokyn plný spúšťacích slov a fráz, nie ako hmlisté zhrnutie.

Telo zručnosti je samotný návod: aký nástroj zavolať, s akou presnou syntaxou, ako čítať výstup a čo ukázať používateľovi. Buďte konkrétni: uveďte ukážkové príkazy a rozhodovací strom.

SKILL.md udržujte stručný. Dlhšie podrobnosti presuňte do skills/<name>/references/*.md a v zručnosti na ne len odkážte; AI si ich načíta, až ich bude skutočne potrebovať.

Dodanie nástroja: bin/ a hooky životného cyklu

Pokiaľ má váš doplnok spúšťať nástroj príkazového riadka, dodajte ho ako predkompilovanú binárku a hookom životného cyklu ho nainštalujte do PATH sandboxu.

Binárka

Do plugins/<name>/bin/<tool> commitnite samostatný (staticky linkovaný) linuxový spustiteľný súbor. Použiť môžete akýkoľvek jazyk, ktorý sa skompiluje do statickej linuxovej binárky; jestvujúce doplnky používajú Rust. Nástroj načíta vstup a výsledky vypíše na stdout, ideálne ako JSON.

Inštalácia do PATH

Inštalačný hook má jediný účel: skopírovať binárku do ~/.local/bin, ktorá už je v PATH. Pri jedinej binárke nepotrebujete ani skript; príkazy zapíšte priamo do plugin.json (presne tak to robí doplnok ocr). ${PLUGIN_DIR} sa rozvinie na cestu k priečinku nainštalovaného doplnku:

  "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ý mechanizmus. Platformu zaujíma jediné: váš nástroj musí skončiť v PATH.

Tri hooky životného cyklu

onUpdate obvykle len zopakuje postInstall. Na súbory doplnku odkazujte cez ${PLUGIN_DIR}; je to obdoba ${CLAUDE_PLUGIN_ROOT} z Claude Code.

Premenné prostredia

Vaše hooky aj každý príkaz, ktorý AI spustí, vidia tri skupiny premenných.

CODEXIS_PLUGIN_* (deklarujete ich vy)

Vlastná konfigurácia doplnku (URL, ID). Deklarujete ju v bloku env v plugin.json:

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

Názov začnite prefixom CODEXIS_PLUGIN_ a zvyšok voľte jedinečne pre svoj doplnok, aby nikdy nekolidoval s premennou iného doplnku. Citlivé údaje sem nepatria; hodnoty sú uložené priamo v manifeste. Konfiguráciu deklarujte v env; nevytvárajte súbory .env ani nepoužívajte export vnútri hookov.

CODEXIS_USER_* (dodávané citlivé údaje, len na čítanie)

Tokeny a kľúče konkrétneho používateľa; dodáva ich platforma. Iba ich čítajte: nikdy ich nelogujte ani ich nevkladajte natvrdo do binárky.

CODEXIS_PUBLIC_* (dodávaný kontext, len na čítanie)

Údaje o prostredí, v ktorom príkaz práve beží.

Hooky inštalácie, odinštalovania a aktualizácie bežia mimo chatu, takže dostanú URL platformy, domovský adresár aj premenné CODEXIS_USER_*, ale nie SESSION_ID / TOOL_CALL_ID.

Preklady (i18n)

Rozhranie je dostupné v češtine (cs), angličtine (en) a slovenčine (sk). Blok i18n má každý manifest aj každá zručnosť.

• Technické identifikátory (name, id, kľúče tagov) sa nikdy neprekladajú.
• description zručnosti sa nikdy neprekladá; je to spúšťač pre AI, nie text pre rozhranie.
• Prekladajú sa len zobrazované texty: displayName, description v manifeste, summary zručnosti 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, nie description):

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

Keď preklad chýba, použije sa náhrada v poradí požadovaný jazyk → en → nepreložený name/description. Vyplňte minimálne en; cs a sk však dôrazne odporúčame.

Voliteľné: subagenti, event hooky, MCP, komponenty, automatizácie

Subagenti (agents/<name>.md)

Subagent je špecializovaný asistent, ktorému AI môže odovzdať časť práce. Dodajte ho ako Markdown súbor v priečinku agents/, s frontmatterom a telom, ktoré slúži ako 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.

Rovnako ako pri zručnostiach je description spúšťačom pre model. name píšte malými písmenami, slová oddeľujte pomlčkou. Priečinok agents/ platforma nájde sama; v manifeste kvôli nej nič uvádzať nemusíte.

Event hooky (hooks/hooks.json)

Event hooky spúšťajú príkazy automaticky pri udalostiach v chate (na rozdiel od hookov životného cyklu vyššie, ktoré bežia pri inštalácii). Zapíšte ich do hooks/hooks.json:

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

matcher je regulárny výraz, ktorý sa porovnáva s názvom nástroja; príkaz hooku dostane JSON na stdin a beží v sandboxe. Platforma podporuje len týchto päť udalostí: SessionStart, Stop, PreToolUse, PostToolUse, PreCompact.

MCP servery (.mcp.json)

Pokiaľ chcete sprístupniť externé nástroje cez Model Context Protocol, dodajte .mcp.json (alebo .claude-plugin/.mcp.json) s mapou mcpServers:

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

Podporované sú transporty stdio (proces spustený v sandboxe), SSE aj streamované HTTP; nástroje servera sa automaticky objavia v sade nástrojov AI. Server, ktorý sa nepodarí spustiť, chat nerozbije; len sa pri ňom zobrazí upozornenie „nedostupné“.

Komponenty: zabudované webové dashboardy

Komponenta je webová aplikácia zobrazená priamo v rozhraní produktu. V manifeste uveďte "components": "./components", každej komponente dajte vlastný components/<name>/component.json a pribaľte zostavený front-end (index.html, assets/, locales/), voliteľne aj podporný 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": "..." }
  }
}

Automatizácie: naplánované úlohy

Automatizácia je Markdown súbor v priečinku automations/, ktorý obsahuje len 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 sa spúšťa podľa plánu v poli cron (tu každý deň o 3:00).

Reference: dokumentácia zručnosti načítaná podľa potreby

Ďalšie Markdown súbory v priečinku skills/<name>/references/. SKILL.md udržujte krátky a na referenčný súbor v ňom len odkážte; AI si ho načíta, až ho bude potrebovať (napr. „Celý postup nájdeš v references/czech-law-change-assessment.md“).

Kontrolný zoznam

• Máte vlastný git repozitár so súborom .claude-plugin/marketplace.json a priečinkom plugins/.
• Doplnok je v priečinku plugins/<name>/; <name> je malými písmenami, slová oddelené pomlčkou.
• plugin.json obsahuje name, version a description; name sa zhoduje s názvom priečinka aj so záznamom v marketplace.json.
• Doplnok má v marketplace.json záznam s novo vygenerovaným uuid.
• Každá zručnosť má vlastný SKILL.md: jedinečný uuid, name a description plný kľúčových slov.
• Pokiaľ dodávate nástroj: linuxová binárka bin/<tool> je commitnutá, hooky sú zapojené v plugin.json a binárka sa inštaluje do ~/.local/bin.
• Konfigurácia je v bloku env ako premenné CODEXIS_PLUGIN_*; tokeny a kľúče sa čítajú z CODEXIS_USER_* a nikdy nie sú natvrdo v kóde.
• i18n je vyplnené (minimálne en; cs a sk odporúčame).
• Zmeny sú commitnuté a pushnuté na verejný git hosting; doplnok sa inštaluje pridaním URL repozitára ako Git marketplace.