阶段 3 · 定制与扩展——Skill / Hook / Subagent / Plugin 四件套

1
my-skill/
2
├── SKILL.md           # 主说明（必需）
3
├── reference.md       # 详细参考，按需加载
4
├── examples/
5
│   └── sample.md
6
└── scripts/
7
    └── helper.py

1
---
2
name: my-skill                     # 显示名称，命令名来自目录名
3
description: >                     # Claude 用此决定何时自动加载（推荐填写）
4
  当用户询问 xxx 时使用
5
when_to_use: >                     # 补充触发场景，附加在 description 后
6
  触发短语: "帮我做 xxx"
7
argument-hint: "[issue-number]"    # /命令 后自动补全时的提示
8
arguments: [issue, branch]         # 命名参数，映射 $issue $branch
9
disable-model-invocation: true     # true: 只能手动 /name 调用，Claude 不自动触发
10
user-invocable: false              # false: 从 / 菜单隐藏，只由 Claude 自动调用
11
allowed-tools: Bash(git *) Read    # skill 激活时预批准的工具
12
disallowed-tools: AskUserQuestion  # skill 激活时禁用的工具
13
model: sonnet                      # 覆盖当前轮次的模型（inherit / haiku / sonnet / opus）
14
effort: high                       # low / medium / high / xhigh / max
15
context: fork                      # 在独立 subagent 中运行此 skill
16
agent: Explore                     # 配合 context: fork 指定代理类型
17
hooks:                             # 限定于此 skill 生命周期的 hook
18
  PostToolUse:
19
    - matcher: "Edit"
20
      hooks:
21
        - type: command
22
          command: "npx prettier --write"
23
paths: "src/**/*.ts,*.go"          # 仅在操作匹配文件时自动加载
24
shell: powershell                  # 内联 !`cmd` 使用 PowerShell（需 CLAUDE_CODE_USE_POWERSHELL_TOOL=1）
25
---

1
## 当前 diff
2
!`git diff HEAD`
3

4
## 多行注入
5
```!
6
node --version
7
git status --short
8
```

1
---
2
name: fix-issue
3
description: >
4
  按团队规范修复 GitHub issue。当用户说"修复 issue 123"或"/fix-issue 编号"时使用。
5
argument-hint: "[issue-number]"
6
disable-model-invocation: true
7
allowed-tools: Bash(git *) Bash(gh *) Read Edit Write Grep Glob
8
---
9

10
## 当前 issue 信息
11

12
!`gh issue view $ARGUMENTS --json title,body,labels`
13

14
## 操作步骤
15

16
1. 阅读上方 issue 内容，理解需求
17
2. 用 Grep/Glob 定位相关代码
18
3. 实现修复，遵循项目代码风格
19
4. 运行测试（如果存在）：`Bash("npm test" 或项目约定命令)`
20
5. 暂存并提交：
21
   - `git add -p`（交互式确认变更）
22
   - `git commit -m "fix: <issue 标题> (#$ARGUMENTS)"`
23
6. 输出：修改了哪些文件、提交 SHA、剩余风险点
24

25
## 注意
26

27
- 若 issue 描述不清，停下来问我，不要猜测
28
- 不要修改 `.env`、`package-lock.json`、`.git/` 内的文件

1
/fix-issue 456

1
{
2
  "session_id": "abc123",
3
  "cwd": "/your/project",
4
  "hook_event_name": "PreToolUse",
5
  "tool_name": "Bash",
6
  "tool_input": {
7
    "command": "npm test"
8
  }
9
}

1
{
2
  "hookSpecificOutput": {
3
    "hookEventName": "PreToolUse",
4
    "permissionDecision": "deny",
5
    "permissionDecisionReason": "请使用 rg 替代 grep 以获得更好性能"
6
  }
7
}

1
{
2
  "decision": "block",
3
  "reason": "测试未通过，请先修复"
4
}

1
{
2
  "additionalContext": "用户所在时区：UTC+8，当前 sprint：认证重构"
3
}

1
{
2
  "hooks": {
3
    "PostToolUse": [
4
      {
5
        "matcher": "Edit|Write",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "command": "powershell -NoProfile -Command \"$input = $input | Out-String | ConvertFrom-Json; npx prettier --write $input.tool_input.file_path\""
10
          }
11
        ]
12
      }
13
    ],
14
    "PreToolUse": [
15
      {
16
        "matcher": "Bash",
17
        "hooks": [
18
          {
19
            "type": "command",
20
            "command": "powershell -NoProfile -File \"$env:USERPROFILE\\.claude\\hooks\\block-dangerous.ps1\""
21
          }
22
        ]
23
      }
24
    ],
25
    "Stop": [
26
      {
27
        "hooks": [
28
          {
29
            "type": "command",
30
            "command": "powershell -NoProfile -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude 已完成', 'Claude Code')\""
31
          }
32
        ]
33
      }
34
    ],
35
    "Notification": [
36
      {
37
        "matcher": "idle_prompt",
38
        "hooks": [
39
          {
40
            "type": "command",
41
            "command": "powershell -NoProfile -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude 需要你的输入', 'Claude Code')\""
42
          }
43
        ]
44
      }
45
    ],
46
    "SessionStart": [
47
      {
48
        "matcher": "compact",
49
        "hooks": [
50
          {
51
            "type": "command",
52
            "command": "powershell -NoProfile -Command \"Write-Output '提醒：使用 pnpm 而非 npm，提交前跑 pnpm test，当前 sprint：认证重构'\""
53
          }
54
        ]
55
      }
56
    ]
57
  }
58
}

1
{
2
  "hooks": {
3
    "PreToolUse": [
4
      {
5
        "matcher": "Bash",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "command": "powershell -NoProfile -File \"$env:USERPROFILE\\.claude\\hooks\\block-dangerous.ps1\""
10
          }
11
        ]
12
      }
13
    ]
14
  }
15
}

1
{
2
  "hooks": {
3
    "PreToolUse": [
4
      {
5
        "matcher": "Bash",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "if": "Bash(git *)",
10
            "command": "powershell -NoProfile -File \"$env:USERPROFILE\\.claude\\hooks\\check-git-policy.ps1\""
11
          }
12
        ]
13
      }
14
    ]
15
  }
16
}

1
---
2
name: code-reviewer              # 必需，小写+连字符，hooks 中作为 agent_type 使用
3
description: >                   # 必需，Claude 据此决定何时委托
4
  代码审查专家。代码变更后主动使用。
5
tools: Read, Grep, Glob, Bash    # 允许工具列表（省略则继承所有）
6
disallowedTools: Write, Edit     # 禁用工具列表
7
model: sonnet                    # sonnet / opus / haiku / 完整 model ID / inherit
8
permissionMode: acceptEdits      # default / acceptEdits / auto / dontAsk / bypassPermissions / plan
9
maxTurns: 20                     # 最大代理轮数
10
skills:                          # 启动时预加载的 skill（注入完整内容而非描述）
11
  - api-conventions
12
  - error-handling-patterns
13
mcpServers:                      # 仅此 subagent 可用的 MCP 服务器
14
  - playwright:
15
      type: stdio
16
      command: npx
17
      args: ["-y", "@playwright/mcp@latest"]
18
hooks:                           # 限定于此 subagent 的 hook
19
  PreToolUse:
20
    - matcher: "Bash"
21
      hooks:
22
        - type: command
23
          command: "./scripts/validate-command.sh"
24
memory: project                  # user / project / local，启用跨会话持久记忆
25
background: false                # true: 始终作为后台任务运行
26
effort: medium                   # 工作量级别
27
isolation: worktree              # 在独立 git worktree 中运行（文件改动隔离）
28
color: blue                      # red/blue/green/yellow/purple/orange/pink/cyan
29
---
30

31
你是一名资深代码审查员……（系统提示正文）

1
用 code-reviewer subagent 检查最近的认证模块改动

1
@"code-reviewer (agent)" 看一下 auth 的变更

1
{
2
  "agent": "code-reviewer"
3
}

1
---
2
name: db-reader
3
description: 执行只读数据库查询，用于数据分析和报告生成
4
tools: Bash
5
hooks:
6
  PreToolUse:
7
    - matcher: "Bash"
8
      hooks:
9
        - type: command
10
          command: "powershell -NoProfile -File .claude/hooks/validate-readonly-query.ps1"
11
---
12

13
你是数据库分析员，只有只读权限。执行 SELECT 查询回答数据问题。
14

15
如果被要求执行 INSERT/UPDATE/DELETE/DROP，解释你只有只读访问权限。

1
my-plugin/
2
├── .claude-plugin/
3
│   └── plugin.json          # 清单（可选，有此文件或组件目录之一即为插件）
4
├── skills/
5
│   └── hello/
6
│       └── SKILL.md
7
├── commands/                # 旧版平面文件形式（仍兼容）
8
├── agents/
9
│   └── reviewer.md
10
├── hooks/
11
│   └── hooks.json
12
├── .mcp.json                # MCP server 配置
13
├── .lsp.json                # LSP server 配置
14
├── monitors/
15
│   └── monitors.json        # 后台监视器
16
├── output-styles/           # 自定义输出样式
17
├── bin/                     # 添加到 PATH 的可执行文件
18
└── settings.json            # 启用插件时的默认设置

1
{
2
  "name": "my-plugin",
3
  "description": "做某件事的插件",
4
  "version": "1.0.0",
5
  "author": {
6
    "name": "你的名字",
7
    "email": "optional@example.com"
8
  },
9
  "homepage": "https://github.com/you/my-plugin",
10
  "repository": "https://github.com/you/my-plugin",
11
  "license": "MIT"
12
}

1
{
2
  "hooks": {
3
    "PostToolUse": [
4
      {
5
        "matcher": "Write|Edit",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh"
10
          }
11
        ]
12
      }
13
    ]
14
  }
15
}

1
{
2
  "agent": "security-reviewer"
3
}

1
{
2
  "name": "company-tools",
3
  "owner": {
4
    "name": "DevTools Team"
5
  },
6
  "plugins": [
7
    {
8
      "name": "code-formatter",
9
      "source": "./plugins/formatter",
10
      "description": "编辑后自动格式化"
11
    },
12
    {
13
      "name": "deployment-tools",
14
      "source": {
15
        "source": "github",
16
        "repo": "company/deploy-plugin"
17
      },
18
      "description": "部署自动化工具"
19
    }
20
  ]
21
}

1
# 在 Claude Code 会话内：
2

3
# 添加 marketplace
4
/plugin marketplace add anthropics/claude-plugins-community
5
/plugin marketplace add company/internal-plugins
6
/plugin marketplace add ./local-marketplace
7

8
# 列出可用插件
9
/plugin list
10

11
# 安装插件
12
/plugin install code-formatter@company-tools
13

14
# 管理已安装插件
15
/plugin enable my-plugin
16
/plugin disable my-plugin
17
/plugin update my-plugin
18

19
# 验证插件结构
20
/plugin validate ./my-plugin

1
/config  →  选择"输出样式"

1
{
2
  "outputStyle": "Proactive"
3
}

1
---
2
name: Diagrams First
3
description: 每次解释都先给出 Mermaid 图
4
keep-coding-instructions: true
5
---
6

7
解释代码、架构或数据流时，先用 Mermaid 图展示结构，再用文字说明。
8

9
使用 `flowchart TD` 表示控制流，`sequenceDiagram` 表示请求路径。图保持在 15 节点以内。

1
/statusline 显示模型名、上下文百分比进度条、当前 git 分支

1
{
2
  "statusLine": {
3
    "type": "command",
4
    "command": "~/.claude/statusline.ps1",
5
    "padding": 2,
6
    "refreshInterval": 10
7
  }
8
}

1
{
2
  "hooks": {
3
    "PostToolUse": [
4
      {
5
        "matcher": "Edit|Write",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "if": "Edit(*.ts|*.tsx) Write(*.ts|*.tsx)",
10
            "command": "powershell -NoProfile -Command \"$j = $input | Out-String | ConvertFrom-Json; npx prettier --write $j.tool_input.file_path\""
11
          }
12
        ]
13
      }
14
    ]
15
  }
16
}

1
---
2
name: code-reviewer
3
description: 代码质量审查专家。代码改动后主动使用。
4
tools: Read, Grep, Glob, Bash(git diff *) Bash(git log *)
5
model: sonnet
6
color: blue
7
---
8

9
你是资深代码审查员。
10

11
审查时关注：
12
- 代码可读性和命名
13
- 错误处理是否完整
14
- 潜在安全问题
15
- 测试覆盖率
16
- 性能隐患
17

18
输出格式：
19
- 🔴 严重（必须修复）
20
- 🟡 警告（建议修复）
21
- 🔵 建议（可以改进）
22

23
每条包含具体文件和行号。

1
@"code-reviewer (agent)" 审查最近的 auth 模块改动

1
my-dev-plugin/
2
├── .claude-plugin/
3
│   └── plugin.json
4
├── skills/
5
│   └── review-pr/
6
│       └── SKILL.md    # 从练习 1 复制
7
└── hooks/
8
    └── hooks.json      # 格式化 hook

1
{
2
  "name": "my-dev-plugin",
3
  "description": "PR 审查 + 自动格式化工具包",
4
  "version": "1.0.0"
5
}