Skill 写成 2000 字说明书？Claude 根本不读——路由器思维与渐进式披露

Skill 写得越详细越被忽略，你信不信？

你试着把团队所有的代码审查规范、所有安全检查清单、所有性能优化套路，统统塞进一个 SKILL.md，洋洋洒洒 2000 字。结果呢？Claude 跑 review 的时候，该报的 SQL 注入没报，该揪的 N+1 查询漏了。你以为它"读懂了"，其实它只读了开头三段------后面 1500 字在上下文里被静默丢弃。

这不是模型笨，是上下文膨胀逼出来的选择性失明。Token 池子就那么大，正文越长，注意力越分散，关键的触发条件反而被淹没。正确做法是把 SKILL.md 当路由器，不是说明书。

一、YAML 前置元数据：Skill 的身份证

每个 Skill 顶部那一段 YAML frontmatter，才是 Claude 真正"读"的部分。正文反而是命中之后才加载的二等公民。

yaml 复制代码

---
name: api-doc-generator
  # 唯一标识符，最多 64 字符，省略时用目录名

description: Generate API documentation from source code. Use when
  the user asks to "write API docs", "document endpoints", or
  "create OpenAPI specs". Supports Express, FastAPI, and Spring Boot.
  # 触发描述，最多 1024 字符------路由匹配的真正依据

argument-hint: "[source directory] [output format]"
  # 参数提示，在 / 菜单中显示

disable-model-invocation: true
  # true 时禁止自动调用，只能 /skill-name 手动触发

allowed-tools:
  - Read
  - Grep
  - Glob
  - Write
  - Bash(python:*)
  # 工具白名单，精确控制能力边界

model: haiku
  # 简单任务用 haiku，更快更省

context: fork
  # fork 时在隔离子智能体中执行，不污染主对话
---

frontmatter 里没有"流程详解"，全是身份证字段：name 是名字，description 是触发条件，allowed-tools 是权限边界，disable-model-invocation 决定显式触发还是语义匹配。Claude 在路由阶段只看这些。

二、description 是 Skill 的灵魂

很多人把心思花在正文，description 随便糊一句"帮助用户处理代码相关任务"。这是把灵魂写废了------Claude 路由匹配靠的就是 description 里那几个触发词，不是你正文里写的"第一步、第二步"。

yaml 复制代码

# ❌ Claude 根本不知道何时触发
description: Helps with projects.

# ❌ 只写了做什么，没写触发场景
description: Generates API documentation.

# ✅ 触发词 + 使用场景 + 能力边界
description: Generate API documentation from Express, FastAPI, or
  Spring Boot source code. Use when user asks to "write API docs",
  "document endpoints", "create OpenAPI specs", or mentions
  "Swagger". Supports route detection, request/response schema
  extraction, and authentication requirement marking.

写 description 的三句话公式：前两句说能力（Claude 靠这两句判断意图），中间用 Use when... 枚举用户可能说的关键词，最后限定能力边界。上限 1024 字符，别超。

三、路由器思维：Quick Reference 表才是正文的主角

SKILL.md 的正文不是给你写说明书用的，是给 Claude 当路由表用的。复合型 Skill 最该这么写：

markdown 复制代码

## Quick Reference

| Analysis Type      | When to Use           | Reference                   |
|-------------------|-----------------------|-----------------------------|
| Revenue Analysis   | 收入、营收、销售额     | `reference/revenue.md`       |
| Cost Analysis      | 成本、费用、支出       | `reference/costs.md`         |
| Profitability      | 利润、毛利率、净利率   | `reference/profitability.md` |

Claude 看到这张表就知道：用户问"营收"加载 revenue.md，问"成本"加载 costs.md。正文本身只放路由表和总流程，具体公式全部分散到 reference/ 下，按需加载。

顺便一提，我给雷达鸭（收录中国一人公司赚钱案例的 App，Uni-app+arkTS+UniCloud，华为应用市场+微信小程序）的搜索页写过一份代码审查 Skill，把所有 ArkTS 规范铺了 1800 字在正文里，结果 Claude review 时连 @State 没初始化这种低级问题都没揪出来------后来改成路由器+契约式引用，正文压到 200 字，反而灵了。

四、契约式引用：加载条件 + 路径 + 内容预期

弱引用是另一个坑。你写一句 See reference/revenue.md for more details，Claude 压根不知道何时该去读。

markdown 复制代码

# ❌ 弱引用------Claude 不知道何时加载
See `reference/revenue.md` for more details.

# ✅ 契约式引用------三要素齐全
## Revenue Analysis
When the user asks about revenue growth, ARPU, or revenue composition:
→ Load `reference/revenue.md` for calculation formulas and industry benchmarks.

契约三要素：加载条件 （用户问 revenue growth/ARPU/revenue composition 时）、路径（reference/revenue.md）、内容预期（计算公式和行业基准）。三要素齐全，模型才知道"哦，现在该去读这个文件了"。

五、渐进式披露：别一次性把正文喂完

把上面三步串起来，就是渐进式披露的完整链路：

路由阶段：Claude 只看 frontmatter 的 description，判断要不要进入这个 Skill。
命中后：加载 SKILL.md 正文，但正文里只有 Quick Reference 路由表和总流程。
深度执行：根据契约式引用，按需加载 reference/*.md 里的具体公式/规范。

每一层只加载当下需要的，上下文窗口始终干净。你写的 2000 字"详细流程"，拆成 5 个 reference 文件分散加载，比一次性塞进去强 10 倍。

六、权限设计模板：最小权限，禁止 `Bash(*)`

Skill 的 allowed-tools 不是越宽越好，是越精确越好。Harness 给了四套现成模板：

yaml 复制代码

# 审计类：严格只读
allowed-tools: [Read, Grep, Glob]

# 生成类：可写不可改
allowed-tools: [Read, Grep, Glob, Write]

# 分析类：只读 + 特定脚本
allowed-tools: [Read, Grep, Glob, Bash(python:*)]

# 执行类：受控命令
allowed-tools:
  - Read
  - Bash(git status:*)
  - Bash(git add:*)
  - Bash(git commit:*)
  - Bash(npm test:*)

Bash 的精细控制语法记一下：Bash(git:*) 允许所有 git 子命令，Bash(git log:*) 只允许 log，Bash(./scripts/*:*) 只允许 scripts 目录。Bash(*) 等于授权所有 shell，禁用。代码审查 Skill 给 Read/Grep/Glob 就够，给 Write 就是给自己挖坑。

七、$ARGUMENTS 和 `!`command``：动态上下文注入

任务型 Skill 经常要接参数、要感知当前环境。两个语法搞定：

yaml 复制代码

---
name: migrate-component
description: Migrate a component between frameworks
argument-hint: "[component] [from] [to]"
disable-model-invocation: true
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

$ARGUMENTS 是全部参数，$0/$1/$2 是位置参数。用户敲 /migrate-component Button Vue React，正文里的 $0 就替换成 Button。

!command`` 则是动态上下文注入，命令输出在加载时就被嵌进正文：

markdown 复制代码

## Current State (Auto-detected)

Git status:
!`git status --short 2>/dev/null || echo "Not a git repository"`

Staged changes:
!`git diff --staged --stat 2>/dev/null || echo "Nothing staged"`

Claude 一进 Skill 就能看见当前 git 状态，不用再跑一遍命令。提交类 Skill 用这招最爽。

八、三套完整 YAML：参考型 / 任务型 / 复合型

参考型 Skill（语义触发，注入领域知识）：

yaml 复制代码

---
name: code-reviewing
description: Performs structured code reviews following team standards.
  Checks security vulnerabilities, performance issues, and code quality
  in priority order. Use when user asks to "review code", "do a code
  review", "check this PR", "audit this function", or provides code
  and asks for feedback.
allowed-tools:
  - Read
  - Grep
  - Glob
---

# 代码审查流程
你是一名资深代码审查员。按以下优先级执行：
## 第一优先级：安全检查
- SQL 注入、XSS、硬编码密钥、越权访问
## 第二优先级：性能问题
- N+1 查询、未加索引、循环内重复计算
## 第三优先级：代码质量
- 函数过长、命名不清、空 catch、违反 DRY

任务型 Skill（显式触发，执行动作）：

yaml 复制代码

---
name: committing
description: Quick git commit with auto-generated or specified message
argument-hint: "[optional: commit message]"
disable-model-invocation: true
allowed-tools:
  - Bash(git status:*)
  - Bash(git add:*)
  - Bash(git commit:*)
  - Bash(git diff:*)
model: haiku
---

Create a git commit.
If a message is provided: $ARGUMENTS
- Use that as the commit message
If no message is provided:
- Analyze `git diff --staged` and generate a message

## Current State (Auto-detected)
!`git status --short 2>/dev/null || echo "Not a git repository"`

复合型 Skill（路由器+渐进式披露）：

yaml 复制代码

---
name: financial-analyzing
description: Analyze financial data, calculate financial ratios, and
  generate analysis reports. Use when the user asks about revenue,
  costs, profits, margins, ROI, financial metrics, or needs financial
  analysis of a company or project.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(python:*)
---

# Financial Analysis Skill
## Quick Reference
| Analysis Type     | When to Use         | Reference                  |
|-------------------|---------------------|----------------------------|
| Revenue Analysis  | 收入、营收、销售额   | `reference/revenue.md`     |
| Cost Analysis     | 成本、费用、支出     | `reference/costs.md`       |
| Profitability     | 利润、毛利率、净利率 | `reference/profitability.md`|

参考型靠 description 语义命中，任务型靠 /skill-name 显式触发，复合型靠 Quick Reference 表路由到 reference 文件。三种类型对应三种触发方式，别混。

那么问题来了：你手头那个写了 2000 字正文的 Skill，是打算继续赌 Claude 心情好读完，还是花半小时拆成路由器+reference？

关于作者：雷达鸭 App 独立开发者，10+ 年软件开发经验，软件设计师、人工智能应用工程师，专注鸿蒙 ArkTS+Web 前端，探索 AI 自动化。

Skill 写成 2000 字说明书？Claude 根本不读——路由器思维与渐进式披露

一、YAML 前置元数据：Skill 的身份证

二、description 是 Skill 的灵魂

三、路由器思维：Quick Reference 表才是正文的主角

四、契约式引用：加载条件 + 路径 + 内容预期

五、渐进式披露：别一次性把正文喂完

六、权限设计模板：最小权限，禁止 Bash(*)

七、$ARGUMENTS 和 !command``：动态上下文注入

八、三套完整 YAML：参考型 / 任务型 / 复合型

六、权限设计模板：最小权限，禁止 `Bash(*)`

七、$ARGUMENTS 和 `!`command``：动态上下文注入