Claude Code 的插件系统上线已经有一阵了。仔细阅读文档后会发现，它解决的问题比表面看起来更根本：Claude Code 的配置一直散落在 .claude/ 目录里，难以分享、难以版本化、也难以审核。插件系统把这些能力打包成了标准单元。

值得注意的是：插件里的技能、代理、钩子、MCP 服务器——这些能力在插件出现之前就已经存在。插件做的只是把它们标准化。理解这一点，就理解了整个插件系统的设计出发点。

插件 vs 独立配置：怎么选

建议：先用独立配置快速迭代，需要分享时再转成插件。

快速上手：第一个插件

三步走。

第一步：创建目录和清单文件

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

plugin.json 定义插件的身份：

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

name 是唯一标识，也是技能的命名空间。version 可选，设置后用户只在版本号更新时收到更新通知。

第二步：添加技能

技能放在 skills/ 目录下，每个技能是一个文件夹，包含一个 SKILL.md：

mkdir -p my-first-plugin/skills/hello

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

第三步：本地测试

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

启动后在输入框输入 /my-first-plugin:hello 即可测试。

命名空间设计

插件技能一律使用 /插件名:技能名 格式，多个插件中存在同名技能也不会互相覆盖。想让技能接收参数，在 SKILL.md 里用 $ARGUMENTS 占位符：

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today.

修改后运行 /reload-plugins 即可热加载。注意：重载后的技能数量统计只覆盖 commands/ 目录，可能显示 0 skills，但技能实际上已经加载。

另外，claude plugin init my-tool 会在 ~/.claude/skills/ 下初始化一个插件，下次会话自动加载，无需手动传 --plugin-dir。

一个插件能装什么

新手常见错误：把 commands/、agents/、skills/ 等目录放进 .claude-plugin/ 里面。.claude-plugin/ 里只应放 plugin.json，其他所有目录都在插件根目录下。

只有一个技能的插件可以把 SKILL.md 直接放在插件根目录，用 frontmatter 里的 name 字段作为调用名。多技能插件请使用 skills/ 目录。

复杂插件进阶

LSP 服务器：需要支持官方没覆盖的语言时，添加 .lsp.json：

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

用户机器上必须装有对应的语言服务器二进制文件，否则会在 /plugin 管理器的 Errors 标签里看到启动失败。

后台监视器：monitors/monitors.json 定义监视器，插件激活时自动启动，stdout 的每一行都会作为通知发送给 Claude：

[{
  "name": "error-log",
  "command": "tail -F ./logs/error.log",
  "description": "Application error log"
}]

默认设置：settings.json 目前支持 agent 和 subagentStatusLine 两个键。agent 可以把插件里的自定义代理激活为主线程，改变 Claude Code 的默认行为：

{
  "agent": "security-reviewer"
}

测试与调试

--plugin-dir 是本地开发的主通道，支持指向目录或 .zip 压缩包：

claude --plugin-dir ./my-plugin.zip

如果本地插件和已安装的 marketplace 插件同名，本地版本在当前会话中优先。测试已安装插件的修改版时不需要先卸载。

远程测试用 --plugin-url：

claude --plugin-url https://example.com/my-plugin.zip

开发中运行 /reload-plugins 可以热加载更新，无需重启。插件未生效时按三步排查：检查目录结构、逐个测试组件、使用 CLI 调试工具。

提交到社区市场

Anthropic 维护两个公共市场：

• claude-plugins-official：官方精选集，首次交互式启动时自动注册
• claude-community：社区市场，第三方审核后进入

提交前先本地验证：

claude plugin validate ./your-plugin

通过会打印 ✔ Validation passed，加 --strict 把警告当错误处理。

从 .claude/ 迁移

如果你已有独立配置，迁移成本不高。创建插件目录和清单文件，然后复制：

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

钩子需要从 settings.json 里把 hooks 对象复制到 hooks/hooks.json。迁移完成后删除 .claude/ 里的原文件——项目级和用户级的 .claude/agents/ 会覆盖同名插件代理，不删的话插件版本不会生效。技能不会冲突，插件技能是命名空间化的。

插件到底改变了什么

插件没有发明新能力。技能、代理、钩子、MCP 服务器，单独配置时都能用。插件做的是把这些东西标准化，加上版本、名字、描述和分发渠道。

Claude Code 从工具变成了平台——工具做好自己的事，平台让别人做事。

不仅是 Claude Code，Cursor、DSH 都在推出自己的插件市场。原本零散的零件正在被更利于发行和分发的插件形式整合。伴随着 DSH、Codex Harness 等框架开源，AI 原生软件的形式正在变得清晰。