Chapter 03

SKILL.md 结构与元数据

写得好的 SKILL.md 比写得多的 SKILL.md 重要。本章把每一个字段、每一种常见错误、每一个加载时机掰开讲清楚。

完整字段一览

---
name: sec-10k-analyzer
description: >
  分析 SEC 10-K 年报,输出财务健康度评分与风险摘要。
  激活:用户提供 10-K 文件路径或 ticker。
  不处理:10-Q 季报(用 sec-10q-analyzer)、非美股。
version: 1.3.0
allowed-tools:
  - Bash
  - Read
  - Write
  - WebFetch
required-env:
  - SEC_API_KEY
tags: [finance, analysis, public-filings]
maintainer: finance-team@example.com
---
name(必填)
Skill 的唯一标识,小写字母 + 连字符,与目录名一致。Claude 内部用来引用。反例:驼峰、空格、中文。
description(必填,核心)
Claude 决定是否激活本 Skill 的唯一依据。必须包含:做什么 / 何时激活 / 不处理什么。3 行最佳,超过 500 字会影响命中精度。
version(可选)
语义化版本。团队协作与 Marketplace 分发时必要;个人用可省略。
allowed-tools(可选)
明确限制 Skill 可用的工具。API 场景下是安全边界——即便用户开了 Write 权限,Skill 如果没写 Write,就不能写文件。
required-env(可选)
声明依赖的环境变量。Skill 激活前若缺失,Claude 会提示用户配置,而不是运行到一半报 401。
tags / maintainer(可选)
纯元数据,不参与激活逻辑。Marketplace 搜索、团队归属用。

description 的三段结构

官方建议的 description 模板:

[做什么] 一句话描述核心能力 [何时激活] 关键词 / 输入条件 / 用户意图 [不处理] 相邻但不做的场景,留给兄弟 Skill

对比两个版本:

反例正例
description: SQL 工具 description: 生成符合公司 data-warehouse schema 的 Snowflake SQL。激活:用户描述数据查询需求且提到表名或业务概念。不处理:DDL、权限管理、Postgres。
5 字,Claude 看到所有 SQL 请求都激活 范围明确,Snowflake 专属,Postgres 请求不误触

正文结构:三层金字塔

SKILL.md 的正文(frontmatter 之下的 markdown)应该分三层,从必读到参考:

┌─────────────────────────────────────┐ │ 层 1 工作流(Workflow) │ │ Claude 必须遵循的主步骤,按数字排列 │ │ 目标:读完这一节能跑通 80% 场景 │ ├─────────────────────────────────────┤ │ 层 2 边界与决策点(Edge Cases) │ │ 遇到 X 时去读 references/Y │ │ 目标:触发懒加载,不把细节塞进来 │ ├─────────────────────────────────────┤ │ 层 3 示例对话(Few-shot) │ │ 3-5 个高代表性样例,纠正常见跑偏 │ │ 目标:小参数模型也能学到调用模式 │ └─────────────────────────────────────┘

一份优秀的 SKILL.md 正文模板

# {name}

{一句话重申能力,供 Claude 在激活后复读确认。}

## 工作流

1. 第一步,指明具体动作与用到的脚本。
2. 第二步,包含输入校验。
3. 第三步,生成交付物。

## 决策点

- 如果 {条件 A},读 `references/a.md` 按方案 A 处理。
- 如果 {条件 B},读 `references/b.md`。
- 如果遇到未定义情况,明确向用户提问,不要猜。

## 常见失败

- 报错 X → 解法 Y
- 输入格式 Z → 先运行 `scripts/convert.py`

## 示例

### 示例 1: 典型用法

用户: "帮我 ..."
Claude:
1. [调用 detect_fields.py]
2. [输出] ...

### 示例 2: 边界情况

用户: "..."
Claude: 先问清楚 ...,再做 ...。
示例对话比大段说教有效 10 倍
LLM 对 few-shot 极度敏感。与其写 "不要直接填签字域",不如写一段对话演示 Claude 遇到签字域时如何提问、如何降级处理。

Claude 读 SKILL.md 的顺序

  1. 激活期:只注入 frontmatter(name + description)到上下文,正文不读。此时占用约 50-200 tokens。
  2. 匹配期:用户请求命中 description,Claude 主动 read SKILL.md 全文,约 500-2000 tokens。
  3. 执行期:Claude 遇到"去读 references/X"、"运行 scripts/Y" 时,才按需加载那些文件。
别在正文里 import 100KB
有人会把 API Spec 的所有 endpoint 列表复制进 SKILL.md,以为"让 Claude 记得住"。这会一次性把 50K tokens 怼进上下文——Skill 的节流优势荡然无存。API Spec 放 references/,用时再 grep。

长度与性能经验

区域推荐长度超出后果
description50-200 字太长影响激活精度,Claude 抓不到关键词
SKILL.md 正文200-500 行超过后考虑拆分到 references
references/ 单文件< 5000 行超过后按主题拆成多个小文件,便于 grep
Skill 总体积< 50 MB过大影响 Marketplace 分发

版本管理与 changelog

Skill 进入团队使用后,强烈建议:

常见反模式

❌ description 里写 "高级 SQL 工具"
形容词无意义,Claude 匹配不到任何具体请求。改成"生成 Snowflake SELECT 语句"。
❌ SKILL.md 里塞完整 API 文档
违背渐进披露。拆到 references/api/*.md,用 grep 触发。
❌ 没写"不处理什么"
Skill 互相打架——两个 SQL Skill 同时激活,Claude 不知道用哪个。明确职责边界。
❌ 把代码写在 SKILL.md 的代码块里让 Claude 复制执行
让 Claude 现场抄代码容易出错。封装成 scripts/,给一个清晰的 CLI 签名。

本章小结