编写第一个 SKILL.md

本单元目标

学完本单元后，你将能够独立编写一个符合 Claude Skills 规范的 `SKILL.md` 文件，并理解其 frontmatter、正文结构与调用逻辑，使该 Skill 能被 Claude 正确识别和复用。

概念讲解

`SKILL.md` 是 Claude Skills 的核心描述文件，它本质上是给 Claude 看的一份“操作说明书”。就像你把一项工作流程写成 SOP 交给新同事一样，`SKILL.md` 用结构化的方式告诉 Claude：这个技能是干什么的、在什么场景下触发、具体怎么执行。

一个标准的 `SKILL.md` 包含两部分：frontmatter（文件开头的 `---` 包裹区域）和正文（markdown 格式的自由文本）。frontmatter 中至少需要声明 `name`（技能名）和 `description`（技能描述），其中 `description` 尤为关键——Claude 会基于它来判断何时该调用这个技能。正文部分则用标题、列表、代码块等 markdown 语法，详细描述执行步骤、注意事项和示例。

举个例子：假设你要写一个“周报生成”技能，frontmatter 中的 `description` 可以写“当用户需要总结本周工作、生成周报时使用”，正文则列出“收集本周事项 → 按优先级排序 → 生成结构化周报”等步骤。这样，当用户提到“帮我写周报”时，Claude 就能匹配到你的描述并调用这段流程。

对于 L3 进阶者来说，关键不是记住语法，而是理解 `description` 的触发匹配逻辑，以及正文如何通过清晰的结构让 Claude 稳定复现你的意图。

实操演练

1. 在项目目录下新建 `skills/` 文件夹，在其中创建名为 `weekly-report` 的子文件夹，并新建空白的 `SKILL.md` 文件。
2. 在文件最顶部写入 `---` 开闭的 frontmatter 块，填入 `name: weekly-report` 和 `description: 当用户需要总结一周工作、生成周报时使用此技能`。
3. 在 frontmatter 下方用 `# 周报生成` 作为一级标题，接着用 `## 执行步骤` 分节，用有序列表列出 3 个步骤（收集素材、整理分类、输出模板）。
4. 在文末添加 `## 示例` 分节，用代码块展示一份简短的周报输出样例，供 Claude 参考格式。
5. 保存文件后，在项目根目录运行 `claude skills list` 命令，确认该技能出现在列表中且描述正确。

练习任务

1. 将上述 `weekly-report` 技能扩展为包含 5 个以上步骤、带条件分支（如“若本周无重要事项，则输出简化版”）的完整 `SKILL.md`，并确保通过 `claude skills list` 验证。
2. 仿照该结构，为“代码审查”场景编写第二个 `SKILL.md`，要求 `description` 明确触发条件，正文包含至少一个代码块示例。