第3课：创建自定义插件

为什么需要这个#

现成的插件并不总能满足你的需求。创建自己的插件可以：

🎯 自动化重复的工作流程
👥 与团队共享工具
📦 将知识和实践打包为可移植的格式
🏪 向社区发布插件

在本课中，我们将使用 plugin-dev 插件的材料从零创建一个插件。

第1步：创建文件夹结构#

# 创建插件文件夹
mkdir -p my-awesome-plugin/.claude-plugin
mkdir -p my-awesome-plugin/commands
mkdir -p my-awesome-plugin/agents
mkdir -p my-awesome-plugin/skills/my-skill
mkdir -p my-awesome-plugin/hooks

得到如下结构：

my-awesome-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
├── skills/
│   └── my-skill/
└── hooks/

第2步：创建清单文件（plugin.json）#

文件 .claude-plugin/plugin.json 是你插件的"身份证"：

{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "用于自动化工作流程的插件",
  "author": {
    "name": "你的名字",
    "email": "you@example.com"
  },
  "keywords": ["automation", "workflow"]
}

可用的清单字段#

字段	必填	说明
`name`	✅ 是	`kebab-case` 格式的唯一名称
`version`	否	`MAJOR.MINOR.PATCH` 格式的版本号（例如 `1.0.0`）
`description`	否	简短描述（50-200个字符）
`author`	否	作者姓名和邮箱
`homepage`	否	文档链接
`repository`	否	代码仓库链接
`license`	否	许可证（例如 `MIT`）
`keywords`	否	搜索标签

第3步：创建命令（Command）#

命令是用户在 Claude Code 中输入的斜杠命令（例如 /my-plugin:hello）。

创建文件 commands/hello.md：

---
name: hello
description: 问候用户并显示项目信息
---

# Hello 命令

执行以下操作：

1. 用友好的消息问候用户
2. 显示当前日期和时间
3. 如果有 README.md 文件——简要描述项目
4. 建议从哪里开始工作

要友好且积极！

Frontmatter — 命令头部#

--- 和 --- 之间的块称为 frontmatter（元数据）。它包含：

name — 命令名称（如何调用）
description — 描述（显示在提示中）

带参数的命令#

创建 commands/review-file.md：

---
name: review-file
description: 检查指定文件的错误和代码风格
---

# 文件审查

用户想检查文件：$ARGUMENTS

执行以下检查：
1. 语法错误
2. 代码风格不一致
3. 潜在的安全问题
4. 改进建议

以结构化报告的形式显示结果。

$ARGUMENTS 是一个特殊变量，包含命令后面的文本。如果用户输入 /my-plugin:review-file src/app.js，那么 $ARGUMENTS 的值就是 src/app.js。

第4步：创建代理（Agent）#

代理是一个专门的助手，Claude Code 可以调用它来解决特定任务。与命令不同，代理在自己的上下文中工作。

创建文件 agents/code-checker.md：

---
name: code-checker
description: 专门用于代码质量检查的代理
---

# 代码质量检查代理

你是代码质量专家。你的任务是：

1. 分析提供的代码
2. 查找潜在的错误
3. 检查是否遵循最佳实践
4. 提出具体的改进建议

## 工作规则

- 始终解释**为什么**某些内容是问题
- 提供正确代码的示例
- 按严重程度排序：🔴 严重、🟡 重要、🟢 建议

第5步：创建技能（Skill）#

**技能（Skill）**是 Claude Code 在需要时自动加载的知识库。与命令不同，技能不会被直接调用——当主题相关时，Claude 会自动引用它。

创建文件 skills/my-skill/SKILL.md：

---
name: 我的编码风格技能
description: 当用户要求编写或审查 Python 代码时使用此技能
version: 0.1.0
---

# Python 编码风格

## 规则

1. 所有函数使用 type hints
2. Docstrings 使用 Google 格式
3. 最大行长度为88个字符（Black 格式）
4. 使用 isort 排序导入

## 良好代码示例

```python
def calculate_total(items: list[dict], tax_rate: float = 0.1) -> float:
    """计算含税总额。

    Args:
        items: 包含 'price' 字段的商品列表。
        tax_rate: 税率（默认10%）。

    Returns:
        含税总额。
    """
    subtotal = sum(item["price"] for item in items)
    return subtotal * (1 + tax_rate)


## 第6步：添加钩子

创建文件 `hooks/hooks.json`：

```json
{
  "description": "代码质量检查钩子",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查文件是否包含注释且不包含硬编码的密码或 API 密钥。如果一切正常返回 'approve'，否则返回 'deny' 并附上解释。",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

第7步：测试插件#

# 使用我们的插件启动 Claude Code
claude --plugin-dir ./my-awesome-plugin

# 在 Claude Code 中尝试命令：
> /my-awesome-plugin:hello
> /my-awesome-plugin:review-file src/main.py

调试时：

claude --plugin-dir ./my-awesome-plugin --debug

插件组件对比#

组件	如何调用	用途
命令	`/plugin:command`	用户请求的具体操作
代理	Claude 自动调用	复杂的专门任务
技能	按主题自动加载	背景知识和规则
钩子	事件触发时执行	自动检查/验证

课程总结#

插件由包含清单文件 plugin.json 和组件的文件夹创建
命令是包含 Claude 指令的 Markdown 文件，通过 / 调用
代理是用于复杂任务的专门助手
技能是自动加载的知识库
钩子是事件触发时的自动检查
$ARGUMENTS 传递命令参数
使用 --plugin-dir 测试插件，使用 --debug 调试