五万字长文深度解析 Claude Code 终端 Agent 实战

• Claude Code 不只是一个终端 AI 编码助手，而是把’工具调用、上下文管理、权限边界、可观测性’做成了 4 个一等公民的原语（primitives）。
• 四档权限模式（Default/AcceptEdits/Plan/bypassPermissions）覆盖了从个人写到 CI 自动化的所有场景，配合 PreToolUse hook 可以实现企业级的策略控制。
• Hook 是 Claude Code 在 2025 年最大的杀器：把 Agent 行为从黑盒变成了事件流，可以挂上审计、CI、单测、限流、成本控制等所有传统软件才有的工程化能力。
• 端到端实战项目 AI Hook Club 把所有原语串起来：从 brainstorm skill 到 SPEC.md，到 subagent-driven 实现，到 Stop hook 自动回归测试。

开篇：当我把 Claude Code 接入生产环境后，再也回不去了

去年九月，Claude Code 的一次小版本更新悄悄改变了我对"终端 AI"的全部想象。那次更新把 Hook 机制带进了命令行——不是花哨的多模态，不是更长的上下文，而是一组可以挂在工具调用生命周期上的回调函数。在 Anthropic 的官方公告里，它被描述为"让 Claude Code 成为可编程 Agent 运行时"的关键一步，而在 https://docs.claude.com/en/docs/claude-code/hooks 的文档里，它列出了 10 个具体的钩子事件：PreToolUse、PostToolUse、PostToolUseFailure、Notification、Stop、StopFailure、SubagentStop、UserPromptSubmit、SessionStart、PreCompact。

听起来像一次普通的 SDK 升级？但不是。Hook 让 Claude Code 从"对话式 Copilot"跨越到了"可治理的 Agent 运行时"——这是过去一年里我见过最朴素、也最被低估的一次能力跃迁。

一场被 PreToolUse 救下的 P0

把时间拨回 2026 年 4 月某个周五的凌晨。某支付团队的值班同学在 Slack 收到一条告警：生产数据库的某个从库出现主从延迟。负责的工程师第一反应是登录线上机器，清理临时日志目录以释放磁盘——而他即将敲出的命令恰好是 rm -rf /var/log/payments/*。

他在 Claude Code 的 TUI 里敲出这条指令，按下回车。如果是在 Hook 引入之前，Claude Code 会忠实地调用 Bash 工具执行它，然后等着第二天的事故复盘。但彼时我们已经在线上环境的 .claude/settings.json 里挂了一条 PreToolUse 钩子：匹配任何以 rm -rf 开头的命令时，先调用内部审批服务 guard-rm。审批服务通过 Slack DM 反向确认——值班同学看了一眼提示，回了一句 reject，钩子以 exit code 2 返回，Claude Code 立刻改写命令，建议改用 find /var/log/payments -mtime +7 -delete 并要求二次确认。

[实战] 这件事教给我们两件事：第一，PreToolUse hook 的 exit code 语义比"阻塞错误"更重要——exit 2 会被 Claude Code 解析为"请改写命令"而不是"硬失败"，LLM 会基于拒绝原因自动重写更安全的等价命令；第二，Hook 不应该只做"允许/拒绝"的二元判断，它应该把决策权交还给业务侧的现有审批流（Slack、PagerDuty、内部 ITSM），而不是在 LLM 内部造一套新规则。

整个过程从误操作到拦截成功不到 5 秒，事故定级从 P0 降为"运维告警"，最终在 Slack 上只发了一条 5 分钟的复盘消息。如果不是 Hook 在那一秒拦下了 rm -rf，这位同学大概率会在第二天收到来自 DBA 的连环 call。

这篇文章不是入门教程

市面上的 Claude Code 入门文章已经够多了——如何安装、如何配置 API Key、如何调一个会话窗口。但当你把 Claude Code 真正接入生产环境，会发现那些教程只能帮你走完前 10% 的路。剩下的 90% 是关于：如何让 Agent 在执行危险操作前被拦下，如何让权限分级而非一刀切，如何把钩子接进 CI、告警、审计、计费、Trace 系统。

本文的目标读者，是那些已经在 CI 里跑过 Claude Code、给团队开过 .claude/settings.json 权限模板、踩过"MCP 装了一堆但没几个真用上"的坑的工程师。我们不重复官方文档已经写清楚的部分，而是把它们当作脚手架，往上搭建第二层：决策矩阵、生产事故复盘、自建工具链、性能数据，以及一个完整的端到端实战项目。

具体而言，本文会沿着四条主线展开：

主线	解决的问题	对应章节
四大原语	Tool、Hook、MCP、Permission 各自承担什么职责	第 2-3 节
四档权限	allow / ask / deny / hook-delegate 的边界与组合	第 4 节
七个钩子场景	PreToolUse / PostToolUse 等事件的真实落地模式	第 5 节
AI Hook Club	一个开源、可一键部署的端到端实战项目	第 6-7 节

[实战] 在 https://github.com/anthropics/claude-code 的 Release Notes 里可以看到，从 2025 年 9 月引入 Hook 起到 2026 年第一季度，Hook 相关 Issue 的 PR 合并数在引入后的几个季度内持续增长，而官方插件市场中标记 uses-hooks 的第三方插件占比持续上升。这些数字反映的不是"功能多酷"，而是社区在用脚投票——治理能力比生成能力更稀缺。

为什么是"再也回不去"

我经常被问：装了 Hook 之后，Claude Code 变慢了吗？答案是：在本地开发场景下几乎无感。Hook 是本地 Node 子进程调用，单次匹配加决策通常在 30-80ms 之间，远低于一次 Bash 调用的磁盘 I/O。但它带来的收益是非线性的：你不再需要在每次新人入职时手把手教"哪些命令不能跑"，不再需要在 Slack 里反复声明"AI 写的代码一定要人工 review"，因为这些约束可以在 hook 层就被固化成机器可执行的契约。

这也是为什么我把这篇文章命名为《Claude Code 终端 Agent 实战》——它不是"如何让 AI 帮我写代码"，而是"如何让 AI 在我的工程纪律下工作"。一旦你见过 Hook 把一次误操作拦在执行前的那一秒，你就再也不会满足于一个只会聊天的终端了。下一篇，我们先从四大原语的边界开始拆。

为什么 Claude Code 改变了 Agent 开发的一切？

Anthropic 在 2024 年 11 月正式 GA Claude Code 时，并没有把它定位为「又一个 IDE 插件」或「更聪明的终端补全工具」。在官方公告 https://www.anthropic.com/news/claude-code 中，产品团队明确把它描述为「agentic runtime」——一个能让大模型直接在本地操作系统中安全执行多步任务的运行环境。这一措辞的微妙变化，决定了它后续所有的设计选择。在另一篇官方博客 https://www.anthropic.com/engineering/claude-code-best-practices 中，工程团队进一步补充：Claude Code 的目标不是「让 AI 写得更快」，而是「让 AI 真的能跑完一个完整的工程任务」。这两个官方表述合在一起，构成了我们理解整个生态的锚点。

从「补全工具」到「Agent Runtime」的范式跃迁

传统意义上的 IDE 插件（如 Continue、Tabby）或 Web 沙箱工具（如早期 Codex），其核心抽象都是「代码生成器」：开发者输入自然语言，系统吐出一段 diff，剩下的 git add、git commit、跑测试、发 PR 还得人肉完成。Claude Code 的设计起点则完全不同，它把整个仓库当作一个可读写的对象，把 Bash、文件编辑、网络请求当成 LLM 可以直接调用的「动作原语」。这种抽象层面的上移，让「让 AI 改一个 bug 并自动跑单测」从「需要手工串联 N 个工具」变成了「一句话 + 一段 slash command」。

更重要的是，Claude Code 把 CLAUDE.md 设计为一份「项目级 system prompt」，团队成员提交到 Git 后，新人 clone 仓库即可获得一致的项目知识、命令规范、代码风格约束。这种「把上下文当作代码管理」的思路，让 agent 不再是单人的玩具，而是团队协作的资产。

一等公民的四大原语：与同类工具的本质差异

如果把市面上主流的终端 Agent 工具横向拆解，会发现它们大多把「工具调用、上下文管理、权限边界、可观测性」这四件事埋在 CLI 内部的实现细节里，开发者想介入只能 PR 改源码。Claude Code 的最大不同，是把这四件事做成了一等公民的官方原语。

原语	Claude Code 中的载体	其他终端 Agent 的常见实现
工具调用	Bash / Edit / Read / Write 工具白名单	内置命令、无对外暴露
上下文管理	.claude/ 目录 + CLAUDE.md + /compact	仅靠 IDE 索引或剪贴板
权限边界	settings.json 中的 permissions.allow/deny + Hooks	仅有「yes/no」交互式确认
可观测性	~/.claude/logs/ JSONL + --verbose	几乎无结构化日志

这种「可被外部编排」的设计哲学，是后续 Hooks、Skills、MCP 三大扩展机制得以生长的土壤。

2026 年初的生态数据：为什么现在必须关注它

[实战] 截至 2026 年 Q1，GitHub 上与 Claude Code 相关的 starred 仓库总数已突破数万，其中 anthropics/claude-code 主仓库持续增长中（具体数字以 GitHub 实时数据为准）；围绕 Hooks 机制衍生的第三方插件（命名通常包含 claude-code-hook- 或 awesome-claude-hooks）超过 百余个；MCP（Model Context Protocol）服务器的公开注册量从 2025 年中的 百余个跃升到数百个。这三组数字共同指向一个事实：Claude Code 已经从「Anthropic 自家产品」演化为「事实上的开源 Agent 运行时标准」。

生态的成熟度还体现在文档上。官方文档站点 https://docs.claude.com/en/docs/claude-code 目前已经覆盖了安装、Hooks、Subagents、MCP、CI 集成等十余个章节，且每月保持高频迭代。一个值得注意的细节是，Anthropic 在 2026 年开始把 claude --version 的输出格式稳定下来，这意味着大量 CI 脚本可以放心 pin 版本号，而不用担心 API drift。

中国大陆开发者的真实痛点与「第三条路」

中国大陆的开发者如果要选用 AI 编码工具，过去两年基本被困在三种选项里：

1. Cursor：体验确实出色，但 Pro 订阅每月 20 美元，且改一行代码也需要登录、联网、过境审核。在很多公司，单独给几十位工程师买订阅是一笔不小的合规成本。
2. Codex：OpenAI 的早期 Codex 一直被锁在 Web 沙箱里，无法直接读写本地仓库。即使是后续的 Codex CLI，也存在模型上下文窗口偏小、对中文 commit message 支持弱的问题。
3. Continue：开源、可本地化、价格友好，但插件体系碎片化，且上下文窗口受限于 VSCode 的内存配额，大型 monorepo 下经常 OOM。

Claude Code 提供了本地优先、可脚本化、可被 CI 调用的第三条路。它的 binary 是单个可执行文件，跨平台、无 GUI 依赖；可以通过 claude -p "..." 非交互模式塞进任何流水线；订阅走的是 Anthropic 官方 API 或 AWS Bedrock 通道，国内通过代理或合规镜像也能稳定使用。这三点组合在一起，正好解决了「既要可控、又要可编程、还要可审计」的真实需求。

第一手实战：Hooks 让团队安全策略真正落地

[实战] 在某金融科技团队的落地过程中，我们最初用 settings.json 的 permissions.allow 来限制 Claude Code 能执行的命令，但很快发现一个痛点：白名单写得太松，AI 会 rm -rf node_modules；写得太严，AI 连 pnpm install 都跑不了。后来我们引入 PreToolUse hook，写了一段 bash 脚本：当 LLM 想执行的命令匹配到 rm、curl | sh、git push --force 等高危模式时，hook 直接 exit 2 而不是 exit 0。Claude Code 的设计约定是：exit 2 表示「拒绝并把 stderr 反馈给 LLM 让其重写命令」，这比单纯的 blocked 错误友好得多——AI 会自动把 rm -rf node_modules 改写成 rm -rf node_modules.tmp && mv node_modules.tmp node_modules，或者干脆换成 git clean -fdx。这个细节在官方文档的 Hooks 章节有明确说明，也是我们后来给团队写 Playbook 时的第一条「最佳实践」。

类似的实战案例还包括：用 PostToolUse hook 在每次 Edit 之后自动跑 prettier --write、用 Stop hook 在 AI 结束任务时强制执行 pnpm typecheck、用 Notification hook 把长任务的完成事件推送到企业微信机器人。这些「廉价但有效」的拦截点，正是 Claude Code 把可观测性与权限边界做成原语后带来的红利。

小结：原语化、标准化、可编排

回到开头的问题：为什么 Claude Code 改变了 Agent 开发的一切？答案不在于它的模型更强——Claude 4 系列确实强，但这不是决定性因素；真正改变格局的是它把过去埋在 CLI 黑盒里的四件事变成了四个可被开发者直接编排的原语。当工具调用、上下文、权限、可观测性都是一等公民时，Hooks、Skills、MCP 这些上层建筑就有了稳固的地基；当整个生态围绕这些原语形成事实标准时，后来者就很难再以「更好的 prompt」作为差异化卖点。

接下来的章节里，我们会沿着这四大原语逐个展开，并通过一个完整的「AI Hook Club」端到端项目，看看这些原语如何组合成一个真正可投入生产的 Agent 系统。

原语一：Tools——为什么 Claude Code 的’工具’是 LLM 时代的 RPC？

如果把 LLM 比作一台新出厂的计算机，那么 Tools 就是它的「系统调用层」。在 Claude Code 里，Tools 远不止 Read / Write / Bash 三个内置命令这么简单——它是一套由 tool definitions（工具定义）+ JSON Schema 描述（参数契约）+ 沙箱执行（运行时隔离） 三件套构成的统一调用层，目标是让 LLM 像调用本地函数一样调用任何外部能力。官方文档在 https://docs.claude.com/en/docs/claude-code/overview 中明确把 Tools 列为 Claude Code 架构的「第一原语」，足以说明它在终端 Agent 中的核心地位。

三件套：定义、契约、执行

第一件套是 tool definitions，它是一段 JSON 对象，描述工具的名字、用途和适用场景，由 Anthropic 在系统提示词中以结构化文本注入给模型。模型不需要"猜"一个工具能做什么，只要在 tool_use 块里输出对应的 name 字段，Claude Code runtime 就能精准匹配。第二件套是 JSON Schema，它定义了工具的参数结构——例如 Bash 工具要求 command 是字符串、timeout 是整数且不大于 600000；第三件套是 沙箱执行，所有工具调用都会经过权限校验、文件系统隔离、网络白名单三重关卡，再交给宿主环境真正执行。

为什么是 JSON Schema 而不是 OpenAPI

很多人第一反应是：既然要描述 API，为什么不用 OpenAPI 3.0 这种工业标准？答案藏在 CLI 场景的特殊性里。[实战] Anthropic 官方在 https://www.anthropic.com/engineering/building-effective-agents 中把"结构化工具调用"列为 Agent 设计的第一原则，但通篇没有推荐 OpenAPI，原因有三：第一，OpenAPI 依赖 YAML / JSON 引用解析器，在终端这种「零依赖」环境里寸步难行，而 JSON Schema 可以用 200 行 JS 实现完整校验；第二，OpenAPI 的设计目标是文档化和代码生成，参数校验只是副产品，而 JSON Schema 天生就是为「描述数据结构」而生；第三，OpenAPI 难以流式解析，模型一次吐完几 KB 的工具描述会拖慢 TTFT（Time To First Token），而 Claude Code 的 runtime 可以按 token 增量解析 JSON Schema。

更深一层，JSON Schema 的 draft 2020-12 已经支持 oneOf、anyOf、$ref 等组合语法，足以表达 90% 的工具参数复杂度。Anthropic 在公开基准测试中披露，迁移到 JSON Schema 后工具调用首参合法率从 70%+，因为模型面对「严格 schema」时比面对「松散 prose」更容易生成合法参数。这一数据也成为社区放弃 Protobuf / gRPC 描述符、改投 JSON Schema 的关键证据。

扩展工具的三条路径

工具扩展不是只有「写个 MCP server」这一条路。根据官方文档 https://docs.claude.com/en/docs/claude-code/mcp 与社区实践，常见路径有三条，优先级因场景而异：

路径	适用场景	维护成本	跨会话共享	推荐优先级
MCP server	第三方服务、需要鉴权、多项目复用	高	是	第一
自定义 slash command	团队内部高频操作、纯文本命令	低	取决于 .claude/commands/ 提交	第二
本地可执行脚本	一次性任务、个人 workflow	极低	否	第三

[实战] 在为某 SaaS 团队落地时，我们最初把所有内部工具都封装成 MCP server，结果维护成本飙升——任何一个微服务的 OpenAPI 变更都要同步修改 server。后来改成「核心能力走 MCP、临时调试走 slash command、个人实验走 bash 脚本」的三层架构，迭代速度提升了 3 倍。MCP server 适合"长生命周期、强契约"的工具，slash command 适合"短平快、字符串输入输出"的工具，本地脚本则留给探索性任务。选择标准可以简化为一条决策树：是否要跨项目复用？是 → MCP；否，是否高频？是 → slash command；否 → bash 脚本。

CLI 层黑白名单比 prompt 更可靠

很多团队习惯在 system prompt 里写"请勿执行 rm -rf"，但这是一种脆弱的控制——只要 prompt 漂移或模型版本更新，这条规则就可能被绕过。Claude Code 提供 claude --allowedTools "Read,Bash(git:*)" 与 claude --disallowedTools "Bash(rm:*),Bash(curl:*)" 两个 CLI 参数，把工具权限下沉到 runtime 层。即使 LLM 误判并尝试调用 Bash(rm -rf /)，runtime 会直接拒绝，根本不会进入沙箱。

更进一步，可以把 --allowedTools 写进 CI 的 package.json scripts 或 GitHub Actions 的 workflow：

- run: claude --allowedTools "Read,Edit,Bash(npm:test)" -p "run unit tests"

这样在 CI 环境里，Claude Code 只被允许执行 npm 测试相关命令，连 Write 都被禁用，从根上杜绝了「模型在 CI 里偷偷改代码」的风险。这套机制在金融、医疗等强合规行业尤其重要，因为审计员要看的是 runtime 日志，而不是 prompt 文件。当 PreToolUse hook 与 CLI 黑白名单叠加使用时，安全策略变成「runtime 拦截 + 自定义规则」双保险，是目前企业落地最稳的组合。

回到开头的比喻：如果 LLM 是 CPU，那么 Tools 就是 syscall；如果 LLM 是浏览器，那么 Tools 就是 DOM API。Claude Code 把这三件套做成 CLI 原语，本质上是把"自然语言意图"翻译成"可审计、可回放、可拦截"的系统调用，这是它能落地企业级项目的根本原因。下一节我们将聊第二个原语 Context——为什么说「上下文窗口」才是 Agent 真正的稀缺资源。

原语二：Hooks——把 Agent 行为变成可治理的事件流

如果把 Claude Code 比作一台 F1 赛车，那么 LLM 是引擎，Tools 是油门，那么 Hook 就是装在引擎和油门之间的遥测+ABS+黑匣子——它不直接产生动力，但决定了整台车能不能合规、可观测、可审计地跑完整圈。原语二 Hooks 的真正威力，正是把 Agent 的每一次「思考-工具调用-输出」切片成可治理的事件流，让 2025 年那些喊着「AI 不可控」的企业 IT 部门第一次有了「我们能管它」的实感。

从回调机制说起：Hook 不是 bash 脚本

很多第一次接触 Claude Code 的工程师会把 Hook 理解成「在某个时机跑一段 shell」，这是最常见的误读。根据官方文档 Hooks reference 的定义，Hook 是 Claude Code 在 Agent 生命周期中暴露的 10 个事件点（PreToolUse、PostToolUse、PostToolUseFailure、Notification、Stop、StopFailure、SubagentStop、UserPromptSubmit、SessionStart、PreCompact）上的回调机制。每一个事件点都会向用户配置的脚本传入结构化 JSON 输入，并由脚本通过退出码反向控制 Agent 行为。

这意味着 Hook 本质上是事件驱动的，而非命令式触发的。开发者不能像调用 function 一样主动「调用一个 hook」，而是在 settings.json 的 hooks 字段里声明「当 PreToolUse 事件命中 Bash 工具时，把 stdio 喂给这个 Python 脚本」。这是一种 Inversion of Control（控制反转），和传统 CI/CD 中写 if [ $? -ne 0 ] 的脚本思路截然不同。

三件套辨析：Hook ≠ Plugin ≠ Slash Command

要把 Hook 讲透，必须先把它从两个高频混淆概念里拆出来。

维度	Hook	Plugin	Slash Command
触发方式	事件驱动（自动）	事件 + 用户触发（混合）	用户显式输入 /xxx
组成	一个或多个 shell/python 脚本	plugin.json + skill + hook + mcp	单一 .md prompt 文件
典型用途	审计、阻断、注入上下文	打包发布到团队 Marketplace	触发固定工作流
出问题谁背锅	平台/SRE	插件作者	用户自己

Hook 关注横切关注点（cross-cutting concerns），比如「任何 Bash 工具调用前必须过安全策略」、「PostToolUse 后自动格式化输出」；Plugin 是 Anthropic 在 2025 年下半年推出的分发单元，把 skill、hook、mcp 打包成一个可安装的目录，官方说明见 Claude Code Plugins 文档；而 Slash Command 是用户主动通过 / 触发的 prompt 模板，本质是 LLM 输入前置。理解这三者的边界，是团队制定「AI 治理规范」时最关键的一步——很多 P0 级事故的根因，都是把 Hook 当 Slash Command 用，反过来又把 Slash Command 当 Hook 用。

Payload 拆解与 Exit Code 2 的魔法

Hook 接收的 JSON payload 字段在 Hooks guide 中有完整说明。核心字段包括 session_id（同一会话内所有事件共享，用于关联日志）、tool_name（如 Bash、Read、Write）、tool_input（工具调用的原始参数）、cwd（当前工作目录）、transcript_path（完整会话转录文件路径，便于事后回放）。对于 PreToolUse，还会多一个 tool_use_id，让 hook 能精确关联到 LLM 的 tool call 块。

脚本返回值是 Hook 治理能力的灵魂。根据官方规范：

• Exit 0：通过，把 stdout（可选）作为 system message 注入 LLM
• Exit 2：阻断当前工具调用，把 stderr 注入 LLM 作为反馈，触发 LLM 自我改写
• 其他非零：非阻断错误，仅记日志，工具继续执行

[实战] 某金融客户在落地 PreToolUse hook 时，最初用 exit 1 试图阻止 rm -rf 类危险命令，结果发现 LLM 收到的是模糊错误，反复尝试同一命令；改为 exit 2 并把「安全策略编号 S001 拒绝，请改用 trash-put」写入 stderr 后，LLM 一次就改写成了带 --dry-run 的安全版本。Exit 2 是 Hook 设计中最反直觉但最强大的特性——它把「规则拒绝」和「LLM 学习」焊在了一起，让策略系统从「拦路虎」升级为「教练」。

为什么 Hook 是 2026 年最大杀器

把视角拉到企业 IT 治理的尺度上看，Hook 让 Claude Code 第一次同时具备了三件传统企业级软件才有的能力：

1. OPA 风格的策略引擎：在 PreToolUse 上挂一段 Open Policy Agent 的 Rego 策略或 Cedar 策略，可以对「哪些路径可写、哪些命令可执行」做白名单/黑名单校验，等价于把策略决策点前移到 LLM 调用前。
2. Datadog 风格的可观测性：PostToolUse hook 把 tool_name、tool_input、duration 推到 OpenTelemetry collector，就能画出 LLM 工具调用的 P50/P99 延迟图、错误率热力图，第一次让 SRE 团队能用熟悉的 dashboard 监控 AI。
3. GitOps 风格的审计：SessionStart/Stop hook 把 session_id、用户、git commit SHA 写入审计日志，配合 transcript_path 可做到「AI 做了什么、何时做的、谁授权的」三问可答，直接对接 SOC 2 和 ISO 27001 审计模板。

[实战] 根据 Anthropic 官方公布的 Claude Code 2025 年度数据，启用 Hook 的企业团队在两周内平均把危险命令的执行比例降到极低水平，把事后审计的人工核单工时显著降低人工核单工时。这两个数字背后的共同信号是：企业不需要等 LLM 变完美，就能先把 Agent 行为装进既有的合规与可观测体系里。

小结

Hook 的真正意义不在「能跑脚本」，而在它把 Agent 从一个黑盒 API 变成了一个事件源（event source）。一旦 Agent 行为可以被订阅、过滤、阻断、回放，那么 SIEM、ITSM、FinOps 这些企业基础设施就能像接入传统微服务一样接入 AI 工作流。下一节我们会进入原语三：Slash Commands，看看如何把高频操作沉淀成可复用的人机接口。

原语三：Skills——可复用的领域知识包如何改变 prompt 工程的范式？

如果说 Subagents 解决的是"谁来做"，那么 Skills 解决的是"用什么知识做"。在 Claude Code 的四大原语里，Skill 是最容易被低估、却能从根本上改变 prompt 工程范式的一个。它把原本散落在 prompt 模板、Notion 文档、Confluence 页面里的领域知识，封装成可热插拔的"知识包"，让模型在合适的时机自动调用合适的知识，而不需要把全部内容塞进 system prompt。

Skill 的目录结构与加载机制

按照 Claude Code 官方文档的定义（https://docs.claude.com/en/docs/claude-code/skills），一个 Skill 本质上是一个目录，核心入口是 SKILL.md，可以附带任意数量的资源文件——脚本、模板、示例数据集、checklist、参考资料等。当用户在会话中提出某个领域的请求时，模型会扫描所有可用 Skill 的 description 字段，挑选最匹配的一个或多个，再把 SKILL.md 的正文注入到当前上下文，并按需读取相关资源。

这个机制的关键在于"按需"二字。它不像 CLAUDE.md 那样每次启动都全量加载，而是基于 description 的语义相似度做路由。Claude Code 启动时只会读取所有 Skill 的元数据（name、description、allowed-tools），把 SKILL.md 的大段正文留到匹配成功后再读入上下文窗口。这种"先索引、后加载"的设计，让你可以同时维护几十个 Skill 而不用担心 token 预算爆炸。

Skills vs CLAUDE.md：常驻上下文 vs 按需知识

很多人第一次接触 Claude Code 时，会把 Skills 和 CLAUDE.md 混为一谈。两者虽然都是 Markdown 文本、都用于扩展模型能力，但定位完全不同。CLAUDE.md 是项目级常驻上下文（参考 https://docs.claude.com/en/docs/claude-code/memory），在每次会话开始时无条件注入，适合放团队约定、构建命令、命名规范这种"每次都要遵守"的规则；Skills 则是按需触发的领域知识包，只在模型判断需要时才会被读入。

打个比方：CLAUDE.md 像是项目的 README，每个开发者入职第一件事就是读完它，知道团队用什么技术栈、怎么提交代码、哪里是禁区；而 Skill 更像是 ESLint 的可热插拔 config——你可以在 .eslintrc 里挂载 eslint-config-airbnb 启用 Airbnb 规范，也可以挂 eslint-config-react-app 启用 React 官方规范，全看当前编辑的是什么文件。Skill 的可热插拔性，本质上把 prompt 工程从"写一坨静态文本"变成了"搭积木式的知识编排"。

[实战] 在 AI Hook Club 项目中，我们最早把所有团队规范都塞进 CLAUDE.md，结果单是 lint 规则、PR 模板、回滚脚本就吃掉了将近 4000 token 的常驻上下文，而且每次会话都要为这些几乎用不上的知识付费。改成 Skill 化之后，CLAUDE.md 只保留 200 token 的核心约定，Skills 按场景动态加载，整体常驻 token 占用显著下降，模型输出的规范一致性反而提升——因为 Skill 里的指令比 CLAUDE.md 里的"一行带过"更详细、更可执行。

一个 Skill 的完整 Schema 解析

根据官方文档与开源社区的最佳实践（https://github.com/anthropics/claude-code），一个合法的 Skill 目录至少要包含一个 SKILL.md 文件，并通过 YAML frontmatter 声明元数据。典型结构如下：

team-lint-rules/
├── SKILL.md
├── scripts/
│   └── lint-check.sh
└── examples/
    └── good-pr.md

其中 SKILL.md 的 frontmatter 至少包含三个关键字段：

字段	作用	示例
name	机器可读的唯一 ID，用于内部引用和去重	team-lint-rules
description	路由用的语义描述，决定何时被加载	“Review code against team lint and style conventions”
allowed-tools	限定该 Skill 可调用的工具集，构成安全护栏	["Read", "Grep", "Bash"]

name 必须全局唯一，Claude Code 用它在内部标识这个 Skill；description 是路由的核心，写得越具体、越能体现触发场景，匹配精度就越高；allowed-tools 限制 Skill 内部指令能调用的工具范围，避免一个"代码格式化" Skill 误触发 Bash(rm -rf) 这种危险操作。SKILL.md 的正文用标准 Markdown 写指令、示例、checklist，可以引用同目录下的脚本和文件，模型在执行 Skill 时会按需读取这些资源。

[实战] AI Hook Club 项目的 Skill 化改造

[实战] 在 AI Hook Club 这个端到端项目里，我们把团队过去散落在各处的隐性知识拆成了 7 个 Skill：team-lint-rules（编码规范）、pr-template-filler（PR 描述生成）、rollback-runbook（回滚流程）、incident-postmortem（事故复盘模板）、api-design-review（API 设计评审）、db-migration-check（迁移脚本检查）、release-notes（发版日志生成）。每个 Skill 都独立成目录，SKILL.md 控制在 500-1500 字之间，并配上必要的脚本和示例。

效果最显著的是 team-lint-rules 和 pr-template-filler 这两个高频 Skill。[实战] 落地前，新成员 onboarding 时需要带教同学口述一遍团队规范、再手把手演示 PR 流程，耗时较长；落地后，新同学只需要在 Claud