fix(skills): reject multi-skill Claude plugin archives

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>

docs/CLAUDE_PLUGIN_COMPAT.md

@@ -0,0 +1,35 @@
+# 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.md` directories 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 in
+  `skills/<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.json` metadata 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.

docs/CONFIGURATION.md

@@ -1006,7 +1006,9 @@ If you are upgrading from older releases:
   agentskills.io-compatible `~/.agents/skills` and the broader Claude-ecosystem
   `~/.claude/skills`. First launch installs versioned bundled skills for common
   workflows including skill creation, delegation, MCP/plugin scaffolding,
-  documents, presentations, spreadsheets, PDFs, and Feishu/Lark.
+  documents, presentations, spreadsheets, PDFs, and Feishu/Lark. See
+  [CLAUDE_PLUGIN_COMPAT.md](CLAUDE_PLUGIN_COMPAT.md) for the supported boundary
+  between portable `SKILL.md` bundles and Claude Code plugin runtimes.
 - `mcp_config_path` (string, optional): defaults to `~/.codewhale/mcp.json`, with
   legacy `~/.deepseek/mcp.json` fallback when the CodeWhale path is absent.
   It is visible in `/config` and can be changed from the TUI. The new path is

docs/GUIDE.md

@@ -404,8 +404,9 @@ work. Read the local guidance before editing, and keep any contribution within
 the repository's conventions.
 
 Next: see [SKILL_INVOCATION_DESIGN.md](SKILL_INVOCATION_DESIGN.md) for skill
-activation behavior and [CONFIGURATION.md](CONFIGURATION.md) for config paths
-and project authority.
+activation behavior, [CLAUDE_PLUGIN_COMPAT.md](CLAUDE_PLUGIN_COMPAT.md) for
+Claude Code skill/plugin compatibility, and [CONFIGURATION.md](CONFIGURATION.md)
+for config paths and project authority.
 
 ## 10. Getting Help