创建插件

从空目录做出第一个 Claude Code 插件：清单、目录布局、用 --plugin-dir 无需市场地测试，以及把已有的 .claude/ 配置改造成插件。

插件是一个目录，里面放 Skill、智能体、Hook 和 MCP 服务器，外加一个叫「清单」的 plugin.json 来给插件命名。Claude Code 把整个目录作为一个单元加载，所以你可以分享给队友、装进多个项目，或发布带版本的发行物。

什么时候该做成插件

Skill、智能体、Hook 和 MCP 服务器单独放在项目或家目录里就能工作。只要它只服务一个项目或只服务你自己，就保持独立配置；想分享给队友、装进多个项目或发布版本时，再做成插件。迁移到插件后，位置和名字都会变：

文件位置：放在插件自己的目录（插件根）下，即 skills/、agents/、hooks/hooks.json 和 .mcp.json
命名：插件里的 Skill 和智能体带插件名前缀，如 /my-plugin:hello，所以两个插件可以各自提供一个 hello Skill 而不冲突

做第一个插件

下面做一个只有一个 Skill（一句问候）的插件，并用 --plugin-dir 运行它（该标志为一个会话加载插件而不安装）。

创建插件目录，并在里面放一个存放清单的 .claude-plugin/ 文件夹：
```
mkdir -p my-first-plugin/.claude-plugin
```
保存清单为 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 必填，它标识插件，并成为插件提供的每个 Skill 和智能体的前缀（名字里不要有空格）；description 是用户在 /plugin 里看到的文字；version 可选，设置后会把用户留在该版本上直到你改它；author 是署名，里面 name 必填。只有 plugin.json 放进 .claude-plugin/，其他组件直接放在插件根下
每个 Skill 是 skills/ 下含 SKILL.md 的一个目录。创建 my-first-plugin/skills/hello/SKILL.md：
```
---
name: 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.
```
disable-model-invocation: true 表示 Claude 不会自己运行这个 Skill，只有你来触发；想让 Claude 自行运行，去掉这一行
运行之前先校验清单和 Skill 的前置信息：
```
claude plugin validate ./my-first-plugin
```
通过时会打印 ✔ Validation passed，失败时每一行会指出要修的字段

带着插件启动会话，然后运行 Skill：

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

/my-first-plugin:hello

插件只在你用 --plugin-dir 启动的会话里加载。想让 Claude 帮你搭建并检查更大的插件，可以从官方市场安装 Anthropic 的 plugin-dev 插件。

插件目录布局

每种组件都放在插件根下的固定目录里（插件根就是你传给 --plugin-dir 的目录）。大多数插件从这几个位置开始：

位置	内容
`.claude-plugin/plugin.json`	清单；用 `--plugin-dir` 加载且没有清单时，Claude Code 以目录名为插件命名
`skills/`	每个 Skill 一个 `<name>/SKILL.md` 目录
`commands/`	平铺的 Markdown 文件，是 Skill 的较旧形式；新插件用 `skills/`
`agents/`	每个子智能体一个 Markdown 文件
`hooks/hooks.json`	Hook 配置
`.mcp.json`	MCP 服务器配置

不用市场开发与测试

开发期间不需要市场：--plugin-dir 直接从文件夹加载插件；测试 .zip 构建也可以用同一个标志。常见问题：组件路径找不到（检查是不是放错了层级）；--plugin-dir 指向市场根目录时不会加载 plugins/ 下的插件（要指向具体的插件目录）；插件加载了但 Skill 缺失（Skill 必须在 skills/<name>/SKILL.md）；userConfig 对话框没出现。验证插件确实改变了 Claude 的行为：用一个只有这个插件才能完成的任务来检查。

分享你的插件

用上面做的插件只存在于你的机器上。准备好给别人时有三种办法：直接发给少数几个人（给目录或 .zip，不用发布任何东西）；列在你自己的市场里（队友添加一次你的市场，按名字安装插件，并收到你的更新）；提交到 Anthropic 的目录（通过审核后，人们可以在 claude.ai 和 Cowork 里添加，并通过账号到达 Claude Code）。

改造已有的 .claude/ 配置：先走一遍上面的第一个插件流程学会布局，再把 .claude/ 下的 Skill、智能体、Hook 和 MCP 配置按上面的目录布局搬进插件根，并注意搬过去之后名字会带上插件名前缀。官方原文有完整的改造步骤。