如何构建 Claude Code 插件：分步指南

Claude Code 开箱即可处理大多数开发任务，但每个团队都有默认设置无法覆盖的特定工作流。您可能需要一个自定义命令，以公司偏好的结构搭建组件；或在每次提交前自动执行 Lint；或快速访问您经常使用的框架文档。

Claude Code 插件让您自行添加这些功能。您可以安装社区构建的插件，也可以创建自己的插件。

如果您刚接触 Anthropic 的代理型编程工具，建议先阅读 Claude Code 指南或Claude 模型入门课程。本教程假设您已安装 Claude Code 并用于基础任务。

完成后，您将学会：

• 从 Anthropic 目录与社区源查找并安装插件
• 理解插件可包含的三类组件
• 为不同用例选择正确类型
• 构建并分享您自己的插件

想了解 Anthropic 最新模型的能力概览，请参阅我们关于 Claude Sonnet 5 的指南。

要点速览

• Claude Code 插件将 skills、MCP 服务器与 hooks 打包为可共享的安装包，使用 claude plugin add 安装

• Skills 按需加载（每个约 100 个 token）；MCP 服务器预加载工具定义（已由 Tool Search 降低）；hooks 以 shell 脚本运行，零 token 成本

• 技能用于知识与工作流；MCP 服务器用于访问外部 API；hooks 用于必须每次都触发的规则

• 用三个文件构建插件：.claude-plugin/plugin.json 清单、一个 skills/ 目录，以及一份 SKILL.md 指令文件

Claude Code 插件是什么？

插件是一个打包单元，将一个或多个 Claude Code 扩展捆绑在一起，便于共享与安装。与其在机器或队友之间手动复制配置文件，不如将一切封装成插件并作为单个单元分发。

插件可包含三种组件：

• Skills：可用 /skill-name 调用的自定义命令，或在相关时由 Claude 自动使用的上下文感知提示

• MCP 服务器：连接外部服务与 API，让 Claude 访问其原本无法获取的数据

• Hooks：在特定事件上自动运行的 shell 脚本，例如文件编辑前或提交后

插件可以只包含其中一种，也可以组合多种协同工作。一个“部署”插件可以包含用于手动部署的 /deploy 技能、一个检查预发布环境状态的 MCP 服务器，以及在任何部署命令执行前运行测试的 hook。

plugin.json 清单文件定义插件的内容。它指定要安装的 skills、MCP 服务器与 hooks，并包含插件名称、版本与作者等元数据。安装插件时，Claude Code 会读取该清单并将各组件放在正确位置。

这种打包格式意味着您无需理解 Claude Code 扩展的内部文件结构。安装插件后，一切都会落到该去的地方。

查找与安装 Claude Code 插件

大多数插件位于以下两处之一。Anthropic 的官方目录 claude.com/plugins 收录了由 Anthropic 构建的插件、已验证的社区贡献以及流行的第三方扩展。每个条目都会展示插件所含组件、兼容性信息与安装说明。

第二个来源是 GitHub：

找到想要的插件后，安装命令取决于其来源：

# From the official directory
claude plugin add @anthropic/deploy-helper
 
# From a GitHub repository
claude plugin add github:username/repo-name
 
# From a local directory (useful during development)
claude plugin add ./my-plugin

安装了几个插件后，您可能需要管理它们。plugin 命令可用于列出、更新和移除：

# List all installed plugins
claude plugin list
 
# Update a specific plugin to the latest version
claude plugin update @anthropic/deploy-helper
 
# Update all plugins
claude plugin update --all
 
# Remove a plugin
claude plugin remove @anthropic/deploy-helper

安装时您需要做的一个决定是作用域。插件可安装在两处：用户级安装到 ~/.claude/plugins/，适用于所有项目；项目级安装到特定仓库内的 .claude/plugins/。

默认是用户级。若仅为当前项目安装，请添加 --project 标志：

claude plugin add @anthropic/deploy-helper --project

当扩展与某个特定代码库强绑定时，项目级插件更合适。

了解公司部署流程的插件应该放在该项目中；而根据您个人偏好格式化代码的插件应安装在用户级。当同一插件同时存在于两个作用域时，项目级版本具有更高优先级，使团队可以在项目中强制执行特定配置，同时开发者在其他地方仍可保留个人插件生效。

选择合适的 Claude Code 插件类型

三种组件类型服务于不同目的，并以不同方式消耗上下文窗口的 tokens。理解这些取舍有助于为每项任务选择合适的类型。

Skills 与 MCP 服务器：token 取舍

MCP 服务器会在会话开始时预加载每个工具定义到上下文窗口。每个工具都需要名称、描述和完整的参数模式，通常每个工具消耗 100–300 个 token。一个包含五个服务器的设置，在您还未输入任何字符前，大约会消耗 55,000 个 token：

• GitHub：35 个工具
•  Slack：11 个工具
• Sentry：5 个工具
• Grafana：5 个工具
• Splunk：2 个工具

有分析发现包含 7 个以上服务器的设置会消耗 67,000+ 个 token，这意味着在对话开始前，您的 200K 上下文窗口已有三分之一被占用。

Skills 采用渐进披露的不同方式。在会话开始时，Claude 只会看到每个技能在 YAML frontmatter 中的一行名称与描述，每个技能约 100 个 token。

只有当 Claude 判断该技能与当前任务相关时，才会加载完整指令。引用文件仅在明确需要时才会加载。而脚本完全不会进入上下文窗口；Claude 在外部运行它们，仅返回输出结果。

Anthropic 在 2025 年底通过 Tool Search 功能解决了这一失衡问题。

Claude Code 不再预加载所有工具定义，而是在检测到工具描述会消耗超过可用上下文的 10% 时，切换为按需加载。

内部测试显示，对于大型工具库，上下文占用从约 134,000 个 token 降至约 5,000 个。工具选择准确率也有所提升：Opus 4 在 MCP 评测中的准确率从 49% 跃升至 74%，Opus 4.5 则从 79.5% 提升至 88.1%。

以下是二者的选择方法。

当您希望 Claude 能以判断力获取并应用知识或工作流时，Skills 最合适。比如描述团队代码审查清单的技能会在 Claude 审查代码时加载，但如何根据上下文应用每一项，仍由 Claude 决定。

对于需要脚本进行重计算的操作，Skills 也很合适，因为脚本代码保持在上下文窗口之外。

当 Claude 需要来自外部服务的实时数据（如 Slack 消息、GitHub PR 或数据库查询）时，MCP 服务器更合适。当多名 AI 代理需要使用同一组工具，或需要审计日志与显式权限等企业特性时，也应选择 MCP。

许多设置会同时使用两者：Skills 通过自然语言指令提供“如何做”和“何时做”，而 MCP 服务器负责实际的 API 调用。

值得安装的热门 Claude Code 技能

• Superpowers（我们的教程）：覆盖 TDD、调试、结构化规划的 20+ 生产验证工作流
• frontend-design：指导 Claude 避免千篇一律的审美，并做出大胆设计决策
• mcp-builder：创建 MCP 服务器以集成外部 API 的指南
•  webapp-testing：使用 Playwright 对本地 Web 应用进行 UI 验证测试
•  skill-creator：引导您交互式构建新技能的工具

值得连接的热门 MCP 服务器

• Context7：实时的特定版本文档查询
• GitHub：仓库搜索、PR 管理、Issue 跟踪
• Playwright：使用可访问性树而非截图进行浏览器自动化
• Supabase：具备行级安全（RLS）感知的数据库查询
• Sentry：在编辑器中直接进行错误跟踪与性能监控

您还可以阅读我们的 热门远程 MCP 服务器 指南。

Hooks：确定性层

Hooks 完全置身于 Skills 与 MCP 的讨论之外。Skills 和 MCP 服务器都面向 Claude（何时使用由 Claude 决定），而 Hooks 则面向系统。它们会在 PreToolUse 或 PostToolUse 等事件上触发，在 Claude 执行特定操作前后运行 shell 脚本。是否运行 Hook 不由 Claude 决定。

这使得 Hooks 成为必须无一例外发生之事的正确选择：每次提交前进行 Lint、阻止写入受保护目录、记录每条 bash 命令，或在任何部署前运行测试。

这位开发者推荐使用“提交时阻止”（block-at-submit）hooks 而非“写入时阻止”（block-at-write）hooks。在任务中途阻止 Claude 会让代理困惑，导致更差的结果。她的团队使用一个 PreToolUse hook 包装 Bash(git commit)，并检查仅在测试通过时才会存在的临时文件。没有该文件就不允许提交。代理先完成工作，最后再进行验证。

Hooks 不带来任何 token 开销，因为它们作为 shell 脚本在上下文窗口外运行。

值得设置的实用 Claude hooks

• 编辑时 ESLint/Prettier：在 Claude 写入文件后自动格式化
• 提交测试门禁：测试未通过则阻止提交
• 受保护路径：禁止写入迁移、配置或 vendor 目录
• 完成通知：长任务完成时发送 Slack 或桌面提醒
• 记录备份：在压缩运行前保存会话历史

如何构建自己的 Claude Code 插件

当某个技能位于您个人的 .claude/ 目录时，只有您能使用它。将其打包为插件后，便可与队友共享或跨项目复用。

我们将构建一个名为 session-logger 的插件，添加一个 /session-logger:summarize 命令。调用后，Claude 会回顾对话并将结构化摘要追加到 SESSION_LOG.md。

创建插件结构

插件可以位于文件系统的任何位置。本教程中，我们将在您的主目录创建一个：

cd ~
mkdir -p session-logger/.claude-plugin
mkdir -p session-logger/skills/summarize

这将创建：

~/session-logger/
├── .claude-plugin/
│   └── plugin.json  	# manifest goes here, nowhere else
└── skills/
	└── summarize/   	# folder name becomes the command name
    	└── SKILL.md 	# must be named exactly this

编写清单

创建 ~/session-logger/.claude-plugin/plugin.json：

{
  "name": "session-logger",
  "description": "Log session summaries to a markdown file",
  "version": "1.0.0"
}

name 字段会成为命名空间前缀。该插件内所有命令都将以 /session-logger: 开头。

编写技能

创建 ~/session-logger/skills/summarize/SKILL.md：

---
description: Log a summary of the current session to SESSION_LOG.md
disable-model-invocation: true
---
 
When invoked, review the conversation and create a summary with these sections:
 
- **Date/time**: Current timestamp
- **Tasks completed**: What was accomplished
- **Files modified**: List of files created or changed
- **Decisions made**: Architectural or implementation choices
- **Open questions**: Unresolved items for future sessions
 
Append the summary to SESSION_LOG.md in the project root. Create the file if it doesn't exist.

disable-model-invocation: true 行告知 Claude 只有您可以触发该技能。没有该标志，若 Claude 认为有助于对话，它可能会自主决定运行该命令。对于日志或部署类工具，通常需要手动控制。

本地测试

导航到任一您想使用该插件的项目，然后以指向插件的 --plugin-dir 标志启动 Claude Code：

cd ~/your-project
claude --plugin-dir ~/session-logger

输入 /session-logger:summarize 调用命令。请注意，在您键入完整名称之前，插件命令不会出现在自动补全建议中。一旦 Claude Code 识别为有效命令，文本会变为蓝色。

在会话中做完一些工作后，运行该命令。Claude 会回顾对话并在当前项目目录的 SESSION_LOG.md 中追加一条记录。

与他人分享

将插件推送到 GitHub。要在手动克隆之外进行分发，请将其添加到插件市场。该 市场指南涵盖如何创建您自己的市场或提交到现有市场。

结语

插件让 Claude Code 从通用助手变成贴合您特定工作流的工具。我们构建的会话日志器仅花了约五分钟和三个文件。大多数实用插件并不会比这复杂多少。

如果您跟着完成了，现在您的机器上已有一个可用的插件。试着微调它：更改摘要格式、添加新部分，或将其替换为团队真正需要的东西。无论是构建一个快捷的个人工具，还是要分发给数百名开发者，结构都保持不变。

另外，有空时也浏览一下社区仓库。看看他人如何组织插件，能学到文档里没有的范式。

想更深入了解 Claude Code，请查看我们关于Claude Code 最佳实践、Superpowers 技能框架、适用于长会话的斜杠命令，以及安全与权限的教程。若您想进一步了解 Claude 模型，推荐 Introduction to Claude Models 课程。