企业官网建设流程全解析

Claude Code 插件开发全流程指南：使用 plugin-dev 的 create-plugin 工作流从零构建高质量插件

【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code

导读

本文基于开源仓库中 plugin-dev 插件的create-plugin命令，系统讲解在 Claude Code 中从需求分析到发布落地的端到端插件开发方法论。该命令将插件开发拆解为发现、组件规划、详细设计、结构创建、组件实现、验证、测试、文档化八个阶段，并自动加载 plugin-structure、hook-development、agent-development 等专项技能、调用 agent-creator / plugin-validator / skill-reviewer 三个专用 Agent 辅助开发。读完本文，你将掌握一套可复制的、经过质量校验的插件开发工作流：既能通过/plugin-dev:create-plugin引导式命令完成全流程，也能理解每个阶段背后的目录规范、清单格式与验证工具原理。

create-plugin 命令概览

/plugin-dev:create-plugin是 plugin-dev 工具包提供的端到端引导式工作流命令，其功能定义与用法记录在 plugins/plugin-dev/README.md 中。命令的元数据位于 create-plugin.md 的 frontmatter：

--- description: Guided end-to-end plugin creation workflow with component design, implementation, and validation argument-hint: Optional plugin description allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash", "TodoWrite", "AskUserQuestion", "Skill", "Task"] ---

可以看到该命令显式声明了可用的工具集合：Read/Write负责读写插件文件，Grep/Glob用于检索与定位组件，Bash用于创建目录和运行校验脚本，TodoWrite用于全程进度追踪，AskUserQuestion用于关键决策点的澄清提问，Skill用于按阶段加载开发技能，Task用于启动专用 Agent。这一"最小必要权限"的声明方式本身就是插件命令最佳实践的样板。

使用方式

/plugin-dev:create-plugin [可选插件描述] # 示例： /plugin-dev:create-plugin /plugin-dev:create-plugin A plugin for managing database migrations

传入的可选描述会作为$ARGUMENTS注入命令正文（命令内写作**Initial request:** $ARGUMENTS），若描述已足够明确，工作流可直接跳过部分澄清提问。

八个阶段的完整脉络

工作流强调五条核心原则：先问澄清问题再动手、按需用 Skill 工具加载开发技能、善用三个专用 Agent 辅助 AI 开发、遵循 plugin-dev 自身沉淀的模式、用 TodoWrite 全程跟踪进度。

Phase 1：需求发现（Discovery）

目标：明确要构建什么插件、解决什么问题。

此阶段的核心动作是：

1. 用 TodoWrite 建立包含全部 8 个阶段的待办列表；
2. 若$ARGUMENTS已明确插件用途，则总结理解并识别插件类型（集成类、工作流类、分析类、工具集等）；
3. 若用途不清晰，则向用户追问三个基本问题：
   • 这个插件解决什么问题？
   • 谁会使用它、何时使用？
   • 它应该做什么？是否有可参考的同类插件？
4. 在继续之前向用户复述理解并请求确认。

产出：清晰的插件用途声明与目标用户画像。

该阶段的设计与 plugin-dev 仓库中 agent-creator 的"提取核心意图"方法论一致——在 agents/agent-creator.md 中，Agent 创建器第一步就是"识别插件的根本目的、关键职责与成功标准，同时兼顾显式需求与隐式需求"。发现阶段的确认动作对应工作流文档中列出的五个关键决策点之首："Phase 1 之后确认插件用途"。

Phase 2：组件规划（Component Planning）

目标：确定插件需要哪些组件类型与数量。

进入本阶段前必须使用 Skill 工具加载 plugin-structure 技能（工作流文档明确标注"MUST load"）。加载后，根据需求逐一判断六类组件的取舍：

规划完成后，以表格形式向用户呈现组件方案并请求确认，例如：

| Component Type | Count | Purpose | |----------------|-------|---------| | Skills | 2 | Hook patterns, MCP usage | | Commands | 3 | Deploy, configure, validate | | Agents | 1 | Autonomous validation | | Hooks | 0 | Not needed | | MCP | 1 | Database integration |

组件类型的底层含义（plugin-structure 技能依据）

为什么是这六类组件？plugin-structure/SKILL.md 给出了 Claude Code 插件的标准目录约定：commands/存放斜杠命令（Markdown 文件）、agents/存放子代理定义（Markdown 文件）、skills/按子目录存放技能（每个技能必须有SKILL.md）、hooks/hooks.json配置事件处理器、.mcp.json定义 MCP 服务器、scripts/存放辅助脚本。所有组件目录必须位于插件根目录（不能嵌套在.claude-plugin/内），全部采用 kebab-case 命名，Claude Code 通过约定式目录自动发现组件——这正是规划阶段判断"需要哪些目录"的依据。

产出：经用户确认的组件清单。

Phase 3：详细设计与澄清提问（Detailed Design & Clarifying Questions）

目标：逐一细化每个组件的规格并消除全部歧义。工作流文档特别警告：这是最重要的阶段之一，切勿跳过（CRITICAL: DO NOT SKIP）。

针对每种组件需要澄清的未定义点：

• Skills：什么查询触发它？提供什么知识？内容粒度如何？
• Commands：接受什么参数？需要哪些工具？交互式还是自动化？
• Agents：何时触发（主动/响应式）？需要什么工具？输出格式？
• Hooks：监听哪些事件？基于提示词还是命令？校验标准是什么？
• MCP：哪种服务器类型？如何认证？暴露哪些工具？
• Settings：包含哪些字段？必填还是可选？默认值？

所有问题按组件类型分节呈现给用户，并且必须等待用户回答后才能进入实现阶段。若用户说"你看着办"，则应给出具体建议并取得显式确认，不能擅自决定。

文档给出了示例问题（以 skill 与 agent 为例）：

• 技能：哪些用户查询应触发此技能？是否包含实用脚本？核心 SKILL.md 与 references/ 的详细程度如何分配？是否包含真实示例？
• 代理：应在某些动作后主动触发，还是仅在显式请求时触发？需要哪些工具？输出格式如何？需要强制哪些质量标准？

产出：每个组件的详细规格说明书。此阶段对应工作流的关键决策点 3："Phase 3 之后才进入实现"。

Phase 4：创建插件结构与清单（Plugin Structure Creation）

目标：搭建插件目录骨架并生成 plugin.json 清单。

具体动作：

1. 确定插件名：kebab-case、描述性命名；
2. 选择创建位置：询问用户"在哪里创建插件？"，提供当前目录、../new-plugin-name、自定义路径三个选项；
3. 用 Bash 创建目录：

mkdir -p plugin-name/.claude-plugin mkdir -p plugin-name/skills # 按需 mkdir -p plugin-name/commands # 按需 mkdir -p plugin-name/agents # 按需 mkdir -p plugin-name/hooks # 按需

4. 用 Write 工具创建 plugin.json 清单：

{ "name": "plugin-name", "version": "0.1.0", "description": "[brief description]", "author": { "name": "[author from user or default]", "email": "[email or default]" } }

5. 创建 README.md 模板；
6. 按需创建.gitignore（用于忽略.claude/*.local.md等文件）；
7. 若创建的是新目录，初始化 git 仓库。

清单字段的完整约束（plugin-structure 技能补充）

plugin-structure/SKILL.md 进一步给出了清单字段的完整规范：

• 必填字段：仅name一项，要求 kebab-case、全插件唯一、不含空格与特殊字符；
• 推荐元数据：version（遵循语义化版本 MAJOR.MINOR.PATCH）、description、author（name/email/url）、homepage、repository、license、keywords；
• 组件路径配置：可通过commands、agents（支持数组多路径）、hooks、mcpServers字段指定自定义路径。注意自定义路径是补充而非替换默认目录，两者会同时加载；路径必须相对插件根目录、以./开头、不能使用绝对路径。

仓库中的最小插件示例见 plugin-structure/examples/minimal-plugin.md：一个hello-world插件仅含.claude-plugin/plugin.json（只有name字段）与commands/hello.md一个命令文件，Claude 会自动发现命令并注册为/hello。

产出：可容纳各组件的插件目录骨架。

Phase 5：组件实现（Component Implementation）

目标：按最佳实践逐一实现各组件。实现每种组件前都应加载对应开发技能：

• Skills → skill-development
• Commands → command-development
• Agents → agent-development
• Hooks → hook-development
• MCP → mcp-integration
• Settings → plugin-settings

5.1 技能（Skills）实现要点

加载 skill-development 技能后，为每个技能：

• 向用户索取具体使用示例（或使用 Phase 3 的产出）；
• 规划资源目录（scripts/、references/、examples/）；
• 创建技能目录结构；
• 编写SKILL.md，要求：
  • 第三人称描述+ 具体触发短语；
  • 精简正文（1,500–2,000 词），采用祈使语气；
  • 引用支撑文件；
• 创建 references 文件承载详细内容、examples 文件提供可运行代码、按需创建工具脚本；
• 用 skill-reviewer Agent 校验每个技能。

这与 skill-development/SKILL.md 倡导的渐进式披露原则一致：元数据（始终加载）→ 核心 SKILL.md（触发时加载）→ references/examples（按需加载），从而在保持 Claude Code 上下文精简的同时提供深度知识。plugin-dev 自身 7 个技能约 11,000 词的 SKILL.md 与 10,000+ 词参考文档就是这一模式的落地实例。

5.2 命令（Commands）实现要点

加载 command-development 技能后，为每个命令：

• 编写带 frontmatter 的命令 Markdown；
• 包含清晰的description与argument-hint；
• 声明allowed-tools（保持最小必要）；
• 指令写给 Claude 而非用户（这是 command-development/SKILL.md 反复强调的关键点：命令是"对 Claude 的指令"，而不是"给用户的说明"）；
• 提供使用示例与提示；
• 按需引用相关技能。

frontmatter 支持的核心字段包括：description（/help中显示的简述）、allowed-tools（字符串或数组，如Read, Write, Edit, Bash(git:*)）、model（sonnet/opus/haiku）、argument-hint（自动补全提示）、disable-model-invocation（禁止 SlashCommand 工具程序化调用）。命令正文支持$ARGUMENTS全量参数、$1/$2位置参数、@文件路径文件引用、!`bash`内联 Bash 执行（用于动态收集 git 状态等上下文），以及${CLAUDE_PLUGIN_ROOT}可移植路径引用。

5.3 代理（Agents）实现要点

加载 agent-development 技能后，为每个 Agent 调用 agent-creator Agent：

• 向 agent-creator 描述代理职责；
• 由它生成：identifier（标识符）、带示例的whenToUse（触发条件）、systemPrompt（系统提示词）；
• 创建带 frontmatter 与系统提示词的 Agent Markdown 文件；
• 配置合适的 model、color 与 tools；
• 用validate-agent.sh脚本校验。

agents/agent-creator.md 展示了这套 AI 辅助生成方法的内部原理：agent-creator 会依次执行"提取核心意图 → 设计专家人设 → 架构系统提示词 → 优化性能 → 创建标识符 → 编写触发示例"六步。其中标识符要求仅用小写字母、数字、连字符，3–50 字符；描述必须以 "Use this agent when..." 开头并附 2–4 个<example>块（每个示例含 Context、user、assistant、<commentary>四要素）；模型默认inherit，颜色按用途选择（blue/cyan 分析审查、yellow 校验告警、red 安全关键、magenta 创造生成），工具遵循最小权限原则。仓库中 agent-creator.md 自身就是这一产物的实例：model: sonnet、color: magenta、tools: ["Write", "Read"]。

Agent 文件 frontmatter 完整字段（依据 agent-development/SKILL.md）：

5.4 钩子（Hooks）实现要点

加载 hook-development 技能后，为每个钩子：

• 创建hooks/hooks.json配置文件；
• 复杂逻辑优先使用基于提示词的钩子（prompt-based hooks）——hook-development/SKILL.md 明确指出这是推荐方式，它用 LLM 自然语言推理做上下文感知判断，比 bash 脚本更灵活、易维护，支持 Stop、SubagentStop、UserPromptSubmit、PreToolUse 事件；
• 使用${CLAUDE_PLUGIN_ROOT}保证可移植性；
• 按需创建钩子脚本（放在examples/而非scripts/）；
• 用validate-hook-schema.sh与test-hook.sh工具测试。

插件专用 hooks.json 使用包装格式（依据 hook-development/SKILL.md）：

{ "description": "Brief explanation of hooks (optional)", "hooks": { "PreToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh", "timeout": 30 }] }], "Stop": [...] } }

可用事件包括：PreToolUse、PostToolUse、Stop、SubagentStop、SessionStart、SessionEnd、UserPromptSubmit、PreCompact、Notification（依据 plugin-structure/SKILL.md）。

5.5 MCP 与 Settings 实现要点

MCP：创建.mcp.json配置，指定服务器类型（本地用 stdio，托管用 SSE）、命令与参数（配合${CLAUDE_PLUGIN_ROOT}）、LSP 场景下的extensionToLanguage映射、按需的环境变量；在 README 中记录必需的环境变量并提供安装说明。参考 mcp-integration/examples/ 下的 stdio/SSE/HTTP 三个示例配置。

Settings：在 README 中提供配置模板；创建示例.claude/plugin-name.local.md文件作为文档；在 hooks/commands 中实现配置读取；在.gitignore中加入.claude/*.local.md。相关解析技巧与真实案例见 plugin-settings/references/。

进度跟踪：每完成一个组件即更新 TodoWrite 待办。

产出：全部插件组件实现完毕。

Phase 6：校验与质量检查（Validation & Quality Check）

目标：确保插件达到质量标准且工作正确。

1. 运行 plugin-validator Agent 做全面校验：检查清单、结构、命名、组件与安全性，并审阅校验报告；
2. 修复关键问题：处理校验中的 critical 错误与代表真实问题的警告；
3. skill-reviewer 复审（若含技能）：逐技能检查描述质量、渐进式披露、写作风格；
4. 测试 Agent 触发（若含代理）：确认<example>块清晰、触发条件具体，对 Agent 文件运行validate-agent.sh；
5. 测试钩子配置（若含钩子）：对hooks/hooks.json运行validate-hook-schema.sh，用test-hook.sh测试钩子脚本，验证${CLAUDE_PLUGIN_ROOT}用法；
6. 呈现结论：校验结果摘要、遗留问题、整体质量评估；
7. 询问用户："Validation complete. Issues found: [count critical], [count warnings]. Would you like me to fix them now, or proceed to testing?"

plugin-validator 的校验维度（源码依据）

agents/plugin-validator.md 给出了完整的十步校验流程，可作为理解该阶段能力的窗口：

1. 定位插件根目录：检查.claude-plugin/plugin.json；
2. 校验清单：JSON 语法（可用jq）、必填name字段、kebab-case 命名、version语义化格式、description非空、author结构、未知字段警告不失败；
3. 校验目录结构：检查 commands/、agents/、skills/、hooks/hooks.json 等标准位置；
4. 校验命令：frontmatter 存在、description必填、argument-hint格式、allowed-tools为数组、无命名冲突；
5. 校验代理：调用 validate-agent.sh 或手工检查 name/description/model/color/示例块/系统提示词；
6. 校验技能：skills/*/SKILL.md存在、frontmatter 含 name 与 description、references/examples/scripts 子目录与引用文件存在；
7. 校验钩子：validate-hook-schema.sh 或手工检查事件名合法、matcher 与 hooks 数组、type 为 command/prompt、命令引用存在脚本且使用${CLAUDE_PLUGIN_ROOT}；
8. 校验 MCP：stdio 有command、sse/http/ws 有url、类型相关字段齐全；
9. 文件组织检查：README.md 完整、无 node_modules/.DS_Store 等多余文件、按需.gitignore、含 LICENSE；
10. 安全检查：无硬编码凭据、MCP 用 HTTPS/WSS 而非 HTTP/WS、hooks 无明显安全问题、示例文件无机密。

校验报告按严重程度（critical/major/minor）分类，区分错误与警告，并为每个问题附文件路径、具体问题与修复建议。

产出：通过校验、可进入测试阶段的插件。

Phase 7：测试与验证（Testing & Verification）

目标：在真实的 Claude Code 环境中验证插件工作正常。

本地安装测试

cc --plugin-dir /path/to/plugin-name

或者将插件复制到项目的.claude-plugin/目录进行项目级测试。

验证清单

• 技能在触发时加载（用触发短语提问验证）
• 命令出现在/help中并能正确执行
• 代理在合适场景下被触发
• 钩子在事件发生时激活（如适用）
• MCP 服务器正常连接（如适用）
• Settings 配置文件生效（如适用）

分组件测试建议

• 技能：使用描述中的触发短语提问，观察是否自动加载；
• 命令：用各种参数运行/plugin-name:command-name；
• 代理：构造与代理示例匹配的场景；
• 钩子：用claude --debug查看钩子执行过程；
• MCP：用/mcp验证服务器与工具。

测试结束后询问用户："I've prepared the plugin for testing. Would you like me to guide you through testing each component, or do you want to test it yourself?"，若需要引导则逐个组件走查测试用例。

产出：测试并验证可用的插件。

Phase 8：文档与后续步骤（Documentation & Next Steps）

目标：完善文档并做好分发准备。

1. 核对 README 完整性：须包含概述、功能、安装、前置条件、用法；MCP 插件记录必需环境变量；钩子插件说明钩子激活方式；Settings 提供配置模板；
2. 添加 marketplace 条目（若发布）：指导添加到 marketplace.json、协助起草市场描述、建议分类与标签；
3. 创建总结：标记全部待办完成，列出创建内容——插件名与用途、创建的组件（X skills, Y commands, Z agents 等）、关键文件及其用途、文件总数与结构；后续步骤包括测试建议、市场发布（可选）、基于使用反馈迭代；
4. 提出改进建议（可选）：可增强插件的额外组件、集成机会、测试策略。

产出：完整、有文档、可发布使用的插件。

贯穿全程的最佳实践与决策节点

全程最佳实践（依据 create-plugin.md 与 plugin-dev 各技能）

• 用 TodoWrite 在每个阶段跟踪进度；
• 用 Skill 工具按需加载开发技能；
• 善用三个专用 Agent：agent-creator（生成代理）、plugin-validator（全面校验）、skill-reviewer（技能评审），分别见 agents/agent-creator.md、agents/plugin-validator.md、agents/skill-reviewer.md；
• 在关键决策点征询用户确认；
• 以 plugin-dev 自身实现为参照样板；
• 安全优先：钩子输入校验、MCP 使用 HTTPS、凭据走环境变量、最小权限原则；
• 可移植性：全程使用${CLAUDE_PLUGIN_ROOT}、只用相对路径、支持环境变量替换；
• 测试与文档：部署前校验配置、用示例输入测试钩子、善用claude --debug调试模式、编写清晰 README。

五个关键决策点（必须等待用户）

1. Phase 1 之后：确认插件用途
2. Phase 2 之后：批准组件规划
3. Phase 3 之后：进入实现
4. Phase 6 之后：修复问题或继续
5. Phase 7 之后：进入文档阶段

按阶段加载技能对照

• Phase 2：plugin-structure
• Phase 5：skill-development、command-development、agent-development、hook-development、mcp-integration、plugin-settings（按需）
• Phase 6：由 Agent 自动使用技能

质量验收标准

每个组件必须满足：✅ 遵循 plugin-dev 验证过的模式；✅ 命名规范正确；✅ 技能/代理具备强触发条件；✅ 包含可运行示例；✅ 文档完善；✅ 通过工具校验（如 validate-agent.sh 会检查 frontmatter 结构、必填字段、示例块、系统提示词长度等）；✅ 在 Claude Code 中实测通过。

端到端示例：数据库迁移插件

以"创建用于管理数据库迁移的插件"为例串联全流程：

• Phase 1 发现：理解为迁移管理与数据库 schema 版本化，确认用户要创建、运行、回滚迁移；
• Phase 2 规划：Skills 1（迁移最佳实践）、Commands 3（create-migration、run-migrations、rollback）、Agents 1（migration-validator）、MCP 1（数据库连接）；
• Phase 3 澄清：支持哪些数据库（PostgreSQL、MySQL 等）？迁移文件格式（SQL 还是基于代码）？Agent 是否在应用前校验？需要哪些 MCP 工具（query、execute、schema）？
• Phase 4-8：按结构创建、组件实现、校验、测试、文档化的顺序推进，直至产出完整插件。

总结

/plugin-dev:create-plugin工作流的价值在于把插件开发从"凭经验摸索"转化为"八阶段可验证的工程流程"：需求发现与组件规划保证方向正确，详细设计阶段强制消除歧义，结构与清单创建奠定自动发现基础，组件实现阶段按技能分类加载最佳实践，校验与测试阶段用专用 Agent 和脚本（plugin-validator、validate-agent.sh、validate-hook-schema.sh、test-hook.sh）兜底质量，最终以文档化收尾为发布铺路。这套工作流与 plugin-dev 仓库中 7 个专项技能、3 个辅助 Agent、6 个工具脚本共同构成了 Claude Code 插件开发的一站式方法论，无论你是要写一个单命令的 hello-world 插件（参考 minimal-plugin.md），还是集成 MCP、hooks 的完整企业级插件，都可以在此框架内获得结构化的开发指导。

【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code