用途：把可复用的工具能力打包成 Claude Code 插件，便于跨项目、跨团队共享或通过市场分发，也可用于版本化管理智能体能力、将 MCP 服务器与技能捆绑。不适用场景：单项目定制（改用 .claude/ 目录）、打包前的快速试验、无需分发的个人工作流。
主要能力：插件至少需要 .claude-plugin/plugin.json 清单，其余组件均可选并从插件根目录的常规目录自动发现。组件包括：技能 skills//SKILL.md（Markdown + YAML，按上下文自动发现）、命令 commands/.md（自动、带命名空间）、智能体 agents/*.md（自动，出现在 /agents 界面）、钩子 hooks/hooks.json（事件触发自动执行）、MCP 服务器 .mcp.json、LSP 服务器 .lsp.json，以及通过清单配置的输出样式。
使用方式：本地开发可用 --plugin-dir ./my-plugin 手动加载测试，用 claude plugin validate . 校验；安装作用域通过 --scope user|project|local 指定。配置和脚本中引用插件文件时使用 ${CLAUDE_PLUGIN_ROOT}，引用项目目录使用 ${CLAUDE_PROJECT_DIR}。插件技能调用形式为 /plugin-name:skill-name。
限制与常见错误：只有 plugin.json 放在 .claude-plugin/ 内，其他组件须位于插件根目录；避免使用绝对路径，防止用 ../ 路径穿越，所有文件应留在插件目录内；缺少清单、钩子脚本未执行 chmod +x、事件名大小写错误（应为 PostToolUse 而非 postToolUse）、误以为自定义路径可替换默认目录（实际是补充）都会出问题。若存在 meta-skill-creator 技能，可将插件内的技能编写委派给它；否则可用 npx skills add oakoss/agent-skills --skill meta-skill-creator 获取。