| 1 | --- |
| 2 | name: plugin-creator |
| 3 | description: Scaffold a local Codewhale plugin bundle with a versioned manifest, namespaced Skills, and an explicit trust review. |
| 4 | --- |
| 5 | |
| 6 | # Plugin Creator |
| 7 | |
| 8 | Use this skill when a user wants a local Codewhale plugin bundle. Trusted and |
| 9 | enabled bundles may add declarative Skills, commands, agents, hooks, and MCP |
| 10 | servers (stdio and remote) through the existing engines. LSP, filesystem |
| 11 | roots, and lifecycle mutation are inventory-only. Native extensions (host |
| 12 | code) are inventory-only unless the user has turned on the experimental |
| 13 | `[features] extension_host` flag. |
| 14 | |
| 15 | ## Workflow |
| 16 | |
| 17 | 1. Pick a Codewhale-owned location: |
| 18 | - User bundle: `~/.codewhale/plugins/<plugin-name>/` |
| 19 | - Workspace bundle: `<workspace>/.codewhale/plugins/<plugin-name>/` |
| 20 | 2. Normalize the bundle name to lowercase hyphen-case. |
| 21 | 3. Create `plugin.json` (Agent Plugins v1.0.0; a legacy `plugin.toml` stays |
| 22 | readable, but new bundles use `plugin.json`): |
| 23 | |
| 24 | ```json |
| 25 | { |
| 26 | "$schema": "https://agent-plugins.org/schemas/plugin.json", |
| 27 | "name": "my-plugin", |
| 28 | "version": "0.1.0", |
| 29 | "description": "What this bundle provides" |
| 30 | } |
| 31 | ``` |
| 32 | |
| 33 | 4. Put each Skill under `skills/<skill-name>/SKILL.md`; Codewhale finds |
| 34 | `skills/` automatically and exposes each as `my-plugin:<skill-name>`, |
| 35 | never as an unqualified command. |
| 36 | 5. Add MCP servers in a sibling `mcp.json` only when the bundle needs an |
| 37 | existing MCP engine. Keep stdio commands and paths inside the bundle. Map local |
| 38 | environment values only as exact `${SOURCE_ENV}` references. For remote MCP, |
| 39 | use HTTPS (or loopback HTTP), forbid URL user information/query/fragment, |
| 40 | use only environment-backed headers or bearer tokens, and declare the exact |
| 41 | normalized endpoint host set in `capabilities.network_hosts` under |
| 42 | `extensions["net.codewhale"]`. Never place credentials in the manifest. |
| 43 | 6. Commands (`commands/*.md`), agents (`agents/*.toml`), and hooks |
| 44 | (`hooks/*.toml`), declared under `extensions["net.codewhale"]`, activate |
| 45 | under the current policy — workspace bundles win same-name collisions over |
| 46 | user and built-in bundles. LSP, filesystem roots, and lifecycle mutation |
| 47 | are inventory-only: declare them only when inventorying future work. A |
| 48 | `native` entry runs only under the experimental extension host; there it |
| 49 | must be one `.mjs`, `.js` or `.mts` ES module file, `/plugin validate` rejects |
| 50 | anything else, and its tools always use `Required` approval, never a |
| 51 | plugin's read-only hint. Full Access, Bypass, or an exact session grant |
| 52 | for the reviewed build can satisfy that gate without a prompt. A bundle |
| 53 | that declares only unsupported surfaces cannot be enabled. |
| 54 | 7. Validate and review without executing bundle content: |
| 55 | - `/plugin validate <plugin-name>` |
| 56 | - `/plugin show <plugin-name>` |
| 57 | - stop and present these results; the person runs `/plugin enable <plugin-name>` |
| 58 | to open the content/capability review, reviews it, runs the exact |
| 59 | `/plugin trust ...` confirmation shown, then enables the bundle |
| 60 | 8. Verify `/skills inspect` reports plugin provenance and `/plugin list` |
| 61 | reports the expected trust and activation state. Trust stages the reviewed |
| 62 | content but does not activate it. After enablement, follow the host's |
| 63 | reload notice: use `/reload` or a new session to apply changes to a live |
| 64 | session's pinned skills and tools. |
| 65 | |
| 66 | Every user and workspace bundle starts untrusted and disabled. Reuse the |
| 67 | existing `/plugin marketplace`, install, update, review and reload surfaces; |
| 68 | do not add a parallel installer, registry or automatic trust flow. Catalog |
| 69 | membership alone never installs, trusts or enables a plugin. |
| 70 | |
| 71 | ## Experimental host code |
| 72 | |
| 73 | Only scaffold host code when the person explicitly uses the experimental |
| 74 | extension-host feature. Start from the tested `hello-extension` example and |
| 75 | `docs/EXTENSIONS.md` in the Codewhale repository. A typed `.mts` entry may use |
| 76 | Node's erasable TypeScript syntax; bundle dependencies locally. Register tools |
| 77 | with a plugin-specific prefix and an object input schema, propagate |
| 78 | `exec.signal`, and use `ctx.effect` for bounded asynchronous cleanup. The |
| 79 | current execution context exposes `signal`, `callId` and `args`; it does not |
| 80 | expose the calling workspace path. Do not change the shared process cwd. |
| 81 | |
| 82 | Stop after install, validate and show; never automate the trust token. A |
| 83 | person reviews, trusts and enables the bundle. `/plugin show <name>` reports |
| 84 | owner state, live tools and recent attributed diagnostics. Recovery may create |
| 85 | fresh registrations, but never replays an interrupted tool call. Explain the |
| 86 | shared-process and current platform sandbox limits without claiming isolation. |
| 87 |