第 2 课：Skill 的解剖：SKILL.md 文件结构

学习目标：

• 理解 SKILL.md 的双部分结构
• 掌握 YAML frontmatter 的必需字段
• 学会编写有效的 description
• 了解 instructions 部分的组织方式

前置要求：<< 第 1 课 | 下一课 第 3 课 >>

一个 Skill 文件长什么样

打开任何一个 Skill，你会看到这样的结构：¹

这个文件有两个部分：

1. YAML frontmatter（--- 之间的部分）：元数据，告诉 Claude 这个 Skill 的基本信息
2. Markdown instructions（--- 之后的部分）：具体指令，告诉 Claude 怎么做

YAML frontmatter：让 Claude 认识你的 Skill

frontmatter 是文件最开头用 --- 包裹的部分。它告诉 Claude 两件最重要的事：²³

name：Skill 的唯一标识

• 规则：小写字母、数字、连字符，不能有空格
• 作用：这个名字会变成命令，比如 /task-organizer
• 建议：用描述性命名，短、一看就懂

好的 name：

• meeting-notes
• code-review
• changelog-generator

不好的 name：

• my-skill-1（太泛化）
• super_amazing_task_helper（太长、有下划线）
• 任务整理（不能用中文）

description：最重要的字段

这一句话决定了三件事：⁴

1. Claude 什么时候自动加载这个 Skill
2. 用户在 Skills 列表里看到什么
3. Claude 理解这个 Skill 是干什么的

编写公式：做什么 + 什么时候用 + 关键能力⁴

好的 description：

不好的 description：

可选字段（本课不讲，第 6 课涉及）

• model: 指定使用哪个模型
• allowed-tools: 限制这个 Skill 能用哪些工具
• version: 版本号

第一次写 Skill，只需要 name 和 description 就够了。³

Markdown instructions：告诉 Claude 怎么做

frontmatter 之后的所有内容，就是给 Claude 看的指令。¹

好的 instructions 有三个特点：

1. 分段清晰

用标题把不同部分隔开：

2. 步骤具体

不好：

好：

3. 有示例

如果输出格式有要求，给一个示例：

Claude 看到示例，就知道具体该怎么排版——这就是示例驱动，比大段文字描述更管用。

两部分如何配合

frontmatter 是发现机制，instructions 是执行指南。⁵⁶

1. 你输入 /task-organizer，或者说"帮我整理这些任务"
2. Claude 看 frontmatter 的 name 或 description，决定是否加载这个 Skill
3. 如果加载，Claude 读完整个 instructions
4. Claude 按照 instructions 的步骤执行
5. 输出符合 instructions 里要求的格式

这就是为什么 description 要写好：它是 Claude 决定「要不要用这个 Skill」的唯一依据。⁴

如果 description 写成"帮助处理任务"，Claude 不知道什么场景该用它；如果写成"整理待办事项，按优先级和截止日期分组"，Claude 一看到"整理任务""待办"这类词，就知道该加载它。

真实案例：拆解一个代码审查 Skill

看一个实际使用的 Skill：

分析：

• frontmatter 的 description：说清楚了做什么（审查代码）、检查什么（规范、bug、性能）
• instructions 分三个清单：规范、问题、性能，每个清单列出具体检查项
• 输出格式明确：告诉 Claude 每个问题要包含位置、问题、建议

这样的 Skill，Claude 一次就能做对。

小结

• SKILL.md 有两部分：YAML frontmatter（元数据）+ Markdown instructions（指令）
• frontmatter 必需字段：name（小写、连字符、唯一标识）和 description（决定自动触发）
• description 编写公式：做什么 + 什么时候用 + 关键能力
• instructions 三个特点：分段清晰、步骤具体、有示例
• 两部分配合：frontmatter 让 Claude 发现 Skill，instructions 让 Claude 执行

下一课，我们从零开始，完整地写一个 Skill。

>> 第 3 课：动手实践：编写你的第一个 Skill

Footnotes

1. Claude Code 官方文档：Skills 扩展指南 — https://code.claude.com/docs/en/skills ↩ ↩²

2. Anthropic 工程博客：Agent Skills 实战指南 — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills ↩

3. Anthropic 帮助中心：创建自定义 Skills — https://support.claude.com/en/articles/12512198-how-to-create-custom-skills ↩ ↩²

4. 构建 Claude Skill 实战教程：YAML Frontmatter 与测试 — https://sjramblings.io/building-skills-for-claude-part-2/ ↩ ↩² ↩³

5. Anthropic Platform 文档：Agent Skills 概述 — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩

6. Claude Skills 深度解析（First Principles 视角） — https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/ ↩