构建插件技能
你是创建和管理Claude Code插件的专家。插件是将代理、技能、命令和钩子捆绑成有凝聚力的包。当用户想要创建、构建、验证或发布完整的插件,或需要插件架构和最佳实践的帮助时,会自动调用。也会在Claude即将创建插件目录结构、编写plugin.json清单或实现涉及将组件捆绑到插件包中的任务时主动调用。
插件是什么?
一个插件是将相关的Claude Code组件捆绑在一起的包:
- 代理:专门化的子代理,用于委托任务
- 技能:自动调用的专业知识模块
- 命令:用户触发的斜杠命令
- 钩子:事件驱动的自动化
插件使用户能够通过一个命令安装完整的功能。
创建插件与单独组件时
使用插件时:
- 你想一起分发多个相关组件
- 你正在构建一个有凝聚力的功能集或领域专业知识
- 你希望用户通过一个命令安装一切
- 你需要在组件之间保持版本兼容性
- 你正在为特定领域创建一个可重用的工具包
使用单独组件时:
- 你只需要一个代理、技能或命令
- 组件不相关,可以独立使用
- 你正在为特定项目定制
- 你不打算分发或共享
插件创建过程
创建插件涉及:
- 收集需求(名称、组件、元数据)
- 创建目录结构
- 编写plugin.json清单
- 创建每个组件(代理、技能、命令、钩子)
- 编写全面的README.md
- 验证完整的插件
组件创建:每种组件类型(代理、技能、命令、钩子)应遵循其各自的最佳实践。使用相应的building-*技能来获取创建每种类型的专业知识。
插件结构和模式
目录结构
plugin-name/
├── .claude-plugin/
│ └── plugin.json # 必需:插件清单
├── agents/ # 可选:代理定义
│ ├── agent1.md
│ └── agent2.md
├── skills/ # 可选:技能目录
│ ├── skill1/
│ │ ├── SKILL.md
│ │ ├── scripts/
│ │ ├── references/
│ │ └── assets/
│ └── skill2/
│ └── SKILL.md
├── commands/ # 可选:斜杠命令
│ ├── command1.md
│ └── command2.md
├── hooks/ # 可选:事件钩子
│ ├── hooks.json
│ └── scripts/
├── scripts/ # 可选:辅助脚本
│ └── setup.sh
├── .mcp.json # 可选:MCP服务器配置
└── README.md # 必需:文档
最小插件结构
一个有效插件的绝对最小要求:
my-plugin/
├── .claude-plugin/
│ └── plugin.json
└── README.md
plugin.json模式
必需字段
{
"name": "plugin-name",
"version": "1.0.0",
"description": "插件的作用"
}
推荐字段
{
"name": "plugin-name",
"version": "1.0.0",
"description": "插件功能的全面描述",
"author": {
"name": "你的名字",
"email": "your.email@example.com",
"url": "https://github.com/yourname"
},
"homepage": "https://github.com/yourname/plugin-name",
"repository": "https://github.com/yourname/plugin-name",
"license": "MIT",
"keywords": ["keyword1", "keyword2", "keyword3"]
}
组件注册
{
"commands": "./commands/",
"agents": ["./agents/agent1.md", "./agents/agent2.md"],
"skills": "./skills/",
"hooks": ["./hooks/hooks.json"]
}
注意:
⚠️ 严重格式警告
数组必须包含简单的路径字符串,而不是对象!
❌ 错误(将静默失败加载):
"commands": [ {"name": "init", "path": "./commands/init.md", "description": "..."}, {"name": "status", "path": "./commands/status.md"} ]✅ 正确:
"commands": [ "./commands/init.md", "./commands/status.md" ]这适用于所有组件数组:
agents,skills,commands和hooks。另外注意:单项数组仍然是数组,不是字符串:
- ❌
"agents": "./agents/my-agent.md"(字符串 - 不会加载)- ✅
"agents": ["./agents/my-agent.md"](数组 - 正确)
可选:MCP服务器
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-name"],
"env": {
"API_KEY": "${API_KEY}"
}
}
}
}
命名约定
插件名称:
- 仅限小写字母、数字和连字符(不使用下划线!)
- 最多64个字符
- 描述性和领域特定
- 示例:
code-review-suite,data-analytics-tools,git-workflow-automation
组件名称:
- 遵循各个组件的命名规则
- 代理:动作导向(
code-reviewer,test-generator) - 技能:首选动名词形式(
analyzing-data,reviewing-code) - 命令:动词优先(
new-feature,run-tests) - 一致性:在插件内使用类似的命名模式
语义化版本控制
插件必须遵循语义化版本控制:MAJOR.MINOR.PATCH
- MAJOR:重大更改(例如,移除组件、更改接口)
- MINOR:新功能(例如,新命令、增强功能)
- PATCH:错误修复和小幅改进
示例:
1.0.0→ 初始发布1.1.0→ 添加了新命令1.1.1→ 修复了现有命令的错误2.0.0→ 移除了弃用的代理(重大更改)
创建插件
按照这些步骤创建结构良好的插件:
第1步:收集需求
询问用户:
- 插件名称和目的:这个插件将做什么?
- 目标领域:它解决什么问题?
- 所需组件:
- 需要多少代理?什么任务?
- 需要多少技能?什么专业知识?
- 需要多少命令?什么工作流程?
- 有任何钩子?什么事件?
- 元数据:
- 作者信息
- 许可证类型(MIT, Apache 2.0等)
- 仓库URL
- 用于可搜索性的关键字
第2步:设计插件架构
计划组件结构:
示例:代码审查插件
code-review-suite/
├── agents/
│ ├── code-reviewer.md # 深度代码分析
│ └── security-auditor.md # 安全扫描
├── skills/
│ ├── reviewing-code/ # 始终开启的审查专业知识
│ └── detecting-vulnerabilities/ # 安全模式匹配
├── commands/
│ ├── review.md # /review [file]
│ ├── security-scan.md # /security-scan
│ └── suggest-improvements.md # /suggest-improvements
└── hooks/
└── hooks.json # 提交前验证
设计原则:
- 内聚性:组件应共同工作以实现共同目标
- 单一责任:每个组件都有明确、专注的目的
- 最小重叠:避免重复功能
- 逐步复杂性:从简单开始,逐步添加功能
第3步:创建目录结构
mkdir -p plugin-name/.claude-plugin
mkdir -p plugin-name/agents
mkdir -p plugin-name/skills
mkdir -p plugin-name/commands
mkdir -p plugin-name/hooks
mkdir -p plugin-name/scripts
第4步:创建plugin.json清单
使用plugin.json模式模板并填写所有字段:
{
"name": "plugin-name",
"version": "1.0.0",
"description": "这个插件提供什么的详细描述",
"author": {
"name": "作者名字",
"email": "email@example.com",
"url": "https://github.com/username"
},
"homepage": "https://github.com/username/plugin-name",
"repository": "https://github.com/username/plugin-name",
"license": "MIT",
"keywords": ["领域", "自动化", "工具"],
"commands": "./commands/",
"agents": "./agents/",
"skills": "./skills/",
"hooks": ["./hooks/hooks.json"]
}
关键验证:
- 有效的JSON语法(使用
python3 -m json.tool plugin.json) - 名称遵循小写连字符约定
- 版本是语义化的(X.Y.Z)
- 所有路径引用实际的目录/文件
第5步:创建组件
使用适当的专业知识创建每个组件:
对于代理:
- 遵循building-agents技能指导
- 使用agent-template.md作为起点
- 放置在
plugin-name/agents/
对于技能:
- 遵循building-skills技能指导
- 创建一个带有SKILL.md的目录
- 放置在
plugin-name/skills/skill-name/
对于命令:
- 遵循building-commands技能指导
- 使用command-template.md作为起点
- 放置在
plugin-name/commands/
对于钩子:
- 遵循building-hooks技能指导
- 创建hooks.json配置
- 放置在
plugin-name/hooks/
第6步:编写全面的README.md
使用{baseDir}/templates/plugin-readme-template.md中的README模板。
必需部分:
- 标题和描述:插件的作用
- 功能:关键能力
- 安装:如何安装
- 组件:列出所有代理/技能/命令/钩子
- 使用:示例和工作流程
- 配置:任何所需的设置
- 许可证:许可证信息
可选部分:
- 屏幕截图/演示
- 架构图
- 故障排除
- 贡献指南
- 更新日志
第7步:验证插件
运行验证脚本:
python3 {baseDir}/scripts/validate-plugin.py plugin-name/
验证检查:
- [ ]
plugin.json存在并且有有效的JSON - [ ] 必需字段存在(名称、版本、描述)
- [ ] 名称遵循约定(小写连字符,最多64个字符)
- [ ] 版本遵循语义化版本控制
- [ ] 所有引用的路径存在
- [ ] 所有组件有效(代理、技能、命令、钩子)
- [ ] README.md存在并且全面
- [ ] 如果指定了许可证,则存在许可证文件
- [ ] 没有安全问题(暴露的秘密、危险的脚本)
第8步:测试插件
测试清单:
- 安装测试:创建到
.claude/plugins/的符号链接,并验证Claude是否加载它 - 组件测试:
- 手动调用每个代理
- 触发技能自动调用
- 使用各种参数运行每个命令
- 用相关事件触发钩子
- 集成测试:验证组件协同工作
- 边缘情况:测试无效输入、缺失文件等
第9步:记录使用情况
提供清晰的指导:
## 安装
### 手动安装
1. 克隆这个仓库
2. 创建到Claude的插件目录的符号链接:
```bash
ln -s /path/to/plugin-name ~/.claude/plugins/plugin-name
- 重启Claude Code
市场安装(如果发布)
claude plugin install plugin-name
快速开始
-
运行你的第一个命令:
/plugin-name:command arg1 arg2 -
调用代理:
让Claude使用agent-name代理 -
自动调用的技能: 技能在相关时自动激活。
## 插件模板
这个技能提供了三个不同用例的插件模板:
### 1. 最小插件模板
**文件**:`{baseDir}/templates/minimal-plugin-template/`
**何时使用:**
- 创建一个简单、单一目的的插件
- 只需要1-2个组件
- 最小复杂性
**结构:**
minimal-plugin/ ├── .claude-plugin/plugin.json ├── commands/ │ └── main-command.md └── README.md
### 2. 标准插件模板
**文件**:`{baseDir}/templates/standard-plugin-template/`
**何时使用:**
- 构建具有多个组件的典型插件
- 需要代理+命令或技能+钩子
- 中等复杂性
**结构:**
standard-plugin/ ├── .claude-plugin/plugin.json ├── agents/ │ └── main-agent.md ├── commands/ │ ├── command1.md │ └── command2.md ├── scripts/ │ └── helper.sh └── README.md
### 3. 完整插件模板
**文件**:`{baseDir}/templates/full-plugin-template/`
**何时使用:**
- 构建全面的插件套件
- 需要所有组件类型
- 多个集成的高复杂性
**结构:**
full-plugin/ ├── .claude-plugin/plugin.json ├── agents/ │ ├── agent1.md │ └── agent2.md ├── skills/ │ ├── skill1/ │ │ ├── SKILL.md │ │ └── scripts/ │ └── skill2/ │ └── SKILL.md ├── commands/ │ ├── cmd1.md │ ├── cmd2.md │ └── cmd3.md ├── hooks/ │ ├── hooks.json │ └── scripts/ ├── scripts/ │ └── setup.sh ├── .mcp.json ├── LICENSE └── README.md
## 常见插件模式
### 模式1:开发工具插件
**目的**:自动化常见的开发工作流程
**组件:**
- **代理**:`code-reviewer`, `test-generator`, `refactoring-assistant`
- **技能**:`reviewing-code`, `writing-tests`, `refactoring-code`
- **命令**:`/format`, `/lint`, `/test`, `/build`
- **钩子**:`PreToolUse`用于代码质量检查
**示例:** `dev-tools-suite`, `code-quality-automation`
### 模式2:领域专业知识插件
**目的**:为领域提供专业知识
**组件:**
- **技能**:领域特定的专业知识(自动调用)
- **命令**:特定于领域的工作流程
- **代理**:深度分析复杂领域任务
**示例:** `data-analytics-tools`, `api-design-suite`, `security-analysis`
### 模式3:工作流自动化插件
**目的**:自动化重复的任务和流程
**组件:**
- **命令**:用户触发的工作流
- **钩子**:事件驱动的自动化
- **脚本**:辅助工具
- **技能**:自动化的背景专业知识
**示例:** `git-workflow-automation`, `deployment-automation`, `project-scaffolding`
### 模式4:集成插件
**目的**:将Claude连接到外部工具和服务
**组件:**
- **MCP服务器**:外部服务连接
- **命令**:触发集成
- **代理**:处理外部数据
- **技能**:关于外部服务的上下文
**示例:** `github-integration`, `jira-connector`, `database-tools`
## 市场集成
如果你为Claude Code市场仓库创建插件,你必须维护中央注册表。
### marketplace.json注册
**文件**:`.claude-plugin/marketplace.json`(在仓库根目录)
这个文件是市场所有插件的**中央注册表**。
#### 添加新插件时
更新`.claude-plugin/marketplace.json`:
```json
{
"metadata": {
"name": "Claude Code Plugin Marketplace",
"version": "X.Y.Z", // ← 增加MINOR版本
"stats": {
"totalPlugins": N, // ← 增加计数
"lastUpdated": "YYYY-MM-DD" // ← 更新日期
}
},
"plugins": [
// ...现有插件...
{
"name": "new-plugin-name",
"source": "./new-plugin-name", // ← 插件目录的路径
"description": "插件描述",
"version": "1.0.0",
"category": "development-tools", // 或"automation", "integration"等。
"keywords": ["keyword1", "keyword2"],
"author": {
"name": "作者名字",
"url": "https://github.com/username"
},
"repository": "https://github.com/username/repo",
"license": "MIT",
"homepage": "https://github.com/username/repo/tree/main/plugin-name"
}
]
}
更新现有插件时
更新两个文件:
1. 插件的plugin.json:
- 增加版本(遵循语义化版本控制)
- 如果更改,更新描述
- 如果更改,更新组件数组
2. 根marketplace.json:
{
"metadata": {
"version": "X.Y.Z", // ← 增加PATCH版本
"stats": {
"lastUpdated": "YYYY-MM-DD" // ← 更新日期
}
},
"plugins": [
{
"name": "existing-plugin",
"version": "1.2.0", // ← 必须与插件的plugin.json匹配
"description": "如果更改,更新描述"
// ...其他字段
}
]
}
关键:保持版本同步
marketplace.json中的版本必须与插件的plugin.json版本匹配- 不一致会破坏安装和更新
为什么这很重要
- 发现:用户浏览marketplace.json以查找插件
- 安装:CLI使用marketplace.json定位和安装插件
- 更新:版本跟踪依赖于marketplace.json
- 文档:插件列表是从marketplace.json生成的
验证脚本
validate-plugin.py
位置:{baseDir}/scripts/validate-plugin.py
用法:
python3 {baseDir}/scripts/validate-plugin.py /path/to/plugin/
验证:
-
目录结构
.claude-plugin/plugin.json存在- 引用的目录存在
- README.md存在
-
plugin.json模式
- 有效的JSON语法
- 必需字段存在
- 名称遵循约定
- 版本是语义化的
- 路径引用现有文件
-
组件验证
- 代理:有效的YAML前言和模式
- 技能:有效的SKILL.md和目录结构
- 命令:有效的YAML前言
- 钩子:有效的hooks.json模式
-
安全检查
- 文件中没有暴露的秘密
- 安全脚本权限
- 没有危险的bash操作
-
文档
- README.md完整性
- 如果指定了许可证,则存在LICENSE文件
退出代码:
0:所有验证通过1:发现关键错误2:仅警告(非阻塞)
示例输出:
✅ PLUGIN VALIDATION: my-plugin
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 plugin.json
✓ 有效的JSON语法
✓ 必需字段存在
✓ 名称遵循约定
✓ 语义化版本控制
📁 目录结构
✓ .claude-plugin/plugin.json存在
✓ 所有引用的路径存在
✓ README.md存在
🔧 组件(5个总数)
✓ 2个代理验证
✓ 1个技能验证
✓ 2个命令验证
🔒 安全
✓ 没有暴露的秘密
✓ 安全脚本权限
📝 文档
⚠ README.md缺少使用示例
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ VALIDATION PASSED (1 warning)
安全考虑
创建插件时:
-
输入验证
- 验证所有命令参数
- 清理文件路径
- 避免脚本中的命令注入
-
权限
- 在技能中使用最小的
allowed-tools - 要求用户确认破坏性操作
- 除非必要,不要预先批准危险工具(Bash, Write)
- 在技能中使用最小的
-
秘密管理
- 永远不要硬编码API密钥、令牌或凭据
- 使用环境变量:
${API_KEY} - 将
.env添加到.gitignore - 文档所需的环境变量
-
脚本安全
- 验证脚本输入
- 避免
eval()和动态代码执行 - 使用绝对路径,而不是相对路径
- 设置限制性权限(文件为644,可执行文件为755)
-
依赖项
- 文档所有外部依赖项
- 固定版本以确保可复制性
- 避免不必要的依赖项
最佳实践
1. 从简单开始,迭代
从最小的功能开始:
- 最初1-2个组件
- 彻底测试
- 根据反馈添加功能
- 每次添加都进行版本升级
2. 清晰的文档
用户应该理解:
- 插件的作用(电梯音)
- 如何安装它
- 如何使用每个组件
- 配置要求
- 常见问题的故障排除
3. 一致的命名
在组件中使用命名方案:
plugin-name:category:action用于命名空间命令- 相关组件的相似前缀
- 描述性,而不是可爱或聪明
4. 深思熟虑的版本
- 从
1.0.0开始初始发布 - 重大更改时增加MAJOR
- 新功能时增加MINOR
- 错误修复时增加PATCH
- 更新marketplace.json以匹配
5. 全面测试
发布前:
- 手动测试所有组件
- 边缘情况测试
- 集成测试
- 在干净环境中进行安装测试
- 验证脚本通过
6. 保持质量
发布后:
- 监控用户反馈
- 及时修复错误
- 小心地添加功能
- 保持文档更新
- 回应问题
参考文档
全面的指南和示例:
你的角色
当用户要求创建插件时:
- 评估范围:了解插件应该做什么
- 推荐架构:建议组件分解
- 验证方法:确保有凝聚力,而不是分散的
- 指导创建:使用模板和验证
- 确保质量:全面测试和文档
- 注册插件:如果适用,更新marketplace.json
要主动:
- 推荐插件而不是分散的组件
- 建议有凝聚力的组件架构
- 及早识别安全问题
- 确保全面的文档
- 在考虑“完成”之前进行验证
你的目标是帮助用户创建高质量、结构良好的插件,提供真正的价值,并遵循最佳实践。
插件设置模式
插件可以使用.claude/plugin-name.local.md模式实现用户可配置的设置。这允许用户在每个项目的基础上自定义插件行为。
文件位置和格式
位置:项目根目录中的.claude/<plugin-name>.local.md
格式:YAML前言+markdown正文
---
# 插件配置(YAML前言)
enabled: true
mode: strict
custom_option: value
---
# 插件上下文(markdown正文)
插件应该考虑的任何项目特定信息。
这个内容可以由钩子或技能加载。
用例
1. 钩子激活控制
---
validation_enabled: true
auto_format: false
---
钩子脚本检查此设置:
#!/bin/bash
CONFIG_FILE=".claude/${PLUGIN_NAME}.local.md"
# 配置不存在时快速退出
[ ! -f "$CONFIG_FILE" ] && exit 0
# 从前文中解析启用设置
ENABLED=$(sed -n '/^---$/,/^---$/p' "$CONFIG_FILE" | grep "^validation_enabled:" | cut -d: -f2 | tr -d ' ')
[ "$ENABLED" != "true" ] && exit 0
# 继续钩子逻辑...
2. 代理状态管理
---
assigned_tasks:
- review-api-endpoints
- update-documentation
completed_reviews: 5
last_run: "2025-01-15"
---
3. 项目特定上下文
---
enabled: true
---
## 项目约定
- 所有新代码使用TypeScript
- 遵循Airbnb风格指南
- 所有API端点必须有测试
## 领域知识
这个项目管理客户计费。关键概念:
- 订阅具有每月/年度周期
- 账单在计费日期生成
在钩子中解析设置
提取字符串/布尔字段:
get_setting() {
local file="$1"
local key="$2"
sed -n '/^---$/,/^---$/p' "$file" | grep "^${key}:" | cut -d: -f2 | tr -d ' '
}
ENABLED=$(get_setting ".claude/my-plugin.local.md" "enabled")
MODE=$(get_setting ".claude/my-plugin.local.md" "mode")
提取markdown正文:
get_body() {
local file="$1"
sed '1,/^---$/d' "$file" | sed '1,/^---$/d'
}
CONTEXT=$(get_body ".claude/my-plugin.local.md")
最佳实践
- 使用
.local.md后缀:表示用户本地设置,应该在.gitignore中 - 提供合理的默认值:没有设置文件时插件应该可以工作
- 文档记录所有设置:在插件README中列出选项
- 验证设置:在钩子中检查所需的值
- 处理缺失文件:始终首先检查设置文件是否存在
- 需要重新启动:设置仅在会话开始时加载
插件设置文件模板
---
# my-plugin设置
# 复制到.claude/my-plugin.local.md并自定义
# 启用/禁用此项目的插件
enabled: true
# 验证严格性:严格 | 正常 | 宽松
mode: normal
# 自定义选项(插件特定)
option1: value1
option2: value2
---
# 项目特定上下文
在这里添加任何插件应该考虑的项目特定信息。
与组件集成
在钩子中(最常见):
CONFIG=".claude/my-plugin.local.md"
[ -f "$CONFIG" ] && ENABLED=$(get_setting "$CONFIG" "enabled")
在技能中(通过描述触发器): 技能可以提到在它们的工作流程中检查项目设置。
在命令中(通过参数默认值): 命令可以读取设置以获取默认值。
常见问题
Q: 我应该何时创建插件与单独组件? A: 当你有3+个相关组件或想要作为包分发功能时,创建插件。单独组件适用于一次性定制。
Q: 我可以包含其他插件作为依赖项吗? A: 不能直接包含。在README.md中记录所需的插件,并指导用户单独安装它们。
Q: 我如何处理插件更新? A: 在plugin.json中增加版本,更新marketplace.json,记录README.md中的更改,然后在发布前彻底测试。
Q: 插件可以有配置文件吗?
A: 可以!使用.plugin-name.config.json或类似的。在README.md中记录配置选项。
Q: 插件关键字和类别有什么区别? A: 关键字用于搜索(字符串数组)。类别按类型对插件进行分组(单个字符串)。两者都提高了可发现性。
Q: 我如何弃用插件组件? A: 在README.md中记录,在组件描述中添加弃用通知,至少维护一个MAJOR版本,然后移除并在MAJOR版本中增加。
总结
创建插件是将专业知识捆绑到可重用、可分发的包中。遵循结构,彻底验证,全面文档,并广泛测试。插件应该感觉像是Claude能力的自然扩展,提供价值而不带来摩擦。