Claude Code Skills：打造你的专属 AI 工作流 · Lesson 3 of 6

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

学习目标：

  • 创建 Skill 的目录结构
  • 从零编写一个完整的 SKILL.md
  • 理解渐进式披露原则
  • 第一次调用你的 Skill

前置要求：<< 第 2 课 | 下一课 第 4 课 >>

我们要做什么

这一课，我们从零开始创建一个真实可用的 Skill：任务整理器。

它做什么：

  • 输入：一堆混乱的待办事项（文字、截图里的文字、会议记录）
  • 输出：按优先级和截止日期整理好的清单

为什么选这个：

  • 简单，不涉及复杂逻辑
  • 实用，你马上就能用上
  • 展示了 Skill 的核心结构

第 1 步：创建目录和文件

打开终端，执行：

目录结构现在是这样：

~/.claude/skills/└── task-organizer/    └── SKILL.md

用你的文本编辑器（VS Code、Cursor、或其他）打开 SKILL.md。

第 2 步：写 frontmatter

先写文件开头的元数据：1

检查清单：

  • ✓ name 是小写、用连字符
  • ✓ description 说了做什么（整理待办）、输入是什么（混乱列表）、什么时候用（会议行动项、项目待办）

第 3 步：写标题和简介

frontmatter 之后，加上标题：

为什么要写标题和简介：

  • 标题给人看（如果你过几个月回来看这个文件，能快速想起它是干什么的）
  • 简介给 Claude 看（补充 description 没说清楚的细节）

第 4 步：定义输入格式

告诉 Claude 接受什么样的输入：2

完成季度报告

  • 审查 PR #234 明天要修复那个登录 bug 周五之前准备演示 demo 更新文档

这里做了什么：

  • 列出了所有可能的输入格式
  • 给了一个示例，让 Claude 看到真实的输入长什么样

第 5 步：写处理步骤

这是 instructions 的核心部分，要写得足够具体：2

为什么要这么详细：

Claude 不是人，不会"理解你的意思"。你写"判断优先级"，它不知道按什么标准判断。但你写"包含'紧急'→ 紧急"，它就知道该怎么做。3

第 6 步：定义输出格式

告诉 Claude 结果应该长什么样：

给示例的好处：

Claude 看到示例，就知道具体的排版、符号、格式。不用猜"emoji 放哪里""时间写在前面还是后面"。

第 7 步：处理边界情况

补充特殊情况的处理方式：

完整文件

现在，你的 SKILL.md 应该是这样的：

保存文件。

第 8 步：第一次调用

打开 Claude Code，输入：

/task-organizer
完成季度报告审查 PR #234，周五之前明天修复登录 bug更新文档紧急：客户反馈的支付问题

Claude 应该输出：

### 🔴 紧急- 修复登录 bug - 明天- 客户反馈的支付问题 - 无明确截止
### 🟡 重要- 审查 PR #234 - 周五
### ⚪ 普通- 完成季度报告 - 无明确截止- 更新文档 - 无明确截止

如果输出不对，不要慌。 下一课我们专门讲调试。

渐进式披露：为什么不一次写完所有细节

你可能注意到，这个 Skill 没有处理"任务有依赖关系"或"任务分配给不同的人"。32

这是故意的。

渐进式披露原则：只给 Claude 它当前需要的信息，不要一次性塞太多。3

第一个版本只做最核心的功能：提取、分类、排序。等你用了几天，发现确实需要"任务分配"功能，再加进去。

好处：

  • Skill 文件短，context 消耗少，Claude 加载快
  • 逻辑简单，不容易出错
  • 你能快速验证核心功能是否正常

等第一个版本跑通了，再迭代。这是所有好的 Skill 的开发方式。3

小结

  • 创建 Skill 的 7 个步骤：目录→frontmatter→标题→输入→步骤→输出→边界情况
  • 步骤要具体：不能写"分析任务"，要写"查找日期关键词：今天、明天..."
  • 给示例很重要：让 Claude 看到输入和输出的实际样子
  • 渐进式披露原则：第一个版本只做核心功能，不要一次写完所有细节
  • 调用方式：/skill-name + 输入内容

下一课，我们学习如何测试和调试 Skill，让它从"能跑"变成"跑对"。

>> 第 4 课：测试与调试

Footnotes

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

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

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

Exercises

01

用第 1 课和第 2 课练习中确定的任务，创建一个完整的 SKILL.md。

Level 1：创建你自己的第一个 Skill

要求：

  1. 创建目录结构
  2. 写完整的 frontmatter（name + description）
  3. 写 instructions，至少包含：输入格式、处理步骤、输出格式
  4. 保存文件
  5. 在 Claude Code 里调用一次
Done criteria · checked locally
02

- [问题描述] - 优先级 - 模块

Bug 报告
03

- [请求内容] - 优先级 - 模块

功能请求
04

- [问题] - 模块

使用疑问

注意事项

  • 如果一条消息同时包含多个问题，拆分成多条
  • 如果无法判断优先级，标记为 P1
  • 保留原始消息的时间戳（如果有）
05

用你的 Skill 处理一个"不正常"的输入，比如：

Level 2：测试边界情况
  • 空输入
  • 格式混乱的输入
  • 包含特殊字符的输入

看看输出是什么，记录下来。下一课我们会用这个结果练习调试。

Done criteria · checked locally

My note

Jot down thoughts, sticking points, things you didn't get. Written to this course's appendix only — the lesson file is never touched.