Claude Code 插件是什么？功能解析与费用说明

什么是 Claude Code 插件

Claude Code 插件是一个包含多个组件的目录，由 Claude Code 作为一个整体进行加载和管理。这些组件包括技能 (skills)、代理 (agents)、钩子 (hooks)、MCP 服务器、LSP 服务器以及后台监控程序。安装插件会一次性添加其所有组成部分，并统一命名；禁用插件则会以相同方式将其移除。

插件不会赋予代理任何其原本不具备的能力。插件内部的每一个部分，你都可以手动在 .claude/ 目录中编写。插件本质上是一个封装层：它提供了一种对这些组件进行版本控制的方法，方便将其分发给 15 个人使用，并在后续进行更新，而无需让每个人手动复制文件。这就是插件的核心理念，关于插件的大多数困惑都源于将其误认为是某种新型功能。

位于 .claude-plugin/plugin.json 的可选清单文件用于命名插件，该名称将成为一个命名空间。名为 commit-commands 的插件中的技能，其调用方式为 /commit-commands:commit，因此两个插件可以各自发布名为 commit 的技能，而不会发生命名冲突。插件代理在 @-mention 列表中的作用域也以相同方式处理，即 plugin-name:agent-name。

插件、技能、MCP 服务器或规则文件

这四个术语常被混用，但它们并不冲突，有必要明确其界限。

• 技能是 Claude 在任务需要时加载的一个指令单元。参见 什么是 Agent 技能。
• MCP 服务器是一个独立进程，通过协议向 Agent 提供工具，通常是你自行运行的网络服务。
• 规则文件（如 CLAUDE.md）是项目上下文，在会话开始时读取并应用于所有内容。
• 插件是一个容器，可以整合技能、Agent、钩子和 MCP 服务器定义，并包含版本号和分发渠道。

因此，插件要回答的问题不是“Agent 能做什么”，而是“我如何将其分发给团队并在下个月更新”。如果你是在前三者之间做选择，技能、MCP 服务器与规则文件的对比 详细涵盖了该决策。如果你关注的是 MCP 部分，在 VPS 上运行自己的 MCP 服务器 涵盖了托管方面的内容。

插件的存储位置及其内部结构

从市场安装的插件会被复制到 ~/.claude/plugins/cache 的本地缓存中，而不是直接从克隆位置运行。每个已安装的版本都有其独立的目录。当你更新或卸载插件时，旧版本的目录会被标记为孤立状态，并在约两周后删除。这样，正在运行且已加载旧版本的会话可以继续工作，而不会在任务执行中途失败。

由于路径在每次更新时都会改变，插件绝不能硬编码其自身位置。插件内部的钩子（Hooks）和 MCP 配置使用 ${CLAUDE_PLUGIN_ROOT}，它会自动解析为当前的安装目录。必须在更新后保留的状态数据应存放在 ${CLAUDE_PLUGIN_DATA} 中，该路径会解析为 ~/.claude/plugins/data/ 下的一个稳定目录。

只有插件自身的目录会被复制到缓存中，这会导致一个常见的后期问题。指向插件根目录之外的路径（例如 ../shared-utils）在本地开发时可以正常工作，但在安装后会失效，因为这些文件从未被复制过去。

目录结构如下所示。

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

只有 plugin.json 应该放在 .claude-plugin/ 内部。其他所有内容都位于插件根目录下。将 skills/ 或 hooks/ 放入 .claude-plugin/ 是导致插件安装成功却无法运行的最常见原因：Claude Code 会在根目录下查找这些目录，如果找不到，加载的插件将不包含任何组件。

清单文件本身很小。

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0"
}

How to install a Claude Code plugin

Installing is two steps, and the first one installs nothing. You add a marketplace, which is a catalog of plugins, then you install individual plugins from it. Anthropic's official marketplace, claude-plugins-official, is registered for you the first time you start Claude Code interactively. Others you add yourself.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

Note that the repository is anthropics/claude-code while the marketplace is named claude-code-plugins. The name comes from the catalog file inside the repository, not from the repository path, so read the marketplace name off the Marketplaces tab of /plugin before you type an install command.

After the install, read the summary line. Plugin is now active. means the components are loaded in this session. Run /reload-plugins to activate. means they are not, and you need to run that command. If /reload-plugins warns that it would re-read the conversation, rerun it as /reload-plugins --force. Then confirm the plugin is really there: /plugin shows it under the Installed tab, /help lists its skills under Custom commands, and anything that failed to load shows up under the Errors tab with the reason.

Installing asks for a scope, and the scope decides who gets the plugin. User scope is you, in every project. Project scope writes the plugin into the repository's .claude/settings.json under enabledPlugins, so everyone who clones the repository is offered it. Local scope is you, in this repository only.

For a script, a Dockerfile, or any session where an interactive panel is not available, use the shell form instead. It installs to user scope unless you pass --scope.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

claude plugin install runs outside a session, so a session that is already open will not see the new plugin until you run /reload-plugins or start a new session.

Managing what you have is the same pattern in both places. /plugin list prints what is installed, and accepts --enabled or --disabled. /plugin disable name@marketplace turns a plugin off without removing it, /plugin enable turns it back on, and /plugin uninstall removes it. The slash-command forms open the plugin panel to apply the change, which is why the claude plugin ... shell equivalents are the ones to use in scripts.

To hand a marketplace to a whole team, put it in the project's .claude/settings.json. Members are prompted to install it once they trust the repository folder.

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

While you are building your own plugin, skip the marketplace entirely. claude --plugin-dir ./my-plugin loads a directory for that session, /reload-plugins picks up your edits without a restart, and claude plugin validate ./my-plugin checks the manifest, the skill and agent frontmatter, and hooks/hooks.json before anyone else sees it.

Claude Code 插件的费用是多少？

该机制本身是免费的。截至 2026 年 8 月，添加市场、安装插件或保持插件启用均不收取任何费用。官方和社区市场均为公开的 git 仓库，插件本质上只是一个包含文本文件的目录。

插件的实际成本在于 token，而 token 正是订阅用量或 API 账单的计量单位。该成本通过以下三种方式产生，且表现各异。

常驻上下文成本。 插件贡献的内容会进入上下文，并在会话的每一轮对话中被重新读取。安装前，/plugin 详情视图会显示 Context cost 的 token 预估值，以及 Will install 部分，其中列出了即将添加的命令、技能、代理、钩子（hook）以及 MCP 和 LSP 服务器。请务必阅读这两项。来自本地或自定义市场的插件可能不会提供这些数据，此时需要手动估算。捆绑了 MCP 服务器的插件通常最占资源，因为工具定义非常大；但在支持 MCP 工具搜索的模型上，这些定义会延迟加载，直到真正需要使用工具时才会调用。

调用成本。 运行插件的技能会将指令追加到对话中，因此仅在调用技能主体时才会产生费用。代理则不同。子代理会开启独立的对话，拥有自己的系统提示词（system prompt）和缓存，且初始时没有任何缓存命中。因此，工作流会生成代理的插件，其成本远高于上下文预估值。

缓存成本。 在会话中途启用或禁用插件，可能会强制下一次请求重新处理整个对话。技能、命令、代理、钩子、LSP 服务器、监控器和主题不会导致此问题：它们添加的内容会追加在现有历史记录之后，因此下一次请求只需为新内容付费，而之前的内容仍可从缓存中读取。唯一的例外是提供 MCP 服务器的插件。如果其工具通过工具搜索延迟加载，缓存将保持有效。如果它们加载到提示词前缀中，下一次请求将把整个对话作为未缓存的输入重新读取。这正是 /reload-plugins 在该情况下发出警告并拒绝操作，直到您通过 --force 确认的原因。

您可以监控这些指标，无需盲目猜测。每个 API 响应都会报告 cache_read_input_tokens 和 cache_creation_input_tokens，通过 显示实时 token 用量的自定义状态栏，您可以直接查看这两项数据。健康的会话读取量远大于创建量。如果创建量在每一轮对话中持续居高不下，说明您的前缀中存在每一轮都在变动的内容。若要全面了解是什么占用了窗口，请参阅 如何管理 Claude Code 上下文窗口 和 这些 token 计数的实际含义。

有一项清理工作可以为您节省开支。Installed 选项卡会将您至少两周未使用的插件归类到 Not used recently 标题下，并在详情视图中显示 Last used 行。这些插件在每次会话中仍会消耗启动时间和上下文资源。请禁用或卸载它们。

插件以您的权限运行

Anthropic 的官方文档对此直言不讳：插件和市场组件属于高度受信任的组件，它们可以在您的机器上以您的用户权限执行任意代码。这并非假设。插件的钩子（hooks）会在会话事件中运行 Shell 命令，包括工具调用前后。当插件启用时，其 bin/ 目录会被添加到 Bash 工具的 PATH 中。其 MCP 服务器是由插件启动的进程。在此环境下，没有任何内容与您的用户账户隔离。

在笔记本电脑上，这种风险仅限于桌面用户可访问的范围。但在服务器上通常并非如此。运行代理的账户往往持有 SSH 密钥、部署令牌、云 CLI 会话以及 Docker 套接字的访问权限，因此“以您的用户身份执行任意代码”意味着控制整台机器。如果 Claude Code 在 VPS 上运行，请在安装任何内容前阅读 如何在 VPS 上安全运行 Claude Code，并在安装与外部服务通信的插件前阅读 如何防止代理获取凭据。

目前确实存在一些防护措施，了解这些措施很有帮助。项目级插件源自代码仓库而非您个人，因此只有在您信任该工作区后才会加载；其 MCP 服务器仍需逐个服务器进行批准；其 LSP 服务器会等待该信任确认；且其后台监控程序不会加载。插件自带的代理不允许声明钩子、MCP 服务器或权限模式。市场插件会被复制到缓存中，且指向市场外部的符号链接会被跳过，因此插件无法拉取主机上的任意文件。

这些措施都无法替代对安装内容的审核。请检查 Will install 列表，优先选择源代码可查看和阅读的插件，将团队使用的插件保存在您可控的市场仓库中，并对您自己编写的任何内容运行 claude plugin validate。

FAQ

Claude Code 插件需要额外付费吗？

不需要。插件系统、插件市场或安装插件均不收取费用。费用仅为 Token 使用量，将根据您的套餐或 API 额度进行结算，与任何其他上下文请求一致。插件会在每一轮对话中增加常驻上下文，调用其技能或代理时会增加更多消耗；如果插件提供的 MCP 服务器将其工具加载到提示词前缀中，还可能强制产生一次昂贵的未缓存请求。在安装前，/plugin 详细视图会显示 Context cost 预估费用。

插件和技能有什么区别？

技能是单一的指令单元。插件是一个软件包，可以包含技能、代理、钩子 (hooks)、MCP 服务器、LSP 服务器和监控器，并具有名称、版本和安装来源市场。当技能仅供您个人或当前项目使用时，请在 .claude/ 中编写独立技能。单一用途的技能（例如 Ponytail，它会促使代理采取最小可行性变更）是此类情况的典型示例：在您的团队也需要它之前，它只是一个包含一条规则的文件。当其他人需要使用该技能，且需要对其进行长期维护时，请将其转换为插件。插件中的技能具有命名空间，因此插件内的技能调用方式为 /plugin-name:skill-name，而非 /skill-name。

我的插件已安装，但其中的技能未显示，是哪里出了问题？

首先检查安装摘要。如果显示 Run /reload-plugins to activate.，说明组件尚未加载；如果重载提示将重新读取对话，请以 /reload-plugins --force 方式重新运行。如果已加载但未显示任何内容，请打开 /plugin 并查看 Errors 选项卡。最常见的结构错误是将 skills/、agents/ 或 hooks/ 放置在 .claude-plugin/ 内部，Claude Code 不会扫描该位置。请记住，插件技能具有命名空间，因此您需要在 /help 的 Custom commands 选项卡中查找 /plugin-name:skill-name。作为最后手段，请执行 rm -rf ~/.claude/plugins/cache、重启并重新安装。

我可以在没有交互式面板的情况下安装插件吗？

可以。请使用 shell 命令 claude plugin install name@marketplace，除非您传入 --scope project 或 --scope local 参数，否则它将安装到用户作用域。该命令适用于脚本、镜像以及无法使用 /plugin 面板的非交互式环境。由于它在会话外运行，已打开的会话需要执行 /reload-plugins 才能使插件生效。

安装从 GitHub 上找到的插件市场中的插件安全吗？

请将其视为以您的身份运行该存储库的安装脚本，因为其实际操作与之非常接近。插件可以通过钩子运行 shell 命令、将可执行文件添加到 Bash 工具的 PATH 中，并启动 MCP 服务器，所有操作均拥有您的用户权限。Anthropic 不控制或验证第三方插件的内容。请仅从您可以阅读源码的来源安装，在确认前检查 Will install 列表，并且在服务器上比在笔记本电脑上更要严格，因为服务器上的账户通常持有具有高价值的密钥和 Token。