创建或整理 Claude Code 插件时如何组织目录结构…

在开发 Claude Code 插件、搭建插件脚手架或排查组件无法加载时，按标准目录布局与清单配置组织 commands/agents/skills/hooks/MCP。

适用场景

解决思路

1. 按标准目录布局组织插件：根目录下放 .claude-plugin/plugin.json 清单，组件目录 commands/、agents/、skills/、hooks/、scripts/ 以及 .mcp.json 都放在插件根级，不要嵌套进 .claude-plugin/。
2. 确保 plugin.json 位于 .claude-plugin/ 目录，且只创建插件实际使用的组件目录。
3. 所有目录和文件名使用 kebab-case 命名。
4. 在 plugin.json 中至少填写 name 字段，使用 kebab-case、全局唯一、不含空格或特殊字符。
5. 补充推荐元数据：version（语义化 MAJOR.MINOR.PATCH）、description、author（name/email/url）、homepage、repository、license、keywords。
6. 如需自定义组件路径，在 plugin.json 中用 commands、agents、hooks、mcpServers 字段指定；路径必须相对插件根、以 ./ 开头、不能用绝对路径，agents 等字段支持数组；自定义路径是补充而非替换默认目录。
7. Commands：在 commands/ 放带 YAML frontmatter（name、description）的 .md 文件，会自动被发现并注册为斜杠命令。
8. Agents：在 agents/ 放带 YAML frontmatter（description、capabilities）的 .md 文件，自动加载，可手动调用或由 Claude Code 按任务上下文自动选择。
9. Skills：在 skills/ 下为每个技能建独立子目录，内含 SKILL.md（frontmatter 含 name、description、version），可在子目录放 scripts/、references/、examples/ 等支持文件，Claude Code 会按 description 匹配任务自动激活。
10. Hooks：在 hooks/hooks.json 或 plugin.json 内联配置事件处理器，事件包括 PreToolUse、PostToolUse、Stop、SubagentStop、SessionStart、SessionEnd、UserPromptSubmit、PreCompact、Notification；例如用 matcher 匹配 Write|Edit 并执行 bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh，可设 timeout。
11. MCP Servers：在插件根的 .mcp.json 或 plugin.json 内联定义 mcpServers，指定 command、args、env，插件启用时自动启动。
12. 所有插件内部路径引用统一使用 ${CLAUDE_PLUGIN_ROOT} 环境变量（hook 命令、MCP 参数、脚本执行、资源文件），禁止硬编码绝对路径、相对工作目录路径或 ~ 快捷方式。
13. 在清单 JSON 字段、组件文件（commands/agents/skills）和被执行脚本中分别以 ${CLAUDE_PLUGIN_ROOT}/... 形式引用路径，脚本内可直接作为环境变量使用。
14. 遵循文件命名约定：命令与 agent 用 kebab-case .md；skill 用 kebab-case 目录名；脚本用描述性 kebab-case 加扩展名；文档用 kebab-case .md；配置用 hooks.json、.mcp.json、plugin.json 等标准名。
15. 依赖自动发现机制：启用插件时读取 .claude-plugin/plugin.json，扫描 commands/ 与 agents/ 的 .md、skills/ 下含 SKILL.md 的子目录、hooks/hooks.json 或清单、.mcp.json 或清单；安装时注册、启用时可用，下次会话生效无需重启。
16. 组织上按逻辑分组相关组件，保持 plugin.json 精简（仅在必要时写自定义路径，简单场景用内联配置），并为插件根、组件目录、脚本目录编写 README 文档。
17. 命名保持一致（如命令 test-runner 对应 agent test-runner-agent），使用能表明用途的描述性名称，避免 utils/、misc.md、temp.sh 之类；命令 2-3 个词，agent 清晰描述角色，skill 聚焦主题。
18. 保证可移植性：始终用 ${CLAUDE_PLUGIN_ROOT}，在 macOS/Linux/Windows 上测试，记录依赖工具及版本，避免系统特定特性，使用可移植的 bash/Python 写法。
19. 维护时保持版本一致（发布时更新 plugin.json 的 version），优雅弃用旧组件，记录破坏性变更，变更后彻底测试所有组件。
20. 排查组件不加载：检查文件目录与扩展名、YAML frontmatter 语法、skill 是否名为 SKILL.md、插件是否已启用。
21. 排查路径错误：替换所有硬编码路径为 ${CLAUDE_PLUGIN_ROOT}，确认清单路径以 ./ 开头且文件存在，可在 hook 脚本中用 echo $CLAUDE_PLUGIN_ROOT 测试。
22. 排查自动发现失效：确认目录在插件根而非 .claude-plugin/ 内、命名符合约定、清单自定义路径正确，必要时重启 Claude Code。
23. 避免插件冲突：使用唯一且描述性的组件名，必要时用插件名做命名空间或命令前缀，并在 README 中记录潜在冲突。

适用边界 · 注意事项

• 不使用 Claude Code 插件体系、或不需要打包 commands/agents/skills/hooks/MCP 的场景。
• 仅编写单个独立 skill 文件、不涉及插件清单与目录布局时，无需套用完整插件结构。