Tutorial ｜构建 Claude Code Plugin¶

难度：⭐⭐⭐ 时间：~1.5h 前置：deep-dive-plugin-loader.md 产物：可安装的 Claude Code plugin

1. Plugin 是什么¶

Plugin = 给 Claude Code 扩展功能的包 - 包含 commands / agents / hooks / MCP servers - 通过 marketplace 分发 - 6 种安装源

2. Plugin 结构¶

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # manifest
├── commands/                # /my-cmd
│   └── my-cmd.md
├── agents/                  # Agent
│   └── my-agent.md
├── hooks/                   # hooks 配置
│   └── hooks.json
├── mcp/                     # MCP servers
│   └── mcp.json
├── skills/                  # Skills
│   └── my-skill.md
├── .mcp.json                # MCP servers (alt)
├── README.md
└── LICENSE

8 个目录/文件。

3. 3 步创建 Plugin¶

3.1 Step 1: 创建目录¶

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

3.2 Step 2: 写 manifest¶

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My awesome plugin",
  "author": {
    "name": "Your Name",
    "url": "https://github.com/you"
  },
  "homepage": "https://github.com/you/my-plugin",
  "license": "MIT",
  "keywords": ["productivity", "tools"]
}

8 字段。

3.3 Step 3: 添加内容（任选）¶

# Commands
cat > commands/hello.md <<'EOF'
---
description: Say hello
---

# Hello
Print "Hello, world!" and greet the user.
EOF

# Agents
cat > agents/reviewer.md <<'EOF'
---
name: reviewer
description: Code reviewer
tools: Read, Grep, Glob
---
You are a code reviewer.
EOF

# Hooks
cat > hooks/hooks.json <<'EOF'
{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        { "type": "command", "command": "echo 'Bash called'" }
      ]
    }
  ]
}
EOF

4. Manifest 详细字段¶

interface PluginManifest {
  name: string              // 必填
  version: string          // 必填
  description: string
  author?: { name, url, email }
  homepage?: string
  repository?: string
  license?: string
  keywords?: string[]
  engines?: { 'claude-code': string }
  // 推测
}

9+ 字段。

5. 4 种 Plugin 资源¶

5.1 Commands¶

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

Slash commands —— /build 触发。

5.2 Agents¶

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

Sub-agents —— Agent(reviewer) 触发。

5.3 Hooks¶

// hooks/hooks.json
{
  "PreToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/validate.sh",
          "timeout": 30
        }
      ]
    }
  ]
}

Hooks —— 自动触发。

5.4 MCP Servers¶

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

MCP 集成。

5.5 Skills¶

# skills/code-review/SKILL.md
---
name: code-review
description: Triggered when user asks for code review
---

# Code Review Skill
When user asks for code review, follow this protocol:
...

Skills —— /code-review 触发。

6. 6 种安装源¶

6.1 npm¶

# plugin.json 加上
{ "name": "my-plugin", "version": "1.0.0" }

# 安装
claude plugin add npm:my-plugin

npm 通用。

6.2 git¶

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

git 仓库。

6.3 GitHub¶

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

GitHub 优化（用 tarball）。

6.4 git subdir¶

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

monorepo。

6.5 Local¶

claude plugin add /path/to/local-plugin

本地开发。

6.6 Session-only¶

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

单次。

7. 完整实战：My First Plugin¶

7.1 目录结构¶

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── greet.md
├── agents/
│   └── helper.md
├── hooks/
│   └── hooks.json
└── README.md

7.2 plugin.json¶

{
  "name": "my-first-plugin",
  "version": "0.1.0",
  "description": "A simple starter plugin",
  "author": { "name": "You" },
  "license": "MIT"
}

7.3 commands/greet.md¶

---
description: Greet the user in a fun way
---

# Greet

Greet the user with:
- Their name (from session context)
- A random fun fact
- An emoji of your choice

Be brief (3 lines max).

7.4 agents/helper.md¶

---
name: helper
description: A friendly helper agent
tools: Read
---

You are a friendly helper. Be concise and warm.

7.5 hooks/hooks.json¶

{
  "SessionStart": [
    {
      "hooks": [
        { "type": "command", "command": "echo 'Plugin loaded!'" }
      ]
    }
  ]
}

7.6 测试¶

# 本地
claude --plugin-dir /path/to/my-first-plugin

# 在 Claude Code 中
> /greet
> Use helper agent to read README.md

8. 发布到 Marketplace¶

8.1 Marketplace 仓库¶

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

注册 plugin。

8.2 用户安装¶

# 1. 注册 marketplace
claude marketplace add https://github.com/you/my-marketplace

# 2. 安装 plugin
claude plugin install my-first-plugin

2 步。

9. 安全考虑¶

9.1 路径校验¶

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

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

# ✅ 通过
"command": "./scripts/validate.sh"

校验。

9.2 命令执行¶

✅ 自己的命令
❌ 用户输入拼接

避免注入。

9.3 Manifest 来源¶

✅ 官方 marketplace
⚠️ 私人 marketplace（需审查）
❌ 未知源

来源重要。

10. 5 个最佳实践¶

小而专 —— 一个 plugin 一个功能
文档完整 —— README + 示例
测试 hooks —— 用 --plugin-dir 测
版本管理 —— semver
manifest 完整 —— name / version / description 必填

5 条。

11. 调试¶

11.1 本地测试¶

claude --plugin-dir ./my-plugin --debug plugin

debug。

11.2 加载日志¶

# 推测
claude --debug plugin

日志。

11.3 Manifest 校验¶

claude plugin validate ./my-plugin

校验（推测）。

12. 下一步¶

写第一个 plugin
测本地
推到 git
注册 marketplace

Tutorial ｜ 构建 Claude Code Plugin¶