| 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 | ## Compatible plugin bundles |
| 19 | |
| 20 | Since v0.9.13, `/plugin install` accepts the declarative subset described in |
| 21 | [Installing plugins](PLUGINS.md): nested `.claude-plugin/plugin.json` metadata, |
| 22 | root skills, commands and agent profiles, plus inline MCP declarations or |
| 23 | `.mcp.json`. Local sources in Claude marketplace catalogs resolve from the |
| 24 | repository root outside `.claude-plugin`. |
| 25 | |
| 26 | Exact `${ENV_NAME}` MCP header references map to Codewhale's environment-backed |
| 27 | credentials, including `Authorization: Bearer ${ENV_NAME}`. Literal credential |
| 28 | values and compound header templates are rejected; importing never reads the |
| 29 | referenced environment variables. |
| 30 | |
| 31 | The importer uses Codewhale's existing adapters, review hashes and enablement. |
| 32 | A Claude marketplace's labels or defaults grant no authority. Bundles are not |
| 33 | scanned from another application's plugin roots or activated automatically. |
| 34 | |
| 35 | ## Unsupported runtime features |
| 36 | |
| 37 | The importer rejects hooks, LSP declarations, custom MCP file paths, and |
| 38 | `${CLAUDE_PLUGIN_ROOT}` expansion. It does not run plugin build steps, |
| 39 | TypeScript agents, dashboard servers, shared plugin state, or token-gated |
| 40 | service processes. Claude-specific frontmatter behavior such as `model: inherit` |
| 41 | is not an additional runtime contract. Remote MCP authentication still follows |
| 42 | Codewhale's existing plugin credential boundary; installation does not complete |
| 43 | OAuth or borrow another application's credentials. |
| 44 | |
| 45 | `/skill install` remains a separate one-skill operation: it rejects multi-skill |
| 46 | plugin archives rather than silently selecting one directory and dropping other |
| 47 | components. Use `/plugin install` for supported bundles, or migrate one explicit |
| 48 | skill directory when the repository depends on unsupported runtime behavior. |
| 49 | |
| 50 | See [PLUGIN_BUNDLES.md](PLUGIN_BUNDLES.md) for discovery, review and activation. |
| 51 |