Claude Code终端使用指南（五）—Skills、子代理、Hooks、MCP与插件

Claude Code 内置的读取、搜索、编辑、命令执行和网络工具已经能够完成多数开发任务。扩展机制解决的是更具体的问题：让 Claude 记住按需知识、复用工作流、把调查放进独立上下文、确定性执行检查、连接外部系统，并把这些能力分发给团队。

本文继续使用虚构的 task-board 项目，完成以下扩展：

1. 创建 /fix-issue Skill；
2. 创建只读 security-reviewer 子代理；
3. 配置编辑后格式化和保护迁移文件的 Hooks；
4. 连接 Claude Code 官方文档 MCP；
5. 说明何时使用插件与代码智能插件。

---

0. 扩展机制选择速查

需求	机制	加载或执行方式
每次会话都应知道的约定	CLAUDE.md	启动时全文加载
特定路径的长期规则	.claude/rules/	启动时或读取匹配文件时
可复用知识或多步流程	Skill	描述常驻，正文按需加载
高输出调查或专门角色	子代理	独立上下文，返回摘要
外部系统的数据和操作	MCP	连接服务器后提供工具
每次匹配事件都必须执行	Hook	生命周期事件确定性触发
语言服务器导航与诊断	Code intelligence plugin	安装语言插件后启用 LSP
跨仓库分发整套能力	Plugin	打包 Skill、Agent、Hook、MCP 等

官方推荐的演进顺序是按实际痛点逐步添加：

同一约定错两次       → CLAUDE.md
重复输入同一提示     → Skill
反复粘贴外部数据     → MCP
调查污染主上下文     → 子代理
某动作必须每次发生   → Hook
第二个仓库需要同配置 → Plugin

不要一次安装大量扩展。每个 Skill 描述、MCP 工具和插件都可能增加上下文或启动成本。

---

1. 理解扩展在代理循环中的位置

会话启动
  ├── 加载 CLAUDE.md
  ├── 加载 Rule
  ├── 加载 Skill 描述
  ├── 注册 MCP 工具名称
  ├── 注册子代理定义
  └── 注册 Hooks

用户提交任务
  ├── Claude 选择 Skill 或子代理
  ├── Claude 选择内置或 MCP 工具
  ├── PreToolUse Hook 可拦截
  ├── 权限与沙箱检查
  ├── 工具执行
  └── PostToolUse Hook 可格式化、检查或返回上下文

各机制不是互斥替代关系。例如：

• MCP 连接数据库，Skill 说明本项目数据模型和只读查询流程；
• Skill 启动子代理完成隔离审查；
• Hook 在文件编辑后运行格式化并把错误反馈给 Claude；
• Plugin 把 Skill、Agent、Hook 和 MCP 配置打包。

2. Skills

2.1 Skill 适合什么

Skill 是包含 YAML Front Matter 和 Markdown 指令的 SKILL.md。它可以是：

• 按需参考资料；
• 可手动调用的命令；
• Claude 自动匹配的工作流；
• 带模板、示例、脚本和参考文件的复合能力。

自定义命令已并入 Skill 体系。已有 .claude/commands/<name>.md 仍可工作，但新功能优先使用 .claude/skills/<name>/SKILL.md。

2.2 位置与作用域

作用域	路径
个人	~/.claude/skills/<name>/SKILL.md
项目	.claude/skills/<name>/SKILL.md
企业	Managed 配置提供
插件	<plugin>/skills/<name>/SKILL.md

个人 Skill 优先于项目 Skill；插件 Skill 带插件命名空间，避免与普通 Skill 冲突。

项目 Skill 会从当前目录向仓库根发现，也可以在 monorepo 子目录中按需发现。

2.3 创建 /fix-issue

目录：

.claude/skills/fix-issue/
└── SKILL.md

内容：

---
name: fix-issue
description: 根据 GitHub Issue 调查、修复并验证 task-board 缺陷
argument-hint: "[issue-number]"
disable-model-invocation: true
allowed-tools:
  - Read
  - Grep
  - Glob
  - "Bash(gh issue view *)"
  - "Bash(npm test *)"
  - "Bash(npm run typecheck)"
  - "Bash(npm run build)"
---

处理 GitHub Issue：$ARGUMENTS。

1. 使用 `gh issue view` 获取 Issue 正文和验收条件。
2. 只读调查相关调用链和现有测试。
3. 若需求有歧义，停止并询问用户。
4. 写一个当前失败的测试稳定复现问题。
5. 完成最小修复。
6. 运行最小相关测试、类型检查和构建。
7. 检查差异范围。
8. 返回根因、修改文件、验证证据和剩余风险。

除非用户另行明确授权，不执行提交、Push、创建 Pull Request 或部署。

调用：

/fix-issue 128

disable-model-invocation: true 表示 Claude 不会自行触发；这对具有副作用或需要用户明确选择的流程更安全，也避免描述常驻上下文。allowed-tools 只在 Skill 当前轮次提供预批准，不应写宽泛云写入或发布权限。

2.4 Skill Front Matter

常用字段：

字段	作用
name	显示名，默认使用目录名
description	Claude 判断何时使用的主要依据
when_to_use	补充触发场景
argument-hint	自动完成时显示参数提示
arguments	定义具名位置参数
disable-model-invocation	禁止 Claude 自动触发
user-invocable	是否出现在 / 菜单
allowed-tools	当前轮次预先允许的工具
disallowed-tools	当前轮次移除的工具
model	当前轮次模型
effort	当前轮次推理强度
context	可设为 fork 在独立上下文运行

只有 description 被官方标为推荐字段。描述应写清楚“做什么”和“何时使用”，避免多个 Skill 描述高度重叠。

2.5 参数与动态上下文

Skill 可以使用：

$ARGUMENTS

也可定义具名参数。动态命令：

## 当前差异

!`git diff HEAD`

Claude Code 会在 Skill 正文进入上下文前运行命令并替换输出。动态命令会执行本机程序，不要在来源不可信的 Skill 中使用，也不要让它无界读取日志或输出 Secret。

2.6 支持文件

.claude/skills/release/
├── SKILL.md
├── checklist.md
├── templates/
│   └── release-notes.md
└── scripts/
    └── validate-release.sh

SKILL.md 应说明何时读取支持文件。把所有参考内容直接塞入主文件会让 Skill 一旦加载就长期占用大量上下文。

2.7 测试 Skill

/skills
/fix-issue 128

检查：

• 是否出现在预期作用域；
• 自动触发策略是否正确；
• 参数是否传入；
• 工具范围是否足够但不过宽；
• 是否给出验证证据；
• 是否意外执行外部写操作。

Skill 目录在会话开始时已存在时，正文编辑通常可实时生效；首次新建顶层目录后，必要时重启会话。

3. 自定义子代理

3.1 子代理的价值

子代理在自己的上下文中执行任务，只把结果返回主会话。适合：

• 读取很多文件的调查；
• 安全审查；
• 测试缺口分析；
• 并行独立任务；
• 需要专门模型或工具范围的角色；
• 不希望中间日志污染主上下文的工作。

它不适合需要持续获得主会话全部细节、频繁与用户互动的小任务。

3.2 位置与优先级

来源	位置或方式	优先级
Managed	组织下发	最高
CLI	--agents JSON	当前会话
项目	.claude/agents/	项目共享
用户	~/.claude/agents/	跨项目
插件	<plugin>/agents/	最低

项目 Agent 应提交到版本控制并接受团队审查。

3.3 创建只读安全审查 Agent

.claude/agents/security-reviewer.md：

---
name: security-reviewer
description: 审查认证、授权、输入校验、注入、凭据和敏感数据处理；在安全审查或修改认证相关代码后使用
tools: Read, Grep, Glob
model: opus
permissionMode: plan
maxTurns: 12
---

你是 task-board 项目的只读安全审查员。

只报告具有明确触发路径和实际影响的问题。每项必须包含：

1. 严重度；
2. 文件与符号位置；
3. 攻击或失败前提；
4. 数据流证据；
5. 影响；
6. 最小修复方向；
7. 建议的回归测试。

不要修改文件，不执行网络请求，不报告纯风格问题。
无法证实时明确标记为待验证假设。

调用：

使用 security-reviewer 审查 Idempotency-Key 实现，
重点检查跨用户键冲突、请求体摘要、日志泄露和重放窗口。

当前版本中 /agents 不再打开创建向导，而是提示用户询问 Claude 或直接编辑 Agent 文件。旧教程中依赖 /agents 向导的步骤已经过时。

3.4 常用字段

字段	作用
name	唯一小写标识
description	Claude 何时委派
tools	可用工具列表
disallowedTools	从继承列表移除工具
model	inherit、模型别名或完整 ID
permissionMode	Agent 权限模式
maxTurns	最大代理轮次
skills	启动时完整预载的 Skills
mcpServers	Agent 可用 MCP
hooks	仅该 Agent 的 Hooks
memory	用户、项目或本地持久记忆
background	默认后台执行
isolation	worktree 文件隔离
effort	推理强度

只有 name 和 description 必需。

3.5 工作树隔离

允许子代理修改代码时：

---
name: refactorer
description: 在独立工作树完成机械重构
tools: Read, Grep, Glob, Edit, Bash
isolation: worktree
---

主会话应明确如何接收结果：提交、分支或补丁。不要让多个子代理在没有隔离的情况下并行编辑同一文件。

3.6 前台与后台

当前版本通常让子代理在后台运行。主会话可继续工作，通过 /tasks 查看后台项。需要结果后才能继续的严格顺序任务，应明确前台或要求主会话等待结果。

后台子代理的文件变化与主会话检查点并不等价。需要可恢复历史时使用 Git worktree 和提交。

3.7 子代理的上下文

自定义子代理一般加载其系统提示、项目 CLAUDE.md、Git 状态和明确预载的 Skills，但不继承主会话完整历史。内置 Explore 与 Plan Agent 还有不同的启动内容。

委派提示应自包含：

错误：检查一下刚才那个问题。

正确：只读检查 src/services/task-service.ts 中 Idempotency-Key 实现。
需求在 SPEC.md 第 3 节；重点验证并发事务和 409 冲突。
返回文件位置、证据和测试缺口。

4. Hooks

4.1 Hooks 与自然语言指令的区别

Hook 在生命周期事件发生时确定性触发，可以：

• 编辑后格式化；
• 工具调用前阻止操作；
• 权限提示时给出决策；
• 会话结束后归档；
• 压缩后重新注入关键上下文；
• 记录配置变化；
• 通知用户；
• 执行测试作为完成门槛。

“一定要执行”的动作使用 Hook；需要模型判断和灵活应用的流程使用 Skill。

4.2 配置位置

Hooks 写在设置文件的 "hooks" 字段，不存在普通项目级独立 hooks.json：

{
  "hooks": {
    "PostToolUse": []
  }
}

插件可以有自己的 Hook 文件结构，但普通用户和项目设置仍应放在 settings.json。

查看：

/hooks

当前 /hooks 界面主要用于查看，修改应编辑设置文件或让 Claude 编辑。

4.3 编辑后格式化

.claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Hook 从标准输入接收 JSON。示例依赖 jq 和 xargs，在 Windows 原生环境中应编写等价 PowerShell 脚本，不要直接复制 Unix 管道。

格式化 Hook 会修改文件。应确认格式化器受项目依赖锁定，且不会对不支持的文件批量重写。

4.4 保护已发布迁移

最可靠的方式是将判断逻辑放到项目脚本，并让 PreToolUse 调用。Hook 读取 .tool_input.file_path，当目标属于已发布迁移时向 stderr 输出原因并以退出码 2 结束。

注册：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-migrations.sh"
          }
        ]
      }
    ]
  }
}

脚本必须：

• 解析 JSON，而不是对原始字符串做脆弱匹配；
• 规范化路径并防止 ..、符号链接绕过；
• 明确维护“已发布迁移”的来源；
• 默认失败关闭；
• 不输出 Secret；
• 有独立测试。

简单路径保护也应同时使用 Edit deny。Hook 适合实现更动态的规则。

4.5 常用事件

事件	时机
SessionStart	新建或恢复会话
UserPromptSubmit	Claude 处理用户提示前
PreToolUse	工具执行前，可阻止
PermissionRequest	即将显示权限对话框
PostToolUse	工具成功后
PostToolUseFailure	工具失败后
Notification	Claude Code 发出通知
SubagentStart / SubagentStop	子代理开始或结束
Stop	Claude 准备结束当前轮次
ConfigChange	配置发生变化
PreCompact / PostCompact	上下文压缩前后
SessionEnd	会话结束
WorktreeCreate / WorktreeRemove	工作树创建或移除

完整事件和输入 schema 必须查阅 Hooks reference。不要依据事件名称猜测 JSON 字段。

4.6 退出码与 JSON

命令 Hook 常见约定：

• 0：成功；
• 2：在支持阻止的事件中阻止，并把 stderr 作为反馈；
• 其他非零：通常作为非阻断错误，具体取决于事件。

需要允许、拒绝、修改输入或附加上下文时，退出 0 并只在 stdout 输出符合事件 schema 的 JSON。

不要同时“退出 2”又期望 JSON 被解析；官方说明 JSON 只在退出 0 时处理。

4.7 Hook 安全

Hook 会自动执行本机代码。检查：

• 项目 Hook 是否来自可信仓库；
• 命令参数是否正确引用；
• 是否存在命令注入；
• 是否使用绝对或基于 $CLAUDE_PROJECT_DIR 的路径；
• 是否设置超时；
• 是否把完整工具输入写入公共日志；
• 是否意外访问网络；
• 是否在每次编辑后运行昂贵全量测试；
• 是否会无限阻止 Stop。

5. MCP

5.1 MCP 解决什么

Model Context Protocol 让 Claude Code 通过服务器访问外部工具和数据，例如：

• Issue 和 Pull Request；
• 监控告警；
• 数据库；
• 设计稿；
• 浏览器；
• 文档系统；
• 团队聊天。

当用户不断从另一系统复制数据到 Claude Code 时，MCP 是候选方案。MCP 提供连接，Skill 可以补充“如何正确使用”。

5.2 连接官方文档 MCP

Claude Code 官方 Quickstart 提供文档 MCP 示例：

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

检查：

claude mcp list
claude mcp get claude-code-docs

进入会话：

/mcp

使用：

使用 claude-code-docs MCP 查找 MCP_TIMEOUT 的当前含义和适用范围。

删除：

claude mcp remove claude-code-docs

5.3 三种作用域

作用域	配置位置	范围
local	~/.claude.json 的项目条目	仅自己、当前项目；默认
project	项目根 .mcp.json	团队共享
user	~/.claude.json 顶层	仅自己、所有项目

示例：

claude mcp add --scope user --transport http \
  claude-code-docs https://code.claude.com/docs/mcp

claude mcp add --scope project --transport http \
  claude-code-docs https://code.claude.com/docs/mcp

Project MCP 会写入 .mcp.json。协作者首次加载时必须审批，防止克隆仓库后静默启动本机程序。

5.4 本地 stdio Server

官方示例使用 Playwright MCP：

claude mcp add playwright -- npx -y @playwright/mcp@latest

-- 后是 Claude Code 启动 Server 的命令。npx -y 可能从网络下载并执行包，只能对可信包使用；生产和企业环境应固定版本并经过供应链审查，而不是长期依赖 @latest。

5.5 .mcp.json

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@<reviewed-version>"
      ]
    }
  }
}

不要把 mcpServers 写进 .claude/settings.json；项目 MCP 配置位于仓库根 .mcp.json。

5.6 凭据与 OAuth

远程 MCP 可能通过浏览器 OAuth 登录：

/mcp

选择 Server 后 Authenticate。

静态 Token 可通过 Header 或环境变量配置，但不得把真实 Token 提交到 .mcp.json。项目配置可使用官方支持的环境变量展开方式，并由每个用户或 CI 注入。

审查第三方 MCP：

• Server 维护者与代码来源；
• 工具会读取和写入什么；
• OAuth Scope；
• 数据发送位置与保留策略；
• 是否可执行任意本地命令；
• 是否包含提示注入内容；
• 是否真的需要 Project 作用域；
• 是否可以只给只读权限。

5.7 MCP 上下文成本

连接过多 Server 会增加工具名称和说明。Claude Code 默认使用工具搜索延迟加载完整 schema，但空闲 Server 仍有成本。

/mcp

查看状态和上下文成本，断开不再使用的 Server。

6. 插件

6.1 插件是什么

插件是分发层，可包含：

• Skills；
• Agents；
• Hooks；
• MCP Servers；
• LSP Servers；
• 主题和其他扩展组件。

当第二个仓库需要同一套配置，或团队希望通过 Marketplace 管理版本时，应考虑插件，而不是复制多个 .claude/ 目录。

6.2 浏览官方 Marketplace

进入会话：

/plugin

界面通常包括 Discover、Installed、Marketplaces 和 Errors。安装前检查详情中的：

• 组件清单；
• 上下文成本；
• 更新时间；
• 来源和主页；
• MCP、Hook 或可执行程序。

官方 Marketplace 会自动可用。第三方 Marketplace 需要明确添加。

6.3 安装与作用域

/plugin install <plugin-name>@<marketplace-name>

作用域：

• User：个人所有项目；
• Project：项目团队共享，写入 .claude/settings.json；
• Local：个人当前项目。

Shell 中也可：

claude plugin install formatter@your-org --scope project

安装或启用后：

/reload-plugins

插件 Skill 使用命名空间：

/plugin-name:skill-name

6.4 代码智能插件

对 TypeScript、Python、Rust 等类型化语言，官方推荐安装对应 code intelligence 插件。它通过 Language Server 提供：

• 跳转定义；
• 查找引用；
• 类型信息；
• 符号和调用层次；
• 编辑后自动诊断。

这比纯 Grep 更精确，并可能减少读取整个文件的上下文成本。插件本身不安装所有语言运行环境时，仍需按插件说明准备 Language Server。

6.5 插件安全

Anthropic 官方提醒：安装前必须信任插件。即便 Marketplace 提供目录，插件仍可能包含 MCP Server、Hook、脚本和其他软件。

项目作用域插件会影响信任仓库的协作者。团队应：

• 固定来源与版本；
• 审查更新；
• 限制允许的 Marketplace；
• 检查插件依赖；
• 在测试项目验证；
• 使用 /plugin 查看未使用和错误插件；
• 删除不再需要的插件。

7. 组合设计

为 task-board 构建一套合理组合：

CLAUDE.md
  └── 始终提供构建、架构和工作流约定

.claude/rules/
  └── 只在 API 或迁移路径加载细则

/fix-issue Skill
  └── 复用 Issue 修复流程

security-reviewer Agent
  └── 独立上下文只读审查

PostToolUse Hook
  └── 每次编辑后格式化

PreToolUse Hook + Edit deny
  └── 阻止已发布迁移被修改

GitHub MCP
  └── 获取 Issue 与 PR 数据

TypeScript code intelligence plugin
  └── 符号导航与类型诊断

应避免：

• 把完整 API 文档放进 CLAUDE.md；
• 让 Skill 负责必须无条件执行的安全拦截；
• 用子代理完成一句话就能回答的小问题；
• 安装大量从未使用的 MCP 与插件；
• 让第三方 Plugin 获得未经审查的发布权限；
• 用 Hook 输出几万行日志回填上下文。

8. 调试扩展

8.1 总览

/context       查看 Skill、Agent、MCP 和记忆的上下文占用
/skills        查看 Skills
/hooks         查看 Hooks
/mcp           查看 MCP 连接与审批
/permissions   查看权限
/status        查看设置来源
/doctor        检查重复 Agent、无效配置和未使用扩展

Shell：

claude doctor
claude --safe-mode

8.2 Skill 不出现

错误：

.claude/skills/fix-issue.md

正确：

.claude/skills/fix-issue/SKILL.md

如果目录在会话启动后首次创建，重启会话。

8.3 Hook 不触发

检查：

• Hooks 是否位于 settings.json 的 "hooks"；
• matcher 是否是字符串而不是数组；
• 工具名大小写是否正确；
• Edit|Write 是否写成有效匹配；
• 脚本是否可执行；
• stdout 是否混入非 JSON 内容；
• Windows 与 Unix 命令是否匹配当前 shell。

调试：

claude --debug hooks

8.4 MCP 不出现

检查：

• 项目文件是否为根目录 .mcp.json；
• 是否从另一个项目添加了 local Server；
• Project Server 是否尚未批准；
• stdio 命令是否使用错误相对路径；
• 需要的环境变量是否应放在 Server 自己的 env；
• /mcp 是否显示认证或连接错误。

claude mcp list
claude mcp get <name>

8.5 Plugin 变更不生效

/reload-plugins

然后检查：

/plugin
/context

下一篇将把 Claude Code 作为可组合的命令行程序使用：非交互 -p、--bare、JSON 与流式输出、权限预算、模型与 Effort、成本控制，以及一套从 /context 到 Safe mode 的系统排障流程。

参考资料

• Extend Claude Code
• Extend Claude with skills
• Create custom subagents
• Automate actions with hooks
• Hooks reference
• Connect to MCP servers
• Connect Claude Code to tools via MCP
• Discover and install plugins
• Plugins reference