Claude Code 扩展层配置笔记：Skills、MCP、Hooks 的实际边界

一张边界表#

先把几个概念摆平。

我的经验是：一旦 CLAUDE.md 开始出现“先做 A，再做 B，最后输出 C”这种句子，就该考虑拆成 Skill。CLAUDE.md 更像项目 README 的机器可读版，Skill 才是操作手册。

Skills：把流程从提示词里移出去#

Claude Code 现在把自定义 slash command 和 Skill 合并了。.claude/commands/deploy.md 还能用，但新东西建议写成 .claude/skills/<name>/SKILL.md。原因不是语法更时髦，而是 Skill 能带自己的目录、支持文件、触发条件、工具预授权、子代理上下文和动态参数。

Skill 的加载方式也很重要：会话启动时通常只加载名称和描述，SKILL.md 正文在触发后才进入上下文。这个机制解决了一个老问题：你可以保留比较完整的流程文档，而不用每次会话都消耗上下文。

一个项目级 Skill 大概长这样：

1
.claude/
2
└── skills/
3
    └── release-check/
4
        ├── SKILL.md
5
        ├── checklist.md
6
        └── scripts/
7
            └── collect-diff.ps1

SKILL.md 示例：

1
---
2
name: release-check
3
description: Check release risk before tagging or deploying. Use when the user asks for release review, version bump review, changelog validation, or pre-deploy verification.
4
when_to_use: Run this for release-related changes, dependency upgrades, schema changes, and deployment config changes.
5
argument-hint: "[base-ref]"
6
disable-model-invocation: true
7
allowed-tools:
8
  - Read
9
  - Grep
10
  - Glob
11
  - Bash(git status)
12
  - Bash(git diff --stat *)
13
  - Bash(pnpm test *)
14
  - Bash(pnpm build *)
15
paths:
16
  - src/**
17
  - package.json
18
  - pnpm-lock.yaml
19
  - .github/**
20
shell: powershell
21
---
22

23
Use `$ARGUMENTS` as the base ref. If it is empty, use `main`.
24

25
Steps:
26
1. Inspect dependency, schema, environment, build script, and public API changes.
27
2. Run the smallest relevant verification command first.
28
3. Report only release blockers, rollback notes, and manual checks.
29
4. If no meaningful risk is found, say so directly.
30

31
For the detailed checklist, read `${CLAUDE_SKILL_DIR}/checklist.md`.

几个细节值得单独记：

• description 是路由条件，不是简介。它要写“什么时候用”，不要写空泛能力。
• disable-model-invocation: true 适合发布、部署、提交这类你想手动触发的流程。
• allowed-tools 是预授权，不是工具白名单；真正的禁止规则仍然要写到权限的 deny。
• paths 能降低误触发，尤其适合 monorepo。
• shell: powershell 只在启用 PowerShell 工具后有意义。
• 复杂参考资料放旁路文件，不要把 SKILL.md 写成几千行。

我通常把 Skill 控制在一个问题域内。比如 release-check 只做发布检查，不顺手生成 changelog，也不顺手打 tag。范围越窄，Claude 越不容易把流程扩写成一段看似完整但不可执行的叙述。

MCP：接外部系统，不是堆工具名#

MCP 要解决的是外部上下文接入。它适合接 GitHub、Playwright、数据库、日志、内部文档、工单系统。它不适合存放“这个项目的代码风格是什么”。

项目共享的 MCP 配置应放在仓库根目录的 .mcp.json。这类配置可以进版本控制，但密钥只做环境变量引用。

1
{
2
  "mcpServers": {
3
    "github": {
4
      "command": "npx",
5
      "args": ["-y", "@modelcontextprotocol/server-github"],
6
      "env": {
7
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
8
      }
9
    },
10
    "playwright": {
11
      "command": "npx",
12
      "args": ["-y", "@playwright/mcp@latest"]
13
    }
14
  }
15
}

对应的项目策略可以放在 .claude/settings.json：

1
{
2
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
  "enabledMcpjsonServers": ["github", "playwright"],
4
  "permissions": {
5
    "allow": [
6
      "mcp__github__get_*",
7
      "mcp__github__list_*",
8
      "mcp__playwright__*"
9
    ],
10
    "deny": [
11
      "mcp__github__delete_*",
12
      "mcp__github__merge_*"
13
    ]
14
  }
15
}

MCP 的作用域也要分清：

同名 server 同时出现在多个地方时，Claude Code 会按优先级连接一次。实际写配置时，我会避免同名覆盖，尤其不要在用户级和项目级都叫 github，除非你非常确定自己要覆盖什么。

Tool Search：很多 MCP 配置慢，是因为 schema 太多#

MCP server 多了之后，问题不是工具数量本身，而是工具 schema 占上下文。Claude Code 的 Tool Search 会先只加载工具名，需要时再展开定义。

这里有一个国内用户常见坑：如果你设置了非官方的 ANTHROPIC_BASE_URL，Tool Search 默认可能不会强开，因为很多代理不会转发 tool_reference。确认代理支持以后再显式设置：

1
{
2
  "env": {
3
    "ENABLE_TOOL_SEARCH": "true"
4
  }
5
}

如果你不确定代理是否支持，先用：

1
$env:ENABLE_TOOL_SEARCH = "auto:5"
2
claude --debug

观察 debug 日志里 MCP schema 是一次性塞进上下文，还是按需搜索。这个比凭感觉判断靠谱。

新接远程 server 时，我会优先选 HTTP transport。SSE 仍然能见到，但新配置没有必要优先走它。纯本地工具、内部脚本和轻量服务仍然可以用 stdio。

Hooks：不要把强约束写成建议#

Hook 是 Claude Code 里最容易被低估的一层。它的定位很明确：如果某件事必须发生，或者某个动作必须被拦截，就不要只写进提示词。

Hook 的 command 版本会从 stdin 收到 JSON。下面是一个 PowerShell 版危险命令拦截脚本：

1
$payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
2

3
if ($payload.tool_name -ne "Bash") {
4
  exit 0
5
}
6

7
$command = [string]$payload.tool_input.command
8
$blocked = @(
9
  "rm\s+-rf",
10
  "git\s+reset\s+--hard",
11
  "git\s+push\s+--force",
12
  "Remove-Item\s+.*-Recurse"
13
)
14

15
foreach ($pattern in $blocked) {
16
  if ($command -match $pattern) {
17
    [Console]::Error.WriteLine("Blocked by project policy: $command")
18
    exit 2
19
  }
20
}
21

22
exit 0

在 .claude/settings.json 里挂上：

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

exit 2 会阻止工具调用。exit 1 只是非阻塞错误，这点很容易写错。

如果你要做更细的控制，也可以让 Hook 输出 JSON。PreToolUse 现在推荐使用 hookSpecificOutput.permissionDecision：

1
{
2
  "hookSpecificOutput": {
3
    "hookEventName": "PreToolUse",
4
    "permissionDecision": "deny",
5
    "permissionDecisionReason": "Database write commands are blocked in this repository."
6
  }
7
}

我的使用边界：

• PreToolUse：拦危险命令、拦敏感路径、给生产环境操作加阻断。
• PostToolUse：格式化、轻量 lint、记录变更。
• PostToolBatch：在一批工具调用结束后追加上下文，比如提醒跑测试。
• Stop：最后检查是否有未跑的验证命令。

不要把耗时很长的测试无脑塞进 PostToolUse。每次编辑都跑完整 e2e，会让 Claude Code 变成一个很慢的自动保存插件。

权限：本地放开，远程收紧#

权限配置我一般按风险分两类：

• 本地、可回滚、低成本动作：适当放开。
• 远程、不可逆、高影响动作：默认收紧。

一个保守起点：

1
{
2
  "permissions": {
3
    "defaultMode": "normal",
4
    "allow": [
5
      "Read",
6
      "Edit",
7
      "Glob",
8
      "Grep",
9
      "Bash(git status)",
10
      "Bash(git diff *)",
11
      "Bash(pnpm test *)",
12
      "Bash(pnpm build *)",
13
      "mcp__github__get_*",
14
      "mcp__github__list_*"
15
    ],
16
    "deny": [
17
      "Read(**/.env)",
18
      "Read(**/.env.*)",
19
      "Bash(git push --force *)",
20
      "Bash(rm -rf *)",
21
      "Bash(Remove-Item * -Recurse *)",
22
      "mcp__github__delete_*",
23
      "mcp__github__merge_*"
24
    ]
25
  }
26
}

这里我宁愿一开始多问几次，也不想默认把远程写操作放开。等你知道某个 MCP 工具只读、稳定、低风险，再把它加入 allow。

Windows 和 PowerShell：能用，但要写清楚#

如果你的主力环境是 Windows，建议显式打开 PowerShell 工具预览：

1
{
2
  "env": {
3
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
4
  }
5
}

然后在 Skill 里用：

1
shell: powershell

这能减少 Git Bash 和 Windows 路径之间的摩擦。代价是团队里如果有人用 macOS/Linux，同一个 Skill 里的 shell 片段就不一定可移植。我的做法是：

• 项目通用 Skill 尽量只写命令意图，少写平台脚本。
• Windows 项目的自动化脚本直接 .ps1 化。
• Hook 里不要依赖个人 PowerShell profile，用 -NoProfile。
• 需要跨平台的检查逻辑，优先写 Node/Python 脚本，再由 Hook 调用。

Plugin：跨仓库复用时再上#

单仓库内，.claude/ 已经够用。Plugin 的意义是分发和版本管理，不是让配置看起来高级。

一个最小结构：

1
my-team-plugin/
2
├── .claude-plugin/
3
│   └── plugin.json
4
├── skills/
5
│   └── release-check/
6
│       └── SKILL.md
7
├── hooks/
8
│   └── hooks.json
9
├── agents/
10
│   └── reviewer.md
11
└── .mcp.json

注意：plugin.json 放在 .claude-plugin/ 里，skills/、hooks/、agents/、.mcp.json 放在插件根目录，不要塞进 .claude-plugin/。

我只在这几种情况下做 Plugin：

• 同一套 Skill 要在多个仓库复用。
• Hook 已经形成团队策略。
• MCP server 是团队统一维护的内部服务。
• 需要通过 marketplace 或固定目录分发。

否则，先留在 .claude/，维护成本更低。

我的配置落点#

如果今天给一个真实项目从零配置，我会先落这几个文件：

1
.claude/
2
├── CLAUDE.md
3
├── settings.json
4
├── settings.local.json
5
├── hooks/
6
│   └── block-dangerous.ps1
7
└── skills/
8
    ├── release-check/
9
    │   ├── SKILL.md
10
    │   └── checklist.md
11
    └── pr-review/
12
        ├── SKILL.md
13
        └── rubric.md
14

15
.mcp.json

第一轮只做这些：

1. CLAUDE.md 写项目事实，不超过 200 行。
2. settings.json 写 deny 规则、低风险 allow、PowerShell 开关。
3. .mcp.json 只接 GitHub 和 Playwright。
4. release-check 写成手动触发 Skill。
5. block-dangerous.ps1 拦截不可逆命令。

等这套跑顺，再加数据库、日志、内部文档这些 MCP。不要一开始就把所有东西都接进来。Claude Code 的问题通常不是能力不够，而是上下文、权限和自动化边界没有收好。

结论#

Claude Code 的扩展系统可以按一句话理解：

CLAUDE.md 记录事实，Skill 固化流程，MCP 接入外部状态，Hook 执行硬约束，Plugin 负责复用分发。

这个分法不花哨，但能减少很多长期维护问题。尤其是团队项目里，最大的收益不是 Claude 偶尔写出一段漂亮代码，而是它在反复执行同一类任务时不会每次都换一套做法。

参考资料#

• Extend Claude with skills
• Connect Claude Code to tools via MCP
• Hooks reference
• Claude Code settings
• Create plugins