Plugin Guide¶

重要性：⭐⭐ 目标读者：plugin 作者 / 团队管理员关联：topics/deep-dive-plugin-loader.md、tutorials/build-plugin.md

1. 概览¶

Plugin = Claude Code 的扩展包。

5 类资源： - Commands - Agents - Hooks - MCP servers - Skills

2. 8 个 Plugin 文件 / 目录¶

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # manifest
├── commands/                # /cmd
├── agents/                  # sub-agent
├── hooks/                   # 生命周期
├── mcp/                     # MCP servers (新)
├── skills/                  # skills
├── .mcp.json                # MCP servers (旧)
└── README.md

8 目录/文件。

3. plugin.json 完整字段¶

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "...",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://github.com/you"
  },
  "homepage": "https://github.com/you/my-plugin",
  "repository": "https://github.com/you/my-plugin",
  "license": "MIT",
  "keywords": ["productivity", "tools"],
  "engines": {
    "claude-code": ">=1.0.0"
  }
}

10 字段。

4. 6 种安装源¶

4.1 npm¶

claude plugin install npm:@my-org/my-plugin

npm 通用。

4.2 git¶

claude plugin install git+https://github.com/you/my-plugin

git。

4.3 GitHub¶

claude plugin install https://github.com/you/my-plugin

GitHub 优化。

4.4 git subdir¶

claude plugin install git+https://github.com/monorepo#subdir=plugins/foo

monorepo。

4.5 Local¶

claude plugin install /path/to/local

本地。

4.6 Session-only¶

claude --plugin-dir /path/to/local

单次。

5. 5 种 Plugin 资源详解¶

5.1 Commands¶

# commands/build.md
---
description: Build the project
---
Run build and report status.

Slash 命令。

5.2 Agents¶

# agents/reviewer.md
---
name: reviewer
description: Code reviewer
tools: Read, Grep, Glob
model: sonnet
---
You are a reviewer.

Sub-agents。

5.3 Hooks¶

// hooks/hooks.json
{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        { "type": "command", "command": "./validate.sh" }
      ]
    }
  ]
}

生命周期。

5.4 MCP servers¶

// .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@mcp/server-github"]
    }
  }
}

MCP。

5.5 Skills¶

# skills/review/SKILL.md
---
name: review
description: Code review
---
When user asks for review...

Skills。

6. Plugin 完整流程¶

6.1 创建¶

mkdir my-plugin
cd my-plugin
mkdir -p .claude-plugin commands

3 步。

6.2 写 manifest¶

// .claude-plugin/plugin.json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "...",
  "author": { "name": "You" }
}

1 步。

6.3 加资源¶

echo "..." > commands/hello.md
echo "..." > agents/agent.md
echo "{...}" > hooks/hooks.json

3 步。

6.4 测试¶

claude --plugin-dir ./my-plugin

1 步。

6.5 发布¶

# 推到 git
git push
# 邀请用户用 git+ URL

发布。

7. Marketplace 集成¶

7.1 创建 marketplace¶

// marketplace.json
{
  "name": "my-marketplace",
  "owner": { "name": "Org" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "git+https://github.com/you/my-plugin"
    }
  ]
}

marketplace.json。

7.2 用户添加¶

claude marketplace add https://github.com/you/my-marketplace
claude plugin install my-plugin

2 步。

8. 5 个最佳实践¶

小而专 —— 一个 plugin 一个目的
文档完整 —— README + 示例
路径校验 —— hooks 不跳出 plugin 目录
版本管理 —— semver
本地测试 —— --plugin-dir

5 条。

9. 安全考虑¶

9.1 路径校验¶

Claude Code 校验 hooks 路径不跳出 plugin。

# ❌ 失败
"command": "../../../etc/passwd"

校验。

9.2 命令执行¶

✅ 自己的命令
⚠️ 用户输入拼接（小心）

避免注入。

9.3 来源审查¶

✅ 官方 marketplace
⚠️ 私人 marketplace
❌ 未知源

审查。

10. 5 个调试技巧¶

本地测试 —— --plugin-dir
debug mode —— --debug plugin
manifest 校验 —— plugin validate
cache 清 —— clearPluginCache
log 看 —— ~/.claude/logs

5 技巧。

11. Plugin vs Skill vs Command¶

维度	Plugin	Skill	Command
复杂度	高	中	低
分发	团队	个人	个人
资源数	5	1	1
安装	显式	自动	自动

何时用。

12. 5 个真实 Plugin 例子¶

12.1 GitHub Plugin¶

提供 GitHub 工具（创建 issue / PR）。

12.2 Database Plugin¶

数据库工具（schema 探索 / 查询）。

12.3 Testing Plugin¶

测试工具（生成 / 运行）。

12.4 Deploy Plugin¶

部署工具（K8s / Docker）。

12.5 Security Plugin¶

安全扫描（linter / secret scan）。

5 例。

13. 总结¶

Plugin = 团队扩展 Claude Code 的标准方式。

核心： - 8 目录/文件 - 5 类资源 - 6 种安装源 - Marketplace 集成

下一步： - 看 tutorials/build-plugin.md - 看 deep-dive-plugin-loader.md - 写第一个 plugin