Plugin Dev 插件开发工具包

Plugin Dev 是 Claude Code 官方提供的完整插件开发工具包，包含 3 个专业 Agent、7 个专业 Skill，以及 8 阶段结构化插件创建工作流，帮助开发者快速构建高质量的 Claude Code 插件。

概述

Plugin Dev 插件是 Claude Code 插件生态的核心基础设施。它提供了从零开始创建插件所需的全部工具和指导，包括：

结构化工作流：8 阶段渐进式插件创建流程
专业 Agent：3 个专门用于插件开发的智能代理
知识库 Skills：7 个涵盖插件各方面知识的技能模块
自动验证：插件结构和配置的自动化检查

核心特性

特性	说明	组件
创建工作流	8 阶段结构化插件创建	`/plugin-dev:create-plugin` 命令
Agent 创建	智能代理设计与优化	`agent-creator` Agent
结构验证	插件配置和目录检查	`plugin-validator` Agent
Skill 评审	Skill 质量评估与改进	`skill-reviewer` Agent
知识指导	7 个专业领域的详细指南	7 个 Skills

安装与配置

插件安装

bash

# 安装 plugin-dev 插件
/plugin install plugin-dev@claude-plugins-official

目录结构

安装后的插件结构如下：

plugins/plugin-dev/
├── .claude-plugin/
│   └── plugin.json              # 插件元数据
├── README.md                    # 插件说明
├── commands/
│   └── create-plugin.md         # 主创建命令
├── agents/
│   ├── agent-creator.md         # Agent 创建器
│   ├── plugin-validator.md      # 插件验证器
│   └── skill-reviewer.md        # Skill 评审器
└── skills/
    ├── plugin-structure/        # 插件结构指南
    │   └── SKILL.md
    ├── agent-development/       # Agent 开发指南
    │   └── SKILL.md
    ├── hook-development/        # Hook 开发指南
    │   └── SKILL.md
    ├── mcp-integration/         # MCP 集成指南
    │   └── SKILL.md
    ├── command-development/     # 命令开发指南
    │   └── SKILL.md
    ├── skill-development/       # Skill 开发指南
    │   └── SKILL.md
    └── plugin-settings/         # 插件设置指南
        └── SKILL.md

配置文件 (plugin.json)

json

{
  "name": "plugin-dev",
  "version": "1.0.0",
  "description": "Comprehensive plugin development toolkit with specialized agents for plugin creation, validation, and skill review",
  "author": {
    "name": "Anthropic",
    "email": "support@anthropic.com"
  }
}

8 阶段创建工作流

工作流概览

mermaid

graph LR
    A[Phase 1<br/>Discovery] --> B[Phase 2<br/>Component<br/>Planning]
    B --> C[Phase 3<br/>Design &<br/>Questions]
    C --> D[Phase 4<br/>Structure<br/>Creation]
    D --> E[Phase 5<br/>Implementation]
    E --> F[Phase 6<br/>Validation]
    F --> G[Phase 7<br/>Testing]
    G --> H[Phase 8<br/>Documentation]

    style A fill:#e3f2fd
    style B fill:#e8f5e9
    style C fill:#fff3e0
    style D fill:#f3e5f5
    style E fill:#e0f7fa
    style F fill:#fce4ec
    style G fill:#f1f8e9
    style H fill:#e8eaf6

详细阶段说明

Phase 1: Discovery（发现阶段）

目标：理解用户的插件需求

行动：

创建 todo list 跟踪所有阶段
询问用户关于插件的核心问题：
- 插件要解决什么问题？
- 目标用户是谁？
- 需要哪些核心功能？
加载 plugin-structure skill 了解插件架构

输出：明确的插件目标和功能范围

Phase 2: Component Planning（组件规划）

目标：确定插件需要的组件类型

行动：

基于需求决定需要哪些组件：
- Commands（斜杠命令）
- Agents（智能代理）
- Skills（知识技能）
- Hooks（钩子）
- MCP Servers（MCP 服务器）
加载相关开发 skills

输出：组件清单和初步设计

Phase 3: Design & Questions（设计与澄清）

目标：详细设计每个组件并解决疑问

行动：

为每个组件设计详细规格
识别技术决策点
向用户澄清设计选择

输出：详细的组件设计文档

Phase 4: Structure Creation（结构创建）

目标：创建插件目录和配置文件

行动：

创建 .claude-plugin/ 目录
生成 plugin.json 配置
创建所有必需的子目录

输出：完整的插件目录结构

Phase 5: Implementation（实现阶段）

目标：实现所有组件

行动：

逐个实现 commands
编写 agents 的 system prompts
创建 skills 的 SKILL.md
实现 hooks 脚本
配置 MCP 服务器（如需要）

输出：完整的组件实现

Phase 6: Validation（验证阶段）

目标：确保插件结构和配置正确

行动：

启动 plugin-validator agent
检查 plugin.json 完整性
验证目录结构
检查命名约定

输出：验证报告和修复建议

Phase 7: Testing（测试阶段）

目标：测试插件功能

行动：

测试每个命令的执行
验证 agents 的触发条件
检查 skills 的加载
测试 hooks 的执行

输出：测试报告

Phase 8: Documentation（文档阶段）

目标：编写用户文档

行动：

编写 README.md
添加使用示例
记录配置选项
提供故障排除指南

输出：完整的用户文档

核心命令

/plugin-dev:create-plugin

启动完整的插件创建工作流。

语法：

bash

/plugin-dev:create-plugin [插件描述]

示例：

bash

# 创建一个代码格式化插件
/plugin-dev:create-plugin "一个自动格式化代码的插件，支持 Python 和 JavaScript"

# 创建一个 Git 工作流插件
/plugin-dev:create-plugin "简化 Git 操作的插件，包含自动提交和 PR 创建"

# 创建一个代码审查插件
/plugin-dev:create-plugin "使用多个专业 Agent 进行代码审查的插件"

工作流程：

mermaid

sequenceDiagram
    participant U as 用户
    participant C as Claude
    participant S as Skills
    participant A as Agents

    U->>C: /plugin-dev:create-plugin
    C->>C: 创建 Todo List
    C->>S: 加载 plugin-structure skill
    C->>U: 询问插件需求
    U->>C: 提供需求描述

    loop 每个阶段
        C->>S: 加载相关 skills
        C->>C: 执行阶段任务
        C->>U: 确认或澄清
    end

    C->>A: 启动 plugin-validator
    A->>C: 返回验证结果
    C->>U: 完成报告

三大专业 Agent

1. Agent Creator（Agent 创建器）

用途：帮助设计和创建新的 autonomous agents

模型：Sonnet（优化速度和质量平衡）

触发条件：当用户需要为插件创建新的 Agent 时

核心能力：

能力	说明
意图提取	分析用户需求，提炼核心目的
角色设计	设计专家角色和行为模式
Prompt 编写	编写全面的 system prompt
触发优化	设计准确的触发条件
性能调优	优化决策框架和响应模式

输出格式：

markdown

---
name: agent-name
description: 描述触发条件和能力
model: sonnet  # 或 inherit/opus/haiku
color: blue    # 可选：blue/green/yellow/red
---

You are [角色描述]...

## 核心职责
1. ...
2. ...

## 工作流程
1. ...
2. ...

## 输出格式
...

2. Plugin Validator（插件验证器）

用途：验证插件结构和配置的正确性

模型：inherit（继承父级模型）

触发条件：插件开发完成后或需要检查配置时

验证清单：

mermaid

graph TD
    A[Plugin Validator] --> B[plugin.json 验证]
    A --> C[目录结构验证]
    A --> D[组件文件验证]
    A --> E[命名约定检查]
    A --> F[最佳实践审查]

    B --> B1[必需字段存在]
    B --> B2[版本格式正确]
    B --> B3[作者信息完整]

    C --> C1[.claude-plugin/ 存在]
    C --> C2[正确的子目录]
    C --> C3[文件位置正确]

    D --> D1[YAML frontmatter]
    D --> D2[必需字段]
    D --> D3[格式正确]

    style A fill:#e3f2fd

验证报告示例：

✅ Plugin Validation Report
==========================

📁 Structure Check
  ✅ .claude-plugin/plugin.json exists
  ✅ commands/ directory found
  ✅ agents/ directory found
  ⚠️  skills/ directory empty

📄 plugin.json Check
  ✅ name: "my-plugin"
  ✅ version: "1.0.0"
  ✅ description present
  ❌ author.email missing

📝 Component Check
  ✅ commands/main.md - valid YAML frontmatter
  ✅ agents/helper.md - valid structure

🔧 Recommendations
  1. Add author.email to plugin.json
  2. Consider adding skills for better documentation

3. Skill Reviewer（Skill 评审器）

用途：评审 Skill 的质量和有效性

模型：inherit

触发条件：当需要评估或改进 Skill 时

评审维度：

维度	检查内容	评分标准
触发效果	description 字段是否准确触发	1-10 分
渐进披露	3 级加载是否合理	1-10 分
内容质量	信息是否准确完整	1-10 分
组织结构	层次是否清晰	1-10 分

改进建议示例：

markdown

## Skill Review Report: my-skill

### Overall Score: 7.5/10

### Strengths
- Clear and concise description
- Good use of examples
- Well-organized structure

### Areas for Improvement

1. **Description Trigger (6/10)**
   - Current: "Helps with code formatting"
   - Suggested: "Use this skill when formatting Python or JavaScript code,
     including indentation, line length, and import ordering"

2. **Progressive Disclosure (8/10)**
   - Core content is appropriate length
   - Consider moving advanced examples to references/

3. **Content Quality (8/10)**
   - Missing error handling section
   - Add more edge case examples

七大专业 Skills

1. plugin-structure（插件结构）

版本：v0.1.0

内容：

插件目录布局标准
plugin.json 配置详解
组件路径自定义方式
自动发现机制

关键知识点：

插件最小结构：
plugins/my-plugin/
└── .claude-plugin/
    └── plugin.json  # 唯一必需文件

plugin.json 最小配置：
{
  "name": "my-plugin"
}

2. agent-development（Agent 开发）

版本：v0.1.0

内容：

Agent 文件结构
YAML frontmatter 配置
System prompt 设计原则
模型和颜色自定义

关键知识点：

markdown

---
name: my-agent
description: Use when [触发条件]. Examples: ...
model: sonnet  # sonnet/opus/haiku/inherit
color: blue    # 可选
---

You are [角色]...

3. hook-development（Hook 开发）

版本：v0.1.0

内容：

Prompt-based hooks vs Command hooks
hooks.json 配置格式
9 种 hook 事件类型
${CLAUDE_PLUGIN_ROOT} 可移植性

支持的 Hook 事件：

事件	触发时机	常见用途
`PreToolUse`	工具执行前	安全检查、参数验证
`PostToolUse`	工具执行后	结果处理、日志记录
`Stop`	Claude 停止前	循环控制、清理操作
`SessionStart`	会话开始时	环境设置、指令注入
`UserPromptSubmit`	用户提交提示时	输入验证、预处理
`Notification`	通知发送时	自定义通知
`SubagentStop`	子代理停止时	结果处理

4. mcp-integration（MCP 集成）

版本：v0.1.0

内容：

MCP 服务器集成方法
.mcp.json vs plugin.json 配置对比
stdio、SSE 等服务器类型
OAuth 和复杂认证

5. command-development（命令开发）

版本：v0.2.0

内容：

Slash command 结构
YAML frontmatter 配置
动态参数处理
文件引用机制

关键知识点：

markdown

---
description: 命令简短描述
allowed-tools: Bash(git:*), Read
---

这里是给 Claude 的指令，不是给用户的说明。
命令内容会被注入到 Claude 的上下文中。

6. skill-development（Skill 开发）

版本：v0.1.0

内容：

Skill 概念和结构
渐进披露设计（3 级加载）
SKILL.md 编写规范
scripts/、references/、assets/ 组织

渐进披露模型：

mermaid

graph TD
    A[Level 1: Metadata] --> B[Level 2: Core Content]
    B --> C[Level 3: References]

    A -->|始终加载| A1[name + description<br/>约 50 词]
    B -->|Skill 触发时| B1[SKILL.md<br/>1000-3000 词]
    C -->|按需加载| C1[scripts/<br/>references/<br/>assets/]

    style A fill:#e3f2fd
    style B fill:#e8f5e9
    style C fill:#fff3e0

7. plugin-settings（插件设置）

版本：v0.1.0

内容：

.claude/plugin-name.local.md 模式
YAML frontmatter + markdown body 结构
从 hooks/commands/agents 读取设置
状态文件管理

实战示例

示例 1：创建简单的代码格式化插件

bash

/plugin-dev:create-plugin "一个代码格式化插件，支持 Python 和 JavaScript"

生成的插件结构：

plugins/code-formatter/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── format.md
└── README.md

示例 2：创建带 Agent 的代码审查插件

bash

/plugin-dev:create-plugin "代码审查插件，包含安全审查和性能审查两个专业 Agent"

生成的插件结构：

plugins/code-reviewer/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── review.md
├── agents/
│   ├── security-reviewer.md
│   └── performance-reviewer.md
└── README.md

示例 3：创建完整的开发工作流插件

bash

/plugin-dev:create-plugin "完整的功能开发工作流插件，包含探索、设计、实现、审查四个阶段，使用 Skills 提供知识支持"

生成的插件结构：

plugins/feature-workflow/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── develop.md
├── agents/
│   ├── explorer.md
│   ├── architect.md
│   └── reviewer.md
├── skills/
│   ├── exploration/
│   │   └── SKILL.md
│   ├── architecture/
│   │   └── SKILL.md
│   └── review/
│       └── SKILL.md
└── README.md

最佳实践

插件设计原则

原则	说明	示例
单一职责	每个插件解决一类问题	代码格式化 vs 代码审查分开
渐进披露	信息按需加载	核心指令在 SKILL.md，详细参考在 references/
工具限制	明确允许的工具	`allowed-tools: Bash(git:*)`
用户确认	关键操作前询问	在架构设计后等待用户批准

命名约定

插件名：kebab-case (例如: code-formatter)
命令名：kebab-case (例如: format-code)
Agent 名：kebab-case (例如: code-reviewer)
Skill 目录：kebab-case (例如: code-patterns/)

常见错误避免

错误	正确做法
Commands 写成用户文档	Commands 是给 Claude 的指令
在 plugin.json 中硬编码路径	使用 `${CLAUDE_PLUGIN_ROOT}`
Agent 触发条件太模糊	提供具体的 Examples
Skill 内容太长	控制在 1000-3000 词

常见问题

Q: 如何选择使用 Agent 还是 Skill？

Agent：需要自主执行任务、有明确的触发条件、需要特定模型
Skill：提供知识和指导、被其他组件引用、按需加载

Q: 插件可以依赖其他插件吗？

A: 目前不支持插件间依赖。每个插件应该是自包含的。

Q: 如何调试插件？

检查 plugin.json 格式是否正确
运行 plugin-validator agent
测试每个命令的独立执行
查看 Claude 的输出日志

Q: Skill 的 description 应该多长？

A: 建议 1-3 句话，约 50 词以内。需要足够具体以触发正确的场景。

总结

Plugin Dev 是构建 Claude Code 插件的完整工具包：

8 阶段工作流 - 从发现到文档的完整流程
3 个专业 Agent - 创建、验证、评审
7 个知识 Skill - 涵盖插件开发各方面
最佳实践 - 命名、结构、设计原则

通过 Plugin Dev，您可以快速构建符合 Claude Code 标准的高质量插件。

参考资源

GitHub 源码 - 官方插件仓库
Claude Code 插件文档 - 官方文档
插件开发指南 - 详细开发教程

本文档基于 plugin-dev 插件 v1.0.0 编写

Plugin Dev 插件开发工具包 ​

概述 ​

核心特性 ​

安装与配置 ​

插件安装 ​

目录结构 ​

配置文件 (plugin.json) ​

8 阶段创建工作流 ​

工作流概览 ​

详细阶段说明 ​

Phase 1: Discovery（发现阶段） ​

Phase 2: Component Planning（组件规划） ​

Phase 3: Design & Questions（设计与澄清） ​

Phase 4: Structure Creation（结构创建） ​

Phase 5: Implementation（实现阶段） ​

Phase 6: Validation（验证阶段） ​

Phase 7: Testing（测试阶段） ​

Phase 8: Documentation（文档阶段） ​

核心命令 ​

/plugin-dev:create-plugin ​

三大专业 Agent ​

1. Agent Creator（Agent 创建器） ​

2. Plugin Validator（插件验证器） ​

3. Skill Reviewer（Skill 评审器） ​

七大专业 Skills ​

1. plugin-structure（插件结构） ​

2. agent-development（Agent 开发） ​

3. hook-development（Hook 开发） ​

4. mcp-integration（MCP 集成） ​

5. command-development（命令开发） ​

6. skill-development（Skill 开发） ​

7. plugin-settings（插件设置） ​

实战示例 ​

示例 1：创建简单的代码格式化插件 ​

示例 2：创建带 Agent 的代码审查插件 ​

示例 3：创建完整的开发工作流插件 ​

最佳实践 ​

插件设计原则 ​

命名约定 ​

常见错误避免 ​

常见问题 ​

Q: 如何选择使用 Agent 还是 Skill？ ​

Q: 插件可以依赖其他插件吗？ ​

Q: 如何调试插件？ ​

Q: Skill 的 description 应该多长？ ​

总结 ​

参考资源 ​

Plugin Dev 插件开发工具包

概述

核心特性

安装与配置

插件安装

目录结构

配置文件 (plugin.json)

8 阶段创建工作流

工作流概览

详细阶段说明

Phase 1: Discovery（发现阶段）

Phase 2: Component Planning（组件规划）

Phase 3: Design & Questions（设计与澄清）

Phase 4: Structure Creation（结构创建）

Phase 5: Implementation（实现阶段）

Phase 6: Validation（验证阶段）

Phase 7: Testing（测试阶段）

Phase 8: Documentation（文档阶段）

核心命令

/plugin-dev:create-plugin

三大专业 Agent

1. Agent Creator（Agent 创建器）

2. Plugin Validator（插件验证器）

3. Skill Reviewer（Skill 评审器）

七大专业 Skills

1. plugin-structure（插件结构）

2. agent-development（Agent 开发）

3. hook-development（Hook 开发）

4. mcp-integration（MCP 集成）

5. command-development（命令开发）

6. skill-development（Skill 开发）

7. plugin-settings（插件设置）

实战示例

示例 1：创建简单的代码格式化插件

示例 2：创建带 Agent 的代码审查插件

示例 3：创建完整的开发工作流插件

最佳实践

插件设计原则

命名约定

常见错误避免

常见问题

Q: 如何选择使用 Agent 还是 Skill？

Q: 插件可以依赖其他插件吗？

Q: 如何调试插件？

Q: Skill 的 description 应该多长？

总结

参考资源