Claude Code 作为 Anthropic 推出的 AI 编程助手，已经内置了强大的代码理解、生成和编辑能力。但每个开发者的工作流程都不尽相同，我们需要更个性化的功能来提升效率。

插件系统正是为了解决这一问题。它支持自定义斜杠命令、专属 Agent 以及自动化 Hook，使 Claude Code 能更好地适配个人或团队的开发习惯。

本文将从零开始介绍 Claude Code 插件的开发过程，并通过实际示例，梳理完整的插件开发流程。

关注公众号:weelinking | 访问官网:weelinking.com

💡 国内如何稳定使用 Claude？推荐 weelinking，国内可直连，按量付费，全系模型支持。

---

认识 Claude Code 插件

为什么需要插件？

在开始之前，先需要回答一个问题：为什么不直接使用项目内的 .claude/< 配置，而要单独开发插件？

独立配置适用场景：

• 仅在单个项目中使用的自定义功能
• 个人实验性的命令或智能体
• 不需要分享的临时配置

插件的优势：

• ✅ 团队共享：一次开发，可在多个项目中使用
• ✅ 版本控制：便于管理和更新
• ✅ 跨项目复用：避免重复配置
• ✅ 命名空间隔离：防止命令冲突

插件开发本身并不复杂，关键在于掌握合理的方法论。当需要在多个项目间共享功能，或进行团队协作时，插件是更合适的选择。

插件能做什么？

Claude Code 的插件系统提供了多种扩展能力，不仅限于简单命令定制：

• 自定义斜杠命令
  可以创建专属快捷指令，例如 /my-plugin:deploy 用于一键部署，或 /my-plugin:review 进行自动代码审查。命令支持参数传递，使功能更灵活。

• 专属 AI 智能体
  可定义特定领域的智能体，如「前端优化专家」或「数据库调优顾问」，每个智能体拥有独立的能力和知识体系。

• Hooks 系统
  支持在特定事件触发时自动执行任务，例如文件保存后自动格式化、代码提交前运行测试等。

• 扩展 Skills 能力
  为 Claude 添加新的专业技能，使其能够识别不同场景并调用对应工具，例如「自动生成 API 文档」或「智能重构建议」。

• 集成 MCP 和 LSP 服务
  可连接外部工具和服务，如数据库查询、API 测试、语言服务器等，实现更完整的开发流程和生态支持。

---

创建你的第一个插件

理论说再多，不如亲手实践。本章将带你快速创建一个功能完整的插件，让你直观感受开发流程。

创建插件目录结构

每个插件都需要标准的目录结构。先创建插件文件夹：

mkdir my-first-plugin

关键目录说明：

• .claude-plugin/：存放插件元数据，只包含 plugin.json
• commands/：存放斜杠命令定义
• agents/：存放自定义智能体（可选）
• skills/：存放技能扩展（可选）

⚠️ 常见误区：不要把 commands/、agents/ 等目录放在 .claude-plugin/ 内部！它们应该与 .claude-plugin/ 同级。

编写插件清单文件

创建 .claude-plugin 目录和清单文件：

mkdir my-first-plugin/.claude-plugin

编辑 my-first-plugin/.claude-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "description": "一个用于学习的简单插件",
  "version": "1.0.0",
  "author": {
    "name": "你的名字"
  }
}

字段解释：

• name：插件的唯一标识，也是命令命名空间前缀
• description：插件简介，会显示在插件管理器中
• version：遵循语义化版本号规范
• author：作者信息（可选）

实现第一个斜杠命令

创建 commands目录并添加第一个命令：

mkdir my-first-plugin/commands

编辑 my-first-plugin/commands/hello.md：

---
description: 向用户发送友好的问候
---

# Hello Command

向用户热情地问候，并询问今天可以帮他们做什么。

文件结构说明：

• 文件名 hello.md 对应命令 /my-first-plugin:hello
• YAML frontmatter 定义命令元信息
• Markdown 内容是命令的具体执行逻辑

本地测试插件

使用 --plugin-dir 标志加载插件进行测试：

claude --plugin-dir ./my-first-plugin

启动后，尝试运行新命令：

/my-first-plugin:hello

使用 /help 查看所有可用命令，你会发现新命令已经列在插件命名空间下。

💡 理解命名空间：插件命令必须带命名空间前缀（如 /my-first-plugin:hello），这样不同插件的同名命令就不会冲突。想修改前缀？更新 plugin.json 中的 name 字段即可。

让命令更智能：使用 $ARGUMENTS 接收用户输入

更新 my-first-plugin/commands/hello.md：

---
description: 向用户发送友好的问候
---

# Hello Command

向名叫 "$ARGUMENTS" 的用户热情问候，并询问今天可以帮他们做什么。

修改完成后，重启 Claude Code，然后运行命令：

/my-first-plugin:hello 小明

你会看到 Claude 使用名字生成问候语。如果需要更精细的参数控制，可以参考官方斜杠命令文档，了解各类参数变量的用法。

---

深入理解插件结构

创建简单插件只是开始，要开发真正实用的插件，需要全面理解插件系统的各个组件。

插件目录全貌

一个完整的插件目录结构如下：

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 插件清单（必需）
├── commands/                # 斜杠命令
│   ├── deploy.md
│   └── review.md
├── agents/                  # 子智能体定义
│   └── api-expert.md
├── skills/                  # 可复用技能模块
│   └── code-review/
│       └── SKILL.md
├── hooks/                   # 事件处理
│   └── hooks.json
├── .mcp.json                # MCP 服务定义
├── .lsp.json                # LSP 服务配置
└── README.md                # 插件说明

目录用途速查：

• commands/：定义可执行的斜杠命令
• agents/：创建具有特定能力的 AI 智能体
• skills/：扩展 Claude 的专业技能
• hooks/：设置事件触发器
• .mcp.json：配置外部工具集成
• .lsp.json：配置语言服务器

斜杠命令进阶

斜杠命令是插件的核心交互方式，支持多种参数模式：

---
description: 部署应用到指定环境
---

# 部署命令

准备将应用部署到 $1 环境。

使用配置文件：$ARGUMENTS

执行步骤：
1. 检查环境状态
2. 构建应用
3. 部署到 $1
4. 验证部署结果

参数技巧：

• $1、$2…：按位置获取参数
• $ARGUMENTS：获取所有剩余参数
• $FILE：获取当前文件路径（特定场景）

命令组织建议：

• 按功能模块分组命令
• 使用清晰的动词作为命令名
• 每个命令专注单一职责

💡 特别提示：本文所有操作均以 weelinking 为例。它提供国内直连 Claude 的服务，无需特殊网络设置，按量付费，新用户注册即送体验额度。

自定义智能体开发

智能体是具有特定专业能力的 AI 实体，适合处理复杂任务。

创建 agents/api-expert.md：

---
name: api-expert
description: REST API 设计和最佳实践专家
---

你是一名经验丰富的 API 架构师，专门设计生产级 REST API。

你的专业包括：
- RESTful 设计原则（正确的 HTTP 方法、状态码、资源命名）
- API 安全（OAuth、JWT、速率限制、输入验证）
- 性能（缓存、分页、压缩、异步模式）
- 文档（带示例的 OpenAPI/Swagger 规范）

帮助设计 API 时：
1. 在建议方案前先澄清需求
2. 设计直观、可预测的 REST 端点
3. 提供有用的错误消息和处理
4. 考虑版本控制和向后兼容
5. 用用户熟悉的语言/框架提供示例代码

始终以**可落地、可生产环境使用**为目标。

智能体特性：

• 拥有独立的系统提示词
• 可以访问特定的工具集
• 保持对话上下文
• 适合复杂、多步骤的任务

Hooks 事件系统

Hooks 让插件能够响应特定事件并自动执行操作。

创建 hooks/hooks.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

常用事件类型：

• PreToolUse：工具调用前触发
• PostToolUse：工具调用后触发
• Notification：发送通知时触发
• Stop：任务完成时触发
• SubagentStop：子智能体任务完成时触发

Hook 执行方式：

• command：执行 shell 命令
• function：调用自定义函数
• url：发送 HTTP 请求

---

插件高级功能开发

掌握了基础组件后，让我们探索插件系统的高级特性，这些功能将让你的插件变得更加强大。

Agent Skills 开发

Skills 是能够被 Claude 主动触发的专业技能，无需用户明确调用。

创建 skills/code-review/SKILL.md：

---
name: code-review
description: 审查代码的最佳实践和潜在问题。在审查代码、检查 PR 或分析代码质量时使用。
---

审查代码时，请检查：
1. 代码组织和结构
2. 错误处理机制
3. 安全考虑因素
4. 测试覆盖率
5. 性能影响

提供具体、可操作的改进建议。

技能触发机制：

• Claude 根据上下文自动判断何时使用
• 不需要用户明确调用
• 可以限制可用的工具集

技能设计原则：

• 聚焦特定领域
• 提供清晰的触发条件
• 包含具体的执行指导

MCP 服务器连接

MCP（Model Context Protocol）让插件能够连接外部工具和服务。

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

集成行为说明:

• 插件启用时，MCP 服务器会自动启动
• 服务器会以标准 MCP 工具的形式出现在 Claude 中
• 能力可直接被命令、agent 和 skills 使用
• 插件内的 MCP 配置与用户级 MCP 相互独立，互不影响

LSP 服务器集成

LSP（Language Server Protocol）为 Claude 提供实时代码智能。

配置 .lsp.json：

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

使用场景：

• 支持小众编程语言
• 自定义语言服务器配置
• 集成公司内部的代码分析工具

注意事项：

• 用户需要安装对应的语言服务器
• 配置错误可能导致代码智能功能异常
• 建议优先使用官方 LSP 插件

复杂插件组织

当插件功能丰富时，良好的组织结构至关重要。

按功能模块组织：

对于包含多个命令、Agent、Skill 或 Hook 的插件，建议按功能模块进行目录组织，而不是将所有文件堆放在同一目录中。想了解更完整的目录布局和组织方式，可参考插件目录结构[1]。

组织原则：

• 相关功能集中管理
• 清晰的命名约定
• 适当的文档说明
• 避免过度嵌套

插件本地测试

开发过程中，可以使用 --plugin-dir参数直接加载本地插件目录，无需安装：

claude --plugin-dir ./my-plugin

Claude 会在启动时读取该目录下的插件定义。

插件内容发生修改后，需要重启 Claude Code 才能生效。重启后可从以下几项进行验证：

• 使用 /插件名:命令名 测试命令是否可用
• 通过 /agents查看自定义 agent 是否加载
• 检查相关 hooks 是否按预期触发

💡 多插件加载：可以多次指定 --plugin-dir，同时加载多个插件目录：

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

🎯 你也可以创建一个本地插件市场用于测试：

mkdir -p dev-marketplace/.claude-plugin

编辑 dev-marketplace/.claude-plugin/marketplace.json：

{
  "name": "dev",
  "owner": {"name": "Me"},
  "plugins": [{
    "name": "my-plugin",
    "source": "../my-plugin",
    "description": "我的新插件"
  }]
}

在 Claude Code 中安装插件：

/plugin marketplace add ./dev-marketplace
/plugin install my-plugin@dev

建议保留 dev-marketplace，这样你就可以在其中添加任意数量的插件进行测试，而不会影响官方市场。

调试插件问题

如果插件没有按预期工作，可以按以下顺序排查：

1. 检查目录结构：确认 commands/、agents/、skills/ 等目录位于插件根目录下，而不是放在 .claude-plugin/ 内
2. 单独验证组件：分别测试每个命令、agent 和 hook，避免多个问题叠加
3. 使用调试工具：结合官方提供的校验与调试工具，查看 CLI 输出并定位具体错误

分享你的插件

当插件功能稳定后，可以考虑对外分享：

1. 补充文档：添加 README.md，说明安装方式和基本用法
2. 规范版本号：在 plugin.json 中使用语义化版本号
3. 选择分发方式：通过插件市场或内部仓库进行分发
4. 提前验证：在正式发布前，让其他成员参与测试

💡 本系列全程使用 weelinking 访问 Claude，国内可稳定使用

---

从现有配置迁移到插件

如果你已经在使用 .claude/ 目录中的自定义配置，迁移到插件格式是个不错的选择。本章将介绍如何完成平滑迁移。

迁移时机判断

适合迁移的情况：

• 需要在多个项目中使用相同配置
• 团队成员希望共享你的自定义功能
• 配置已经稳定，需要版本管理
• 准备公开发布你的扩展

暂时不迁移的情况：

• 仅在单个项目中使用的临时配置
• 正在快速迭代实验的功能
• 包含敏感信息的配置

迁移的成本收益分析：

• 成本：需要重构目录结构、更新命令调用方式
• 收益：更好的可维护性、团队协作能力、版本控制

迁移步骤详解

第一步：创建插件框架

mkdir -p my-plugin/.claude-plugin

创建 my-plugin/.claude-plugin/plugin.json：

{
  "name": "my-plugin",
  "description": "从独立配置迁移的插件",
  "version": "1.0.0"
}

第二步：复制现有配置

# 复制命令
cp -r .claude/commands my-plugin/

# 复制智能体（如果有）
cp -r .claude/agents my-plugin/

# 复制技能（如果有）
cp -r .claude/skills my-plugin/

第三步：迁移 Hooks

如果 Hooks 在 settings.json 中，需要提取到独立文件：

创建 my-plugin/hooks/hooks.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint:fix $FILE"
          }
        ]
      }
    ]
  }
}

第四步：测试迁移后的插件

加载插件，确认迁移后的结构和功能是否正常：

claude --plugin-dir ./my-plugin

启动后，逐项验证各个组件：

• 运行相关斜杠命令，确认命令可用
• 通过 /agents 检查 agent 是否正确加载
• 触发对应场景，验证 hooks 是否按预期执行

迁移后的变化

将原本的 .claude/ 配置迁移为插件后，使用和管理方式会有所不同：

原有方式（.claude/）	插件方式
仅在单个项目中可用	可通过插件市场共享
文件位于 .claude/commands/	文件位于 plugin-name/commands/
hooks 配置在 settings.json	hooks 配置在 hooks/hooks.json
需要手动复制才能共享	可通过 /plugin install 安装

💡 清理建议：在完成迁移并确认插件正常运行后，可删除原 .claude/ 目录中的相关文件，避免重复加载。插件配置的加载优先级高于目录配置。

---

总结

Claude Code 的插件系统，为我们提供了一种可复用、可定制、便于共享的工作流封装机制。无论你是直接使用社区插件，还是将团队经验整理成内部插件，都能显著提升开发效率，同时让流程也更加稳定和可控。

在掌握了 Claude Code 插件开发的基本流程后，你可以结合插件市场与实际需求，将这些流程应用到日常工作中，从而实现更高效的协作与开发。

🔗 本系列全程使用 Claude

文中的所有操作，你现在就可以上手。

推荐使用 weelinking 访问 Claude：

优势	说明
🇨🇳 国内直连	无需任何网络配置，打开即用
💰 按量付费	用多少花多少，不浪费
🎁 新用户福利	注册即送体验额度
⚡ 稳定可靠	账号池技术，不掉线

👉 立即注册，免费开始

---

既然看到这里了，如果觉得有启发，随手点个赞、推荐、转发三连吧，你的支持是我持续分享干货的动力。