plugin-creator

# Plugin Creator $ARGUMENTS Create a new experimental opt-in plugin pack following ai-toolkit conventions. ## Workflow 1. **Capture scope** -- what domain should the plugin pack own? 2. **Pick packaging model** -- domain pack, policy pack, or hook/observability pack? 3. **Define manifest** -- name, description, version, domain, compatibility, included assets 4. **Select assets** -- agents, skills, rules, hooks, docs, templates 5. **Add scaffolding** -- create `plugin.json`, `README.md`, and optional subdirectories 6. **Validate** -- manifest JSON, included asset references, executable hooks, documentation links ## Directory Layout ```text app/plugins/<plugin-name>/ ├── plugin.json ├── README.md ├── agents/ # optional ├── skills/ # optional ├── hooks/ # optional ├── rules/ # optional └── templates/ # optional ``` ## Manifest Template ```json { "name": "memory-pack", "description": "Domain plugin pack for persistent cross-session memory.", "version": "1.0.0", "domain": "memory", "type": "plugin-pack", "status": "experimental", "requires": { "ai-toolkit": ">=1.0.0", "claude-code": ">=1.0.33" }, "includes": { "agents": [], "skills": ["mem-search"], "rules": [], "hooks": ["observation-capture.sh", "session-summary.sh"] }, "hook_events": { "observation-capture.sh": "PostToolUse", "session-summary.sh": "Stop" } } ``` The two hooks are files the pack **owns**, under `app/plugins/memory-pack/hooks/`. That is what makes this a pack rather than a bookmark: installing it puts scripts on disk and entries in the host's hook config that were not there before. ## Authoring Rules - **MUST** keep packs domain-scoped — "memory-pack", "mobile-pack", not "misc-pack" - **MUST** install something the core install does not already provide. `ai-toolkit install` links every core skill and agent, so a pack whose `includes` names only core assets installs **zero files** and is a no-op. Verify before shipping: install core into a throwaway `HOME`, then install the pack, and confirm the file count changed. Nine packs were removed in v4.20.0 for failing exactly this check. - **MUST** reference existing toolkit assets rather than forking them — but referencing alone is not a pack. A pack earns its existence through hooks, scripts, or assets of its own; the reference list is context, not content. - **MUST** ship a valid `plugin.json` with `name`, `description`, `version`, `domain`, `type`, `status`, and `includes` - **NEVER** have a pack silently alter default global install behavior — experimental packs are **opt-in only** - **NEVER** copy an agent or skill file into a pack when referencing the toolkit-level version suffices; duplication creates drift - **CRITICAL**: optional hooks bundled in a pack must be executable (`chmod +x`) and documented in the pack README with their install semantics - **MANDATORY**: the pack README names supported runtimes (`claude`, `codex`, or `all`) and explains that the pack is not part of the default install ## Gotchas - Plugin packs are discovered by scanning `app/plugins/*/plugin.json`. A pack with a missing or malformed `plugin.json` is silently ignored — no error surfaces. Check with `ls app/plugins/*/plugin.json` and `jq . app/plugins/*/plugin.json`. - The `status: experimental` flag gates visibility in some install paths — marking a pack "stable" before it is audited can make it install by default for every user. Keep `experimental` until the pack has eaten its own dogfood. - Packs that include hooks inherit the toolkit's hook merge rules (`_source: "ai-toolkit"`). Hooks without the `_source` tag survive `ai-toolkit update` and can leak into other packs' merge pools. - Versions in `plugin.json` are separate from the toolkit version. A pack at v1.2 running inside toolkit v2.11 may still satisfy `requires.ai-toolkit: >=1.0.0` but mean nothing about actual compatibility — test against the current toolkit before tagging. - Codex-runtime packs need matching `.agents/rules/` and `.codex/hooks.json` variants; a plugin that only ships Claude assets looks broken under Codex CLI. Declare runtime support explicitly. ## Validation Checklist - [ ] `app/plugins/<plugin-name>/plugin.json` exists and parses as JSON - [ ] **The pack installs a non-zero number of files.** `ai-toolkit install` into a throwaway `HOME`, then `plugin install <name>`, and confirm the reported file count is above zero on every runtime the pack claims. A pack reporting `(0 file items)` does nothing and must not ship. - [ ] `README.md` explains purpose, included assets, and opt-in flow - [ ] Referenced agents and skills exist or are created in the same change set - [ ] Optional hooks are executable and use `#!/bin/bash` - [ ] `scripts/validate.py` passes - [ ] Public docs mention the pack only after the manifest and README exist ## When NOT to Use - For an individual **skill** (slash command or knowledge doc) — use `/skill-creator` - For an individual **agent** — use `/agent-creator` - For a single **hook** (not a pack) — use `/hook-creator` - For an MCP server — use `/mcp-builder` - For modifying an existing plugin pack — edit its files directly; this skill is create-only