从零开发 Claude Code 插件：完整实战指南

为什么要写插件

Claude Code 的插件系统让你可以定制自己的命令和技能。想让 Claude 自动提交代码？写个 /commit 命令。想让它在特定场景自动触发某个工作流？写个技能。

插件开发不复杂，但官方文档比较分散。这篇文章把完整流程梳理一遍——从目录结构到发布上线，每个步骤都有实际例子。

我自己开发过几个插件，踩过一些坑。文章里会标注常见错误和避坑建议。

面向读者：有基本编程经验，想自己开发插件或贡献到社区。不需要深厚的 AI 知识，会写 Markdown 和 Bash 就行。

目录结构

一个完整的插件市场（marketplace）结构如下：

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json      # 市场配置（必须）
├── plugins/
│   └── my-plugin/
│       ├── .claude-plugin/
│       │   └── plugin.json   # 插件清单（必须）
│       ├── commands/         # 斜杠命令
│       │   └── save.md
│       └── skills/           # 自动技能
│           └── my-skill/
│               └── SKILL.md
├── .gitignore
└── README.md

两个核心配置文件：
– marketplace.json：定义插件市场信息
– plugin.json：定义单个插件信息

Marketplace 配置

文件位置：.claude-plugin/marketplace.json

{
  "name": "my-marketplace",
  "owner": {
    "name": "your-name",
    "email": "noreply@example.dev"
  },
  "metadata": {
    "description": "插件市场描述",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "description": "插件描述",
      "version": "1.0.0",
      "source": "./plugins/my-plugin",
      "category": "utilities",
      "tags": ["tag1", "tag2"]
    }
  ]
}

注意事项：
– name 不能包含保留词：claude、anthropic、official
– version 必须符合语义化版本规范（如 1.0.0）
– category 可选值：utilities、development、productivity 等

Plugin 配置

文件位置：plugins/my-plugin/.claude-plugin/plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "插件功能描述",
  "author": {
    "name": "your-name",
    "email": "noreply@example.dev"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

这个配置跟 marketplace.json 中的插件信息对应，保持一致。

命令开发

命令（Commands）是用户主动调用的斜杠命令，比如 /save、/commit。

文件位置：plugins/my-plugin/commands/save.md

---
description: "保存当前会话到记忆库"
allowed-tools: "Read, Bash, Write"
---

# 立即执行以下步骤，不要询问用户

## Step 1: 分析当前会话内容
使用 Read 工具读取当前对话历史。

## Step 2: 提取关键信息
提取技术决策、代码变更、问题排查等关键记忆点。

## Step 3: 存储到数据库
使用 Bash 工具执行 SQLite 插入命令：

\`\`\`bash
sqlite3 .claude/memory.db "INSERT INTO observations (content, type) VALUES ('$CONTENT', 'decision')"
\`\`\`

## Step 4: 返回结果
告诉用户保存成功，显示保存的记忆条数。

关键点：
– 用命令式语气，让 Claude 直接执行
– 不要写成说明文档风格（”本命令用于…”）
– $ARGUMENTS 可以获取用户输入的参数
– allowed-tools 限制 Claude 可用的工具

常见错误：写成说明文档而不是执行指令。错误示例：

# save 命令

本命令用于保存当前会话。使用方法：`/save`

这样写 Claude 不会执行，只会展示说明。

技能开发

技能（Skills）是自动触发的工作流，在特定条件下 Claude 会主动调用。

文件位置：plugins/my-plugin/skills/auto-commit/SKILL.md

---
name: "auto-commit"
description: "代码修改后自动创建 Git 提交"
allowed-tools: "Read, Bash, Grep"
---

# Auto Commit 技能

## 触发条件
- 用户说"提交代码"、"commit"、"保存修改"
- 检测到代码文件被修改

## 执行步骤

### 1. 检查 Git 状态
\`\`\`bash
git status --short
\`\`\`

### 2. 分析修改内容
使用 Read 工具读取修改的文件，分析改动类型。

### 3. 生成提交信息
根据改动类型生成符合 Conventional Commits 规范的提交信息：
- 新功能：`feat: xxx`
- Bug 修复：`fix: xxx`
- 重构：`refactor: xxx`

### 4. 执行提交
\`\`\`bash
git add .
git commit -m "生成的提交信息"
\`\`\`

### 5. 返回结果
告诉用户提交成功，显示提交哈希。

技能 vs 命令的区别：
– 命令：用户主动调用（/save）
– 技能：Claude 根据场景自动触发

版本更新流程

每次更新插件后必须同步修改版本号，否则用户更新时不会生效。

需要修改两个地方：

1. .claude-plugin/marketplace.json

{
  "metadata": {
    "version": "1.1.0"  // 修改这里
  },
  "plugins": [
    {
      "version": "1.1.0"  // 修改这里
    }
  ]
}

1. plugins/xxx/.claude-plugin/plugin.json

{
  "version": "1.1.0"  // 修改这里
}

版本号规则：
– 主版本号（Major）：不兼容的 API 变更
– 次版本号（Minor）：向下兼容的功能新增
– 修订号（Patch）：向下兼容的 Bug 修复

更新后推送到 GitHub，用户执行 /plugin update xxx 即可更新。

发布流程

1. 推送代码到 GitHub

git add -A
git commit -m "feat: initial release"
git push origin main

2. 修改仓库描述（可选）

gh repo edit owner/repo --description "插件描述"

3. 发布 Release

gh release create v1.0.0 --title "v1.0.0" --notes "首次发布"

发布后，用户就可以通过插件市场安装了。

用户安装

用户安装你的插件只需两步：

# 1. 添加插件市场
/plugin marketplace add https://github.com/owner/repo

# 2. 安装插件
/plugin install my-plugin

安装后，命令和技能会自动生效。

常见问题

名称包含保留词

错误信息：Plugin name cannot contain reserved words

解决方案：改名，不用 claude、anthropic、official 等词。

更新后不生效

检查版本号是否递增。Claude Code 根据版本号判断是否需要更新。

命令不执行

检查 Markdown 文件是否用命令式语气。不要写成说明文档风格。

错误示例：

本命令用于保存会话。

正确示例：

立即执行以下步骤：读取会话内容，提取关键信息，存储到数据库。

路径找不到

插件安装后会放在缓存目录，路径包含版本号。比如：

~/.claude/plugins/cache/my-marketplace/my-plugin/1.0.0/

如果不确定路径，用 find 查找：

find ~/.claude/plugins -name "my-plugin"

参考资源

• 官方文档：Claude Code Plugins
• 官方模板：claude-code-plugin-template
• 示例市场：gmickel-claude-marketplace
• memory-manager 插件：cfrs2005/claude-plugins

最后说几句

插件开发的核心是理解 Claude 的工作方式——你不是在写程序，而是在写”指令”。

好的插件应该：
– 指令明确，不含糊
– 流程清晰，可追溯
– 错误处理完善，不会卡住

从简单的命令开始，熟悉了再做复杂的技能。开发过程中多测试，特别是边界情况。

祝你开发顺利。