Grimoire

Ghid ELI20 pentru Plugin Creator

4 min read

Ghid ELI20 pentru Plugin Creator

Ce face

plugin-creator creează scheletul valid pentru un plugin Codex: folderul pluginului, manifestul obligatoriu .codex-plugin/plugin.json, structuri opționale și, la cerere, intrarea din marketplace care face pluginul vizibil și ordonabil în UI-ul Codex.

Numele pluginului este normalizat automat: litere mici, hyphen-case, maximum 64 de caractere. Spațiile, underscore-urile și punctuația devin -, iar cratimele consecutive se comprimă. De exemplu, My Plugin devine my-plugin, iar My--Plugin tot my-plugin. Folderul generat și valoarea "name" din plugin.json trebuie să rămână identice.

Ghidul ăsta stă în familia All guides și este pentru operatori care vor să știe ce produce capacitatea și ce limite are, nu pentru rescriere manuală de schema.

Când îmi folosește

Îl folosești când vrei un plugin Codex personal nou, când trebuie adăugată structură opțională într-un plugin local, sau când vrei o intrare de marketplace pentru disponibilitate, autentificare și ordine de randare.

Este util și când lucrezi iterativ la un plugin local existent: flow-ul corect este cu helper-ul de cachebuster și reinstall, nu editare manuală a marketplace-ului. Asta reduce riscul de manifesturi care arată plauzibil, dar sunt respinse la ingestie.

Nu este un editor autonom de marketplace-uri arbitrare. Dacă destinația marketplace-ului nu este cea implicită, ea trebuie cerută explicit și verificată ca instalată înainte de instrucțiuni de reinstall.

Cum îl invoc / declanșez

Comenzile se rulează din root-ul skill-ului, adică directorul care conține SKILL.md.

Pentru scaffold simplu:

python3 scripts/create_basic_plugin.py <plugin-name>

Implicit, pluginul se creează în directorul personal de pluginuri, ca <plugin-name> normalizat.

Pentru marketplace personal:

python3 scripts/create_basic_plugin.py my-plugin --with-marketplace

Marketplace-ul personal implicit este fișierul standard Codex pentru pluginuri locale. Pe Windows se folosește calea echivalentă din profilul utilizatorului.

Folosește --marketplace-name <name> doar când creezi un marketplace nou, iar numele implicit personal este deja luat sau instalat în altă parte:

python3 scripts/create_basic_plugin.py my-plugin \
  --with-marketplace \
  --marketplace-name team-local

Pentru repo sau team marketplace, doar dacă destinația a fost cerută explicit:

python3 scripts/create_basic_plugin.py my-plugin \
  --path <repo-root>/plugins \
  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
  --with-marketplace

Dacă este specificat un --marketplace-path non-default, marketplace-ul trebuie instalat cu codex plugin marketplace add <path-to-marketplace-root> înainte să fie tratat ca disponibil.

Exemplu practic

Vrei un plugin local numit My Plugin, cu foldere pentru skill-uri, hooks, scripts, assets, plus fișiere companion MCP și app, și vrei să apară în marketplace:

python3 scripts/create_basic_plugin.py "My Plugin" \
  --path <parent-plugin-directory> \
  --marketplace-path <marketplace-json-path> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<parent-plugin-directory> este directorul în care va fi creat folderul <plugin-name>, de exemplu un director local de pluginuri.

Înainte să fie predat pluginul generat, se rulează validarea:

python3 scripts/validate_plugin.py <plugin-path>

Pentru un plugin local existent, în dezvoltare:

python3 scripts/update_plugin_cachebuster.py <plugin-path>

Preferă cachebuster-ul default al helper-ului. Override explicit doar dacă utilizatorul îl cere.

Output / unde aterizează

Skill-ul creează root-ul pluginului la:

/<parent-plugin-directory>/<plugin-name>/

Manifestul obligatoriu este mereu aici:

/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json

Când --with-marketplace este setat, creează sau actualizează marketplace-ul țintă. Dacă fișierul nu există, se creează root-ul cu name, interface.displayName și plugins.

Intrarea generată are forma:

{
  "name": "plugin-name",
  "source": {
    "source": "local",
    "path": "./plugins/plugin-name"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

Dacă a fost creată sau actualizată o intrare de marketplace, răspunsul final trebuie să includă handoff-ul Codex app cu linkuri Markdown View <plugin-name> și Share <plugin-name>, folosind deeplink-uri codex://plugins/.... Nu se emit aceste linkuri dacă nu s-a creat sau actualizat marketplace-ul.

Limite / gotchas

Nu lăsa [TODO: ...] în manifest. Defaults pornesc valide și trebuie păstrate valide.

Nu scoate .codex-plugin/plugin.json; structura este obligatorie.

Nu pune apps sau mcpServers în plugin.json dacă fișierele companion nu au fost create efectiv.

Nu adăuga câmpuri respinse de validare, inclusiv hooks.

displayName aparține în interface la nivel de marketplace, nu în intrările individuale din plugins[].

Ordinea din plugins[] este ordinea de randare în Codex. Adaugă la final, dacă nu s-a cerut explicit reorder.

Scrie mereu policy.installation, policy.authentication și category, chiar când sunt defaults. policy.products se adaugă doar la cerere explicită.

Folosește --force doar când înlocuirea fișierelor sau a intrării de marketplace este intenționată.

Dacă scrierea marketplace-ului cere aprobare, cere aprobarea înainte. Dacă utilizatorul preferă să ruleze singur comanda, dă comanda exactă și continuă apoi cu validarea, nu cu presupuneri.

Graph View