Hunter B
877b44935e
Document the portable SKILL.md compatibility boundary for Claude Code plugin bundles and keep /skill install from silently flattening plugin archives that carry multiple skills plus plugin.json runtime metadata. Reported by @AiurArtanis in #2743. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1.5 KiB
1.5 KiB
Claude Plugin Compatibility
CodeWhale treats Claude Code skill folders as instruction bundles when they are
plain SKILL.md directories. It does not run Claude Code plugin runtimes.
Supported
- Workspace or global
.claude/skills/<name>/SKILL.mddirectories discovered by the normal skill registry. - GitHub or tarball installs that contain one selected skill directory such as
skills/<name>/SKILL.md,.agents/skills/<name>/SKILL.md,.claude/skills/<name>/SKILL.md, or a nested package layout ending inskills/<name>/SKILL.md. - Companion files inside the selected skill directory, such as
references/,examples/, or scripts that are only used after the skill is explicitly loaded and trusted.
Not Supported As A Plugin Runtime
Claude Code plugin features remain outside the v0.8.60 compatibility boundary:
.claude-plugin/plugin.jsonmetadata and activation semantics.- Custom slash-command bundles.
- Plugin build steps, compiled TypeScript agents, dashboard servers, shared plugin state, or token-gated service processes.
- Frontmatter fields that require Claude-specific runtime behavior, such as
model: inherit.
If a Claude Code plugin repository contains multiple skills, install or migrate
one skills/<name> directory at a time. /skill install rejects multi-skill
plugin archives with a clear message so it never silently chooses one skill and
drops the plugin runtime behavior.
For richer integrations, wrap the plugin's executable surface as MCP, hooks, or a CodeWhale skill that names the external command explicitly.