06-插件开发全生命周期

插件开发全生命周期

学习目标

本章将掌握 Claude Code 插件从创建到发布的完整生命周期，通过 plugin-dev 插件的 8 阶段引导工作流，掌握：

• 8 阶段开发流程的每个步骤和 Gate
• 三个专用验证 Agent 的职责和输出
• 六个验证脚本的使用方法
• 本地测试工作流（cc --plugin-dir）

---

前置知识

• 插件系统架构与组件发现
• Skill 渐进式知识管理

---

项目实践

8 阶段开发流程

/plugin-dev:create-plugin Command 引导以下 8 个阶段：

阶段	目标	加载的 Skill
1. Discovery	明确插件目的、目标用户、核心功能	plugin-structure
2. Component Planning	确定需要的 Commands、Agents、Skills、Hooks、MCP	plugin-structure
3. Detailed Design	详细设计每个组件（不可跳过）	所有相关 Skills
4. Structure Creation	创建目录结构、plugin.json、README 模板	plugin-structure
5. Component Implementation	实现每个组件	按需加载 Skills
6. Validation	运行验证 Agent 和脚本	plugin-validator、skill-reviewer
7. Testing	本地 cc --plugin-dir 测试	—
8. Documentation	完善 README 和市场发布	—

三个验证 Agent

Agent	职责	验证维度
plugin-validator	全面验证插件结构	目录结构、plugin.json、Commands、Agents、Skills、Hooks、MCP、安全检查
skill-reviewer	审查 Skill 质量	描述质量、触发有效性、渐进式披露、skill-creator 最佳实践
agent-creator	生成 Agent 配置	将用户需求翻译为 Agent frontmatter 和系统提示

六个验证脚本

脚本	功能
validate-hook-schema.sh	验证 hooks.json 结构是否符合 schema
test-hook.sh	用样本输入测试 Hook 脚本
hook-linter.sh	检查 Hook 脚本最佳实践
validate-agent.sh	验证 Agent markdown 文件
parse-frontmatter.sh	提取 YAML frontmatter
validate-settings.sh	验证设置文件

本地测试工作流

开发完成后，使用 cc --plugin-dir <path> 加载未安装的插件进行测试：

cc --plugin-dir ./my-plugin

这会临时加载指定目录中的所有组件，不需要先安装到市场。

为什么 Detailed Design 不可跳过

8 阶段流程中，阶段 3（Detailed Design）被明确标记为不可跳过：

“CRITICAL: Do not skip this phase. Detailed design ensures each component is well-defined before implementation.”

原因：

• 设计先行的工程原则——没有清晰设计就开始编码，很容易导致边写边改
• 组件之间的依赖关系需要在设计阶段明确（如 Hook 依赖 Skill 的格式定义）
• 跳过设计会导致后续 Validation 阶段频繁返工

文档标准

plugin-dev 强制执行一致的文档标准：

维度	标准
描述	第三人称（“This skill should be used when…”）
触发短语	强且具体（列出用户可能的查询方式）
正文	命令式/不定式（“To do X, do Y”）
README	包含安装、使用、特性、最佳实践、贡献指南

陷阱与对策

陷阱	表现	对策
跳过 Detailed Design	组件定义不清晰，Validation 阶段频繁返工	强制执行阶段 3
验证 Agent 和脚本结果矛盾	Agent 认为通过，脚本认为不通过	以脚本的验证结果为准（确定性 > 模型判断）
本地测试与安装后行为不一致	--plugin-dir 加载的环境与实际安装环境不同	最终在安装后再次测试

设计取舍

为什么需要 3 个验证 Agent？

各自专注不同维度：plugin-validator 检查结构正确性，skill-reviewer 检查 Skill 的触发和描述质量，agent-creator 帮助生成 Agent 配置。合并为一个会导致注意力分散。

为什么 Validation 阶段使用 Agent 而非纯脚本？

脚本只能检查格式和结构（如 JSON schema 验证）。Agent 可以检查语义质量（如”这个 Skill 的触发短语是否足够具体？”、“这个 Agent 的系统提示是否清晰？”）。两者互补。

参考来源

• Claude Code Plugin Development 文档
• 源码: plugins/plugin-dev/commands/create-plugin.md
• 源码: plugins/plugin-dev/agents/*.md
• 源码: plugins/plugin-dev/skills/*/SKILL.md