Skill的触发与渐进式加载

写好 Skill 之后，Claude 怎么决定什么时候调用？怎么读取它？理解触发机制是写出"会被用上的 Skill"的关键。

1. Claude 看到 Skills 的方式

Claude 启动时不会读取所有 SKILL.md 的完整内容，而是只看到 frontmatter：

启动时 Claude 看到的 Skill 信息：

[
  {"name": "code-reviewer", "description": "..."},
  {"name": "git-commit-message", "description": "..."},
  {"name": "sql-reviewer", "description": "..."},
  ...
]

每个 Skill 的完整内容按需加载——只有 Claude 判断当前任务匹配某个 Skill 时，才会读取对应的 SKILL.md 完整内容。

2. 为什么这样设计

如果 Claude 启动时把所有 SKILL.md 都加载进上下文：

100 个 Skill × 平均 2000 字 = 20 万字塞进上下文
单条对话可用上下文被吃光，没法处理实际任务
Token 成本暴增

渐进式加载（Progressive Disclosure）让你可以写很多 Skill而不付出代价：

启动时占用：约 100 字 × N 个 Skill = 几 KB
触发时占用：当前 Skill 的完整内容（1-3 KB）

3. 触发的本质：模型的语义理解

Claude 决定使用哪个 Skill 的过程是纯语义的：

用户发来一段话
Claude 在心里"过一遍"所有 Skill 的 description
找出最匹配的 Skill（可能有多个）
读取这些 Skill 的完整内容
按 SKILL.md 的指导完成任务

这意味着：

触发的关键是 description 的语义匹配度
不是关键词匹配，是模型理解了用户意图后判断
多个 Skill 可能同时被触发，模型会综合使用

4. 让 Skill "被找到" 的技巧

技巧 1：在 description 中明确"问题域"

❌ 模糊：

description: 帮助处理 API 相关任务

✅ 明确：

description: 当用户要求设计 RESTful API、定义路由、写 OpenAPI 规范时使用

技巧 2：列举触发动词

description 中包含用户常用的动词，命中率显著提升：

description: 当用户**生成、创建、写、起草** Conventional Commits 风格的 git commit message 时使用

技巧 3：明确不该触发的场景

如果两个 Skill 容易混淆，主动声明边界：

# Skill A
description: 审查 Python 代码的安全漏洞（SQL 注入、XSS 等），不用于一般代码风格审查

# Skill B
description: 审查 Python 代码的风格和可读性，不涉及安全问题

技巧 4：用问题作为 description

更直接，模型一眼能匹配：

description: 用户在问"怎么部署到生产环境"、"上线流程"、"deploy 怎么做" 时使用

5. 多 Skill 协作

一次任务可能涉及多个 Skill。比如用户说："帮我写一个用户登录 API 的实现并提交"。

Claude 可能依次：

触发 api-design Skill（设计接口）
触发 python-fastapi Skill（实现代码）
触发 python-test-writer Skill（写测试）
触发 git-commit-message Skill（生成 commit）

每个 Skill 各司其职，不要在一个 Skill 里塞所有东西。

6. 避免"冗余触发"

问题表现

写多了 Skill 后，可能出现：

用户随便问个问题，Claude 触发了 5 个 Skill
上下文被各种 SKILL.md 撑爆
反而比不用 Skill 还慢

原因

通常是 description 写得太"贪心"——用大量关键词让 Skill 总是被命中。

解决

description 用精准动词 + 明确场景，不要列一堆关键词堆砌
删除"以防万一"的 Skill
同类 Skill 合并（一个 code-quality 比 lint、format、naming 三个分开好）

7. 强制触发 Skill

测试时如果想确保 Claude 用了某个 Skill，可以显式说：

用 git-commit-message skill 帮我写

或：

请按照 git-commit-message skill 的规范处理

显式提到 name，模型几乎一定会使用对应 Skill。

8. 检查 Skill 是否被触发

Claude Code 中可以通过几种方式确认：

方式 1：直接问

你刚才用了哪些 skills？

Claude 会列出实际加载的 Skill。

方式 2：看输出风格

如果输出格式严格符合 SKILL.md 中规定的格式，说明被触发了。否则可能没匹配上。

方式 3：日志（如果支持）

某些客户端会在输出中标注哪些 Skill 被使用，注意查看。

9. Skill 的渐进式深度

利用渐进式加载，可以分层组织内容：

---
name: react-app-builder
description: 创建新的 React 应用时使用，按公司模板生成项目脚手架
---

# React App Builder

## 步骤

1. 询问项目名和功能描述
2. 使用 `templates/base/` 作为起点
3. 根据需求选择性引入：
   - 路由：参考 [reference/routing.md](reference/routing.md)
   - 状态管理：参考 [reference/state.md](reference/state.md)
   - 样式：参考 [reference/styling.md](reference/styling.md)

## 通用规则

（核心规则，常常需要参考的）

这样：

总是加载：SKILL.md（核心步骤 + 通用规则）
按需加载：reference/ 下的具体规范

这种设计让单个 Skill 能覆盖很多场景，又不浪费上下文。

10. 真实例子：触发分析

来看几个用户提问，分析 Claude 会触发哪些 Skill：

例 1

用户："帮我审一下这段代码"

Skill 库：

code-reviewer：description = "代码审查，按公司规范"
sql-reviewer：description = "审查 SQL 查询的性能和安全"

分析：用户没说是 SQL，Claude 大概率只触发 code-reviewer。如果代码片段是 SQL，可能两个都触发。

例 2

用户："这个查询为什么这么慢？"