插件系统

使用 Claude Code 插件系统创建自定义命令、代理和工作流

插件系统 ¶

Claude Code 插件系统允许你扩展 Claude 的功能，创建自定义斜杠命令、专门的代理、可复用的技能，以及自动化钩子。通过插件，你可以将团队的最佳实践和工作流程编码化。

什么是插件？¶

基本概念 ¶

Claude Code 插件是一个包含特定文件结构的目录，可以添加以下组件：

组件	说明	文件格式
Commands（命令）	自定义斜杠命令	`.md` 文件
Agents（代理）	专门任务的子代理	`.md` 文件
Skills（技能）	可复用的知识和能力	目录 + `SKILL.md`
Hooks（钩子）	事件触发的自动化	`hooks.json`

为什么需要插件？¶

团队规范化：将编码规范、审查标准编码为可执行命令
工作流自动化：自动化重复性任务，如提交、部署、审查
知识共享：团队成员共享最佳实践和专业知识
定制体验：根据项目需求定制 Claude 的行为

插件目录结构 ¶

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 必需：插件配置清单
├── commands/                 # 斜杠命令（.md 文件）
│   ├── review.md
│   └── deploy.md
├── agents/                   # 子代理定义（.md 文件）
│   └── code-reviewer.md
├── skills/                   # 代理技能（子目录）
│   └── coding-standards/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # 事件处理配置
├── .mcp.json                # MCP 服务器定义（可选）
└── scripts/                 # 辅助脚本（可选）

快速开始 ¶

安装插件 ¶

# 从市场安装
/plugin install plugin-name@claude-code-marketplace

# 从本地目录安装
claude --plugin-dir /path/to/my-plugin

使用插件创建向导 ¶

/plugin-dev:create-plugin

这个命令会引导你完成 8 个阶段来创建一个完整的插件。

创建自定义命令 ¶

基本命令格式 ¶

在 commands/ 目录创建 .md 文件：

---
description: 执行代码审查
argument-hint: [file-path]
allowed-tools: Read, Bash(git:*)
---

请审查以下文件的代码质量：@$1

重点检查：
1. 代码可读性
2. 潜在的 bug
3. 性能问题
4. 安全漏洞

YAML 前置配置 ¶

字段	说明	示例
`description`	命令描述（显示在 /help）	`执行代码审查`
`argument-hint`	参数提示	`[file-path] [options]`
`allowed-tools`	允许使用的工具	`Read, Bash(git:*)`
`model`	指定模型	`opus` 或 `sonnet`

使用动态参数 ¶

$1, $2, $3... - 位置参数
$ARGUMENTS - 所有参数
@path/to/file - 文件引用
!command`` - 执行 Bash 命令

命令示例 ¶

代码审查命令 (commands/review.md)：

---
description: 全面的代码审查
argument-hint: [file-or-directory]
allowed-tools: Read, Grep, Glob
model: opus
---

对 @$1 进行全面的代码审查。

检查清单：

- [ ] 代码风格是否符合项目规范
- [ ] 是否有潜在的安全问题
- [ ] 错误处理是否完善
- [ ] 是否需要添加测试

如果是目录，先用 Glob 工具找到所有相关文件。

智能提交命令 (commands/commit.md)：

---
description: 智能生成 commit 并提交
allowed-tools: Bash(git:*)
---

1. 运行 `git status` 查看更改
2. 运行 `git diff --staged` 分析已暂存的更改
3. 根据更改内容生成规范的 commit message
4. 执行 `git commit`

Commit message 格式：

- feat: 新功能
- fix: Bug 修复
- docs: 文档更新
- refactor: 重构
- test: 测试相关

创建自定义代理 ¶

代理定义格式 ¶

在 agents/ 目录创建 .md 文件：

---
description: 专门的代码审查代理
model: opus
tools: Read, Grep, Glob
---

你是一个专业的代码审查代理。你的任务是：

1. 仔细阅读提供的代码
2. 识别潜在问题
3. 提供具体的改进建议
4. 关注安全性和性能

始终保持建设性和具体性。

代理类型 ¶

类型	用途	示例
审查代理	代码审查、PR 审查	`code-reviewer`
测试代理	生成和运行测试	`test-generator`
文档代理	生成文档	`doc-writer`
重构代理	代码重构	`refactorer`

创建技能 ¶

技能目录结构 ¶

skills/
└── coding-standards/
    ├── SKILL.md              # 必需：技能定义
    ├── references/           # 参考资料
    │   └── style-guide.md
    └── examples/             # 示例代码
        └── good-practices.md

SKILL.md 格式 ¶

# 编码规范技能

## 概述
这个技能包含团队的编码规范和最佳实践。

## 知识内容

### 命名规范

- 变量：camelCase
- 常量：UPPER_SNAKE_CASE
- 类：PascalCase
- 文件：kebab-case

### 代码风格

- 使用 2 空格缩进
- 最大行宽 100 字符
- 使用分号

### 错误处理

- 始终使用 try-catch
- 记录错误日志
- 提供有意义的错误消息

创建钩子 ¶

hooks.json 格式 ¶

{
  "hooks": [
    {
      "event": "on_commit",
      "command": "npm run lint",
      "description": "提交前运行 lint 检查"
    },
    {
      "event": "on_file_change",
      "pattern": "*.ts",
      "command": "npm run typecheck",
      "description": "TypeScript 文件变更时检查类型"
    }
  ]
}

支持的事件 ¶

事件	触发时机
`on_commit`	提交代码时
`on_file_change`	文件变更时
`on_session_start`	会话开始时
`on_command`	执行命令时

插件配置清单 ¶

plugin.json 格式 ¶

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的自定义插件",
  "author": "Your Name",
  "components": {
    "commands": ["commands/*.md"],
    "agents": ["agents/*.md"],
    "skills": ["skills/*/SKILL.md"],
    "hooks": "hooks/hooks.json"
  },
  "mcpServers": ".mcp.json"
}

实际应用示例 ¶

示例 1：团队代码审查插件 ¶

team-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── review-pr.md          # PR 审查命令
│   ├── security-check.md     # 安全检查命令
│   └── perf-audit.md         # 性能审计命令
├── agents/
│   ├── security-reviewer.md  # 安全审查代理
│   └── perf-analyzer.md      # 性能分析代理
└── skills/
    └── team-standards/
        └── SKILL.md          # 团队规范技能

示例 2：部署自动化插件 ¶

deploy-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy-staging.md     # 部署到测试环境
│   ├── deploy-prod.md        # 部署到生产环境
│   └── rollback.md           # 回滚命令
├── hooks/
│   └── hooks.json            # 部署前检查钩子
└── .mcp.json                 # Kubernetes MCP 配置

最佳实践 ¶

命令设计 ¶

单一职责：每个命令只做一件事
清晰描述：description 要简洁明了
参数文档：使用 argument-hint 说明参数
最小权限：allowed-tools 只包含必要工具
错误处理：考虑失败场景

插件组织 ¶

模块化：相关功能组织在一起
可复用：技能应该可以被多个命令使用
文档化：添加 README 和使用说明
版本管理：使用语义化版本号

安全考虑 ¶

不硬编码密钥：使用环境变量
限制文件访问：只访问必要的路径
验证输入：对参数进行验证
审计日志：记录敏感操作

调试插件 ¶

# 查看插件加载状态
/plugin list

# 查看命令详情
/help my-command

# 测试命令
/my-command test-argument

下一步 ¶

学习 MCP 服务器扩展外部集成
查看 CLI 技巧提升使用效率
探索工作流技巧优化开发流程

← 上一篇

MCP 服务器

自动化与 CI/CD

🚀

开始使用 QCode — AI 编程助手

Claude Code 官方中继，稳定快速，开箱即用

查看套餐定价 → 注册账号