# Claude Code 插件与 Skills

> Claude Code plugin、skills、agents、hooks、MCP、LSP、monitors 的关系,以及从 .claude 配置迁移到可分享插件的方式。

URL: https://docs.passion8.cc/docs/claude-code/plugins
Language: zh-CN
Publisher: Passion8

Claude Code 有两层扩展方式:

如果还没确定该用 `CLAUDE.md`、Skill、Subagent、MCP、Hook 还是 Plugin,先看 [工作原理与扩展地图](https://docs.passion8.cc/docs/claude-code/how-it-works)。官方市场、社区市场、内部 marketplace、版本约束、插件推荐和安全插件治理见 [插件市场与分发](https://docs.passion8.cc/docs/claude-code/plugin-marketplaces)。

| 方式 | 位置 | 适合 |
| --- | --- | --- |
| Standalone 配置 | 项目或用户 `.claude/` | 单项目、个人流程、快速试验 |
| Plugin | 独立目录,可带 `.claude-plugin/plugin.json` | 团队共享、版本化、跨项目复用、市场分发 |

如果只是当前项目要一条命令,先放 `.claude/commands` 或 `.claude/skills`。如果要发给团队、复用到多个项目,再打包成 plugin。

## Plugin 可以包含什么

| 目录或文件 | 作用 |
| --- | --- |
| `.claude-plugin/plugin.json` | manifest,声明名称、描述、版本 |
| `skills/` | Skill 目录,每个 skill 有 `SKILL.md` |
| `commands/` | 旧式扁平命令,新插件优先用 `skills/` |
| `agents/` | 自定义 subagent |
| `hooks/` 或 `hooks.json` | 事件处理器 |
| `.mcp.json` | MCP server 配置 |
| `.lsp.json` | 语言服务器配置 |
| `monitors/` | 后台 monitor 配置 |
| `bin/` | 插件启用时加入 Bash PATH 的可执行文件 |
| `settings.json` | 插件默认 settings |




不要把 `skills/`、`agents/`、`hooks/` 放进 `.claude-plugin/` 目录。`.claude-plugin/` 只放 `plugin.json`。




## 最小插件结构

```text
my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review-api/
        └── SKILL.md
```

`plugin.json`:

```json
{
  "name": "my-plugin",
  "description": "Team workflows for API review",
  "version": "1.0.0",
  "author": {
    "name": "Your Team"
  }
}
```

`skills/review-api/SKILL.md`:

```markdown
---
description: Review API changes for compatibility, auth, pagination, errors, and observability.
---

Review the API change in $ARGUMENTS.
Check request/response compatibility, auth boundary, pagination, error codes, and logs.
Return findings first, then suggested fixes.
```

启用测试:

```bash
claude --plugin-dir ./my-plugin
```

会话里调用:

```text
/my-plugin:review-api src/routes/billing.ts
```

## Skill 命名和参数

| 点 | 说明 |
| --- | --- |
| standalone skill | 通常是 `/skill-name` |
| plugin skill | 通常是 `/plugin-name:skill-name` |
| 参数 | `$ARGUMENTS` 接收命令后面的文本 |
| 自动调用 | 由 `description` 决定 Claude 何时主动使用 |
| 禁止自动调用 | frontmatter 可设置 `disable-model-invocation: true` |
| 限制工具 | 用 `allowed-tools` 或权限规则 |

命名空间看起来长,但能避免多个插件里都有 `/deploy`、`/review` 时冲突。

## 何时从 `.claude/` 迁移到插件

| 信号 | 迁移动作 |
| --- | --- |
| 多个项目复制同一套 commands | 做成 plugin |
| 团队需要统一 hooks / agents | 做成 plugin 并版本化 |
| 需要给 Bash PATH 增加辅助脚本 | plugin `bin/` |
| 需要分发 MCP、LSP、monitor | plugin manifest 管理 |
| 只是当前仓库专用规则 | 留在项目 `.claude/` |

一个实用路径是:先 standalone,稳定后移动到 plugin,最后用 marketplace 或内部仓库分发。

## 插件和缓存

| 操作 | 缓存影响 |
| --- | --- |
| 调用 skill | 作为消息追加,旧前缀通常命中 |
| 启用只含 skills/hooks/agents 的插件 | 通常追加说明,不重建 system prompt |
| 插件带 MCP server | 取决于 tool search,工具 schema upfront 时可能失效 |
| `/reload-plugins` | 变更在 reload 后第一轮体现 |
| 禁用插件后再启用 | 若旧前缀仍在 TTL 内,可能读回旧缓存 |

插件多时,优先确认 MCP 工具是否 deferred,否则每次工具集变化都可能造成 cache miss。

## 官方参考

- [Create plugins](https://code.claude.com/docs/en/plugins.md)
- [Plugins reference](https://code.claude.com/docs/en/plugins-reference.md)
- [Extend Claude with skills](https://code.claude.com/docs/en/skills.md)
- [How Claude Code uses prompt caching](https://code.claude.com/docs/en/prompt-caching.md)