Claude Code企业级插件开发实战：Skill、命令与MCP集成

这次我们来看 Claude Code 的企业级插件开发。Claude Code 是 Anthropic 推出的命令行 AI 编程工具直接在终端里读代码、改代码、跑测试、查日志很多团队已经把它当作“结对程序员”在用。但默认安装只是基本盘真正能拉开团队效率的地方是围绕它做一层自己的插件把公司内部的部署检查、代码规范、接口文档、发布流程全部变成模型可以主动调用的技能和命令。这篇文章不讲怎么安装 Claude Code也不会把官方文档翻译一遍。重点是从插件开发者的视角把一个企业级插件的设计、编码、测试、发布链路走通。你会看到三种可落地的扩展形态Skill 技能文件、Slash Command 插件、MCP Server 集成还会拿到一个带配置、鉴权、日志的插件骨架可以直接改造成团队内部工具。如果你正在负责团队的 AI 工具链建设或者刚接触 Claude Code 插件但不知道怎么下手这篇可以收藏。文里的代码以当前社区常见的开发方式为基准具体的 SDK 导出名、权限字段、命令注册格式要以你安装的版本官方文档为准。1. Claude Code 插件体系核心能力速览先给一张规格表快速判断这个插件体系是不是你需要的。能力项说明项目类型命令行 AI 编程工具的扩展机制主要扩展形态Skill、Slash Command 插件、MCP Server、Harness 集成开发语言Markdown 技能文件、Node.js/TypeScript 为主启动方式Claude Code 内置命令加载、市场安装、本地目录加载配置位置.claude/ 目录、package.json、plugin.json、.mcp.json是否支持 API支持可经 MCP 协议或自定义命令接入企业内部服务是否支持批量任务可配合自定义命令和脚本编排批量处理推荐环境最新版 Node.js、Git 仓库、可访问官方模型的 Claude Code 账号适合场景团队编码规范、私有接口集成、发布审核、代码巡检、自动化流水线Claude Code 插件体系的定位不是“做一个好看的前端页面”而是在命令行会话中扩展模型的能力边界。模型本身只会读文件、写文件、执行命令但通过插件你可以让它调用公司内部系统的 API、按团队规范做代码审查、在发布前强制执行检查清单。从社区实践来看插件开发有三个层次最轻量的是 Skill用 Markdown 写行为说明模型在对话中自动发现并使用不需要编译。中间层是 Slash Command 插件用 TypeScript 写命令处理逻辑适合接入外部系统、执行复杂流程。最重的是 MCP Server把企业内部工具以标准化协议暴露给模型适合跨多种 AI 工具复用。这套分层设计的好处是团队里写文档的人可以维护 Skill写业务系统的人可以维护 MCP Server不需要所有人都懂完整插件 SDK。2. 企业级插件使用场景与边界企业级插件不是“写一个命令让 AI 打招呼”而是要解决真实工程问题。比较典型的场景有下面几类。第一类是代码规范落地。默认情况下Claude Code 生成的代码风格不一定符合团队规范。插件可以把 lint 规则、commit message 规范、代码评审点全部写进 Skill让模型在写代码时主动遵守。第二类是私有系统接入。很多公司有内部平台比如工单系统、发布平台、监控告警系统这些系统不可能开放给公共模型。插件可以通过 MCP Server 或命令调用内部 API让 Claude Code 在会话中直接查询工单状态、检查发布单、触发测试任务。第三类是流程管控。比如开发完成后模型要提交 PR但公司要求 PR 描述必须包含关联工单、影响范围、测试记录。插件可以拦截提交动作检查描述是否完整不满足条件就拒绝执行。这类插件本质上把组织流程编码成了工具逻辑价值很高。使用边界也要说清楚。Claude Code 插件运行在你的终端环境里拥有执行命令、读写文件的权限所以插件代码本身必须经过 review。不要随意安装来源不明的插件尤其是不清楚它往哪个服务器发数据的插件。涉及密钥、Token、内部接口地址的配置必须走环境变量或本地配置文件禁止写死在代码里。另外Claude Code 本身是商业产品账号类型和模型访问策略会影响插件功能。社区里有通过环境变量、Harness 插件等方式接入其他模型服务的实践但能不能用、是否违反服务条款需要你自己结合账号情况验证本文不展开讨论。3. 环境准备与前置条件开发 Claude Code 插件前先把本机环境准备好。核心依赖是 Node.js、Git 和 Claude Code 本体不需要 GPU普通办公电脑就能开发和调试。先确认 Node.js 版本。建议使用 Node.js 18 以上版本因为插件和 MCP SDK 都依赖较新的运行时特性。node -v npm -v然后全局安装 Claude Code。如果你已经装过先执行一次升级避免插件 SDK 和主程序版本不匹配。npm install -g anthropic-ai/claude-code安装完成后在终端里执行claude进入交互界面按提示完成登录认证。认证方式通常有两种一是登录 Anthropic 账号二是设置ANTHROPIC_API_KEY环境变量。企业环境里更推荐 API Key 方式便于在 CI 机器上使用。export ANTHROPIC_API_KEY你的 key claude进入交互界面后可以先验证基础能力是否正常比如问一句“当前工作目录是什么”。如果 Claude Code 能正常回复说明认证和网络都没问题。接下来准备一个演示项目。插件开发建议在独立 Git 仓库里进行不要直接塞到公司主业务仓库里否则版本管理和发布都会很乱。mkdir cce-plugin-demo cd cce-plugin-demo git init到这里环境准备就完成了。整个准备过程不需要 GPU不需要额外容器磁盘占用也很小符合本地轻量开发的特征。4. Claude Code 插件扩展点与基础安装在动手写代码前先理解 Claude Code 的插件加载机制。插件本质上是给 Claude Code 增加新的“能力单元”加载之后模型在合适的时机就会使用这些能力。Claude Code 常见的插件安装入口是交互界面的/plugin命令。你可以通过它查看当前已安装的插件、添加插件市场、安装特定插件。插件市场可以理解为远程索引配置好后团队执行一条命令就能安装统一的内部插件集合。如果你还没配置市场也可以直接从本地目录加载插件这对开发调试最方便。本地插件目录通常是项目下的.claude/文件夹。比如你的插件叫enterprise-tools可以放在.claude/plugins/下面也可以直接用独立仓库加载。开发阶段我建议先把插件放在独立仓库里用本地路径调试。查看当前插件状态在 Claude Code 交互界面执行/plugin如果你的 Claude Code 版本支持市场功能可以用类似下面的方式添加内部插件市场/plugin marketplace add 团队内部市场地址 /plugin install 插件名如果你的版本不支持市场命令不用着急直接走本地目录加载。还有一类插件是通过文件约定自动发现的最常见的就是 Skill。只要在.claude/skills/目录下放符合格式的SKILL.md文件Claude Code 启动后会自动识别不需要额外注册。理解了这个机制下面就可以按三种形态逐个开发了。5. 开发第一种插件形态SkillSkill 是 Claude Code 插件体系里最轻量、最容易上手的一种。它不需要编译不需要写代码本质上是一份结构化的 Markdown 说明书。模型在对话中读到用户需求后会根据 description 判断当前情况是否匹配某个 Skill匹配就自动执行其中描述的步骤。先创建一个技能目录。在项目根目录下建立.claude/ skills/ code-review/ SKILL.mdSKILL.md的前面部分叫 frontmatter用来描述技能的名称和作用。这段描述非常关键模型靠它判断什么时候激活技能写得太模糊会导致该触发时不触发写得太宽泛会导致不该触发时乱触发。--- name: code-review description: 在提交 PR 前对指定目录执行代码审查重点关注安全漏洞、错误处理和性能问题。当用户要求 review、审查代码或提交 PR 前检查时使用。 --- # 代码审查技能 当用户要求进行代码审查时执行以下步骤 1. 使用 Read 工具读取目标目录下的主要源码文件。 2. 检查是否存在硬编码密钥、SQL 注入、危险反序列化等问题。 3. 检查错误处理是否完整是否有过度吞异常或直接泄漏内部堆栈的情况。 4. 检查是否有明显性能问题例如循环内执行网络请求。 5. 按严重程度输出问题清单每个问题给出文件路径、行号和修改建议。这份文件写好后在项目根目录启动 Claude Code输入“帮我 review 一下 src 目录”模型就会自动发现code-review技能并按照里面的步骤去执行。从企业落地角度看Skill 最适合沉淀“知道但容易忘”的过程知识。比如公司规定上线前必须检查环境变量是否齐全、数据库迁移脚本是否有回滚方案这类规则写成 Skill 后模型每次上线前都会主动检查。相比写文档这种方式对开发流程的约束力强得多因为它和实际编码动作绑定在一起。Skill 的缺陷也很明显它没有代码逻辑不能真正调用外部 API不能读写配置文件只能通过 Claude Code 自带的工具能力去完成流程。所以一旦涉及外部系统交互就需要上第二种形态。6. 开发第二种插件形态Slash Command 插件Slash Command 插件是真正意义上的代码插件。它通常是 Node.js/TypeScript 项目通过package.json里的claudeCode字段声明命令命令处理函数在 Claude Code 会话中被调用时执行。先初始化项目npm init -y npm install anthropic-ai/claude-code然后修改package.json声明一个/review命令。这里注意不同版本 Clude Code 对命令声明格式可能有调整以下写法是社区通行的骨架实际开发对照当前版本文档核对字段名。{ name: enterprise-review, version: 1.0.0, type: module, main: dist/index.js, engines: { node: 18 }, claudeCode: { commands: { review: { description: 触发企业级代码审查流水线, args: [ { name: scope, required: false } ], permissions: [ Read, Bash(npm run lint) ] } } } }接着写命令处理逻辑。命令函数会接收参数和上下文对象上下文里通常包含日志、文件读写、工具调用等能力。下面是一段通用骨架重点不是具体 API而是理解结构。export const reviewCommand async (args: string[], context: any) { const scope args[0] ?? .; context.log(review scope: ${scope}); try { // 你的业务逻辑读取配置、调用内部 API、执行检查脚本 const config context.readConfig(review.config.json); const result await runReviewPipeline(scope, config); return { type: text, content: 代码审查完成发现 ${result.issues.length} 个问题, }; } catch (error) { context.log(String(error)); return { type: text, content: 代码审查失败${(error as Error).message}, }; } };在 Claude Code 中安装并触发这个命令后模型会直接调用你的函数而不会自己在对话里“猜测”审查流程。这就保证了结果可控、可审计是企业内部工具链必须的特性。相比 SkillSlash Command 插件能做更重的事情读取配置文件、调用内部 API、执行本地脚本、返回结构化结果。但它需要模型主动调用不会像 Skill 那样自动触发。所以一个完整的企业插件通常会用 Skill 定义流程规范用 Command 实现真正的业务动作。7. 开发第三种插件形态MCP Server 集成MCP 是 Model Context Protocol 的缩写是目前 AI 工具接入外部数据和服务的主流标准。Claude Code 支持 MCP Server意味着你可以把企业内部系统封装成标准化工具然后让模型在对话中直接调用。MCP Server 的优势在于标准化。同样的一个内部接口封装成 MCP 后Claude Code 可以用其他支持 MCP 的 AI 工具理论上也能复用。这让插件开发不再局限于某一个编辑器或某一种 CLI。先安装 MCP SDKnpm install modelcontextprotocol/sdk然后写一个最小 Server。这里用StdioServerTransport意思是 Claude Code 通过标准输入输出和这个 Server 通信不需要额外开端口安全边界更清晰。import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; const server new McpServer({ name: internal-ops, version: 1.0.0, }); server.tool( check_incident, { incidentId: z.string() }, async ({ incidentId }) { // 这里替换成企业内部系统 API 调用 const data await fetchInternalApi(/incidents/${incidentId}); return { content: [{ type: text, text: JSON.stringify(data) }], }; } ); const transport new StdioServerTransport(); await server.connect(transport);写好 Server 代码后把它编译运行再把 MCP 配置告诉 Claude Code。常见方式是在项目根目录放一个.mcp.json或者通过claude mcp add命令添加。配置内容大致包含 Server 名称、启动命令和传输方式。{ mcpServers: { internal-ops: { command: node, args: [dist/server.js], env: { INTERNAL_API_BASE: https://ops.example.internal } } } }启动 Claude Code 后模型会自动发现internal-ops里的工具。当用户问“查一下工单 INC-2024-001 的状态”模型就会调用check_incident把内部系统的返回值组织成回答。在开发 MCP Server 时要注意环境变量注入。不要把内部 API 的密钥写进.mcp.json并提交到 Git 仓库建议通过环境变量或本地 gitignore 文件管理。8. 企业级插件核心设计配置、鉴权与日志三种插件形态都能跑通后接下来要解决企业落地的三件套配置管理、鉴权认证、日志审计。这不是功能点是上了生产环境必须做的事。配置管理上建议插件统一从一个本地配置文件读取参数而不是散落在代码里。比如review.config.json负责定义审查范围、忽略目录、规则开关。这样运维人员不需要改代码只改配置就能调整插件行为。{ review: { ignores: [dist, node_modules, vendor], maxFileSize: 512, rules: { checkSecrets: true, checkErrorHandling: true, checkPerformance: false } } }鉴权的核心原则是插件不保存密钥密钥全部从环境变量读取。以 Node.js 为例统一封装一个 getSecret 函数。export function getSecret(name: string): string { const value process.env[name]; if (!value) { throw new Error(Missing required environment variable: ${name}); } return value; }调用内部 API 时只在这里获取 Token不要手写字符串。日志审计在企业场景里很重要。插件被谁调用、调用时传了什么参数、返回了什么结果都需要记录。这样一旦出现异常操作或安全事件才能追溯。日志建议输出到单独目录同时注意脱敏不要把 Token、密码、用户敏感信息直接打进日志。export function writeAuditLog(entry: Recordstring, unknown): void { const sanitized sanitizeLog(entry); const line ${new Date().toISOString()} ${JSON.stringify(sanitized)}; // 写入企业统一的日志目录 }从工程经验看配置、鉴权、日志这三件事最好在第一个插件阶段就做好不要等插件数量多了再补。否则每个插件各写一套后面统一治理的成本会很高。9. 插件测试与调试插件不是写完就算完要验证在 Claude Code 里能稳定触发、正确执行、优雅报错。调试可以从三个层面试。第一层是单元测试。把插件的核心逻辑抽成纯函数用 Node.js 自带测试框架或 vitest 覆盖正常路径和异常路径。比如审查脚本输入一个含硬编码密钥的文件应该返回一个高危问题输入一个正常文件应该返回“无问题”。npm run test第二层是手动触发。在 Claude Code 交互界面直接输入/review观察日志输出和命令返回。这里重点看两个东西一是命令是否被正确识别二是参数传递是否符合预期。如果命令没被识别检查claudeCode字段声明是否被正确加载插件是否安装成功。第三层是权限与失败模拟。故意给插件传一个不存在的目录或者把内部 API 地址改成一定会超时的地址观察插件会不会崩溃、会不会把堆栈信息直接抛给用户。企业级插件应该捕获异常并返回可读信息而不是让模型拿到一串堆栈去猜。调试时如果 Claude Code 出现异常日志可以打开主程序的日志目录查看。不同版本的日志路径不一样常见的位置在用户主目录下的.claude文件夹里。关注LastError和插件加载相关日志能定位大多数问题。10. 插件的发布与团队共享插件在本地跑通后要交给团队使用就会涉及发布和分发问题。Claude Code 插件的分发主要有三种方式。第一种是私有 npm 包。把插件打包发布到公司私有 npm 仓库团队通过 npm 安装后加载。这种方式适合有统一 Node.js 基础设施的团队安装简单依赖管理清晰。第二种是 Git 仓库分发。插件代码放在 Git 仓库里团队成员 clone 下来后用本地路径或file:协议安装。这种方式不需要维护 npm 包但每次更新需要手动拉取适合小团队快速迭代。第三种是插件市场。如果你的 Claude Code 版本支持 marketplace 功能可以维护一个内部插件市场索引团队成员一条命令就能安装、更新、卸载插件。这是最接近企业级体验的方式也是插件数量多后的推荐方式。不管用哪种方式分发都要做版本管理。插件接口可能跟随 Claude Code 版本升级而变化所以建议在插件的package.json里标注兼容的最低版本并在更新日志里说明破坏性变更。发布前还要做一次代码安全检查。重点看插件有没有外发数据、有没有读取用户主目录敏感文件、有没有在不必要的情况下申请过多权限。插件在 AI 工具里的权限模型通常支持按命令声明权限尽量保持最小可用。11. 常见问题与排查方法下面是 Claude Code 插件开发和使用中比较常见的问题按现象、原因、排查方式、解决方案整理。问题现象可能原因排查方式解决方案插件命令没有被识别claudeCode 字段格式错误或插件未正确加载执行 /plugin 查看已加载插件核对 package.json 声明按文档修正字段Skill 没有被自动触发frontmatter 的 description 写得太模糊或太宽泛在对话中明确描述使用意图测试重写 description加入触发场景关键词安装插件时报依赖版本错误Node 版本过低或 SDK 版本不匹配执行 node -v 检查 Node 版本升级 Node 到 18 以上更新依赖调用内部 API 鉴权失败环境变量未注入或 Token 过期检查进程环境变量和日志重新设置环境变量更新 Token 来源MCP Server 启动失败stdio 传输模式下启动命令写错手动执行启动命令看报错信息修正 command 和 args 配置模型执行插件时总是绕开命令模型没有意识到应该调用该命令在 Skill 里明确写出调用时机结合 Skill 和 Command让流程自动衔接插件中文路径或文件名乱码终端编码不统一检查系统 locale 和终端编码统一使用 UTF-8 编码启动 Claude Code插件日志包含敏感信息日志没有做脱敏处理检查 writeAuditLog 实现对日志字段做过滤和掩码遇到问题时最有效的定位方式是先看日志。如果日志没有输出先确认插件是否真的被执行如果日志有异常把异常信息和触发命令一起记录下来再去查对应版本的 SDK 文档。12. 最佳实践与后续方向最后给几条工程化建议这些是实际落地时容易踩坑的地方。第一插件目录和配置要纳入 Git 管理但密钥文件必须 gitignore。建议在仓库里放一份.env.example模板团队成员复制成自己的.env后填入真实配置。第二第一次开发时不要贪多先做一个最小 Skill 跑通流程再做一个 Command 接一条内部 API最后再上 MCP。这样每一层的问题都能单独定位不会混合在一起无从下手。第三命令权限要最小化。插件只申请它真正需要的工具权限比如Read、Bash(npm run lint)不要给一个Bash(*)了事。权限越大模型误操作时的破坏面越大。第四模型行为不稳定时优先改进 Skill 的 description 和步骤描述不要靠“多写几句话”碰运气。Skill 的质量决定了插件在大模型里能不能被稳定触发。第五把插件使用数据记录下来定期分析哪些命令没被调用、哪些 Skill 频繁触发。这些数据能帮你判断插件是不是真的有用而不是写完入库就吃灰。Claude Code 插件开发的方向还有很多可以深入比如 Harness 集成、事件钩子、插件 UI 等。但从企业落地角度看先把 Skill、Command、MCP 三条线跑通配合好配置、鉴权和日志就已经能覆盖大部分研发流程改造场景。建议从自己团队最痛的一个环节开始比如“提交 PR 前的规范检查”做第一个试点插件跑通后就能形成规范再逐步扩展。