| 1 | # Claude Plugin Compatibility |
| 2 | |
| 3 | Codewhale treats Claude Code skill folders as instruction bundles when they are |
| 4 | plain `SKILL.md` directories. It does not run Claude Code plugin runtimes. |
| 5 | |
| 6 | ## Supported |
| 7 | |
| 8 | - Workspace or global `.claude/skills/<name>/SKILL.md` directories discovered by |
| 9 | the normal skill registry. |
| 10 | - GitHub or tarball installs that contain one selected skill directory such as |
| 11 | `skills/<name>/SKILL.md`, `.agents/skills/<name>/SKILL.md`, |
| 12 | `.claude/skills/<name>/SKILL.md`, or a nested package layout ending in |
| 13 | `skills/<name>/SKILL.md`. |
| 14 | - Companion files inside the selected skill directory, such as `references/`, |
| 15 | `examples/`, or scripts that are only used after the skill is explicitly |
| 16 | loaded and trusted. |
| 17 | |
| 18 | ## Not Supported As A Plugin Runtime |
| 19 | |
| 20 | Claude Code plugin features remain outside the compatibility boundary: |
| 21 | |
| 22 | - `.claude-plugin/plugin.json` metadata and activation semantics. |
| 23 | - Custom slash-command bundles. |
| 24 | - Plugin build steps, compiled TypeScript agents, dashboard servers, shared |
| 25 | plugin state, or token-gated service processes. |
| 26 | - Frontmatter fields that require Claude-specific runtime behavior, such as |
| 27 | `model: inherit`. |
| 28 | |
| 29 | If a Claude Code plugin repository contains multiple skills, install or migrate |
| 30 | one `skills/<name>` directory at a time. `/skill install` rejects multi-skill |
| 31 | plugin archives with a clear message so it never silently chooses one skill and |
| 32 | drops the plugin runtime behavior. |
| 33 | |
| 34 | For richer integrations, wrap the plugin's executable surface as MCP, hooks, or |
| 35 | a Codewhale skill that names the external command explicitly. |
| 36 | |
| 37 | Codewhale's own versioned plugin bundles are a different, explicitly trusted |
| 38 | format. v0.9.1 can activate namespaced Skills and MCP configuration from |
| 39 | `plugin.toml`, but it does not scan, convert, install, or trust Claude bundles |
| 40 | automatically. See [PLUGIN_BUNDLES.md](PLUGIN_BUNDLES.md). |
| 41 |