第八章 写自己的第一个 Skill

你将学到

• Skill 文件夹该放在哪、叫什么、怎么组织。
• SKILL.md 的完整结构与所有 YAML 字段含义。
• 怎么写出一个真的会被触发的 description。
• 完整撰写一个"每周读书清单生成器"Skill。
• 测试与调试 Skill 的 4 个套路。
• 用 skill-creator 让 Claude 帮你生成 Skill。

你需要准备

• 已能跑 Skill 的 Claude（推荐 Claude Code，调试更直观）。
• 一个文本编辑器（VS Code / Cursor / Sublime / 甚至记事本都行）。
• 一颗"先做出能跑的，再追求完美"的心。
• 30–45 分钟。

一、Skill 文件夹放哪、叫什么

1.1 三种"位置"

按 Anthropic 官方约定：

建议：个人 Skill 放全局；团队 Skill 放项目并提交 Git。本章默认用全局路径。

1.2 Skill 文件夹命名 5 条规则

按 Anthropic 官方文档：

1. 使用 kebab-case：小写字母 + 短横线，例如 weekly-report、invoice-extractor。
2. 不能有空格：weekly report ❌，weekly-report ✅。
3. 不能有大写：WeeklyReport ❌，weekly-report ✅。
4. 简短但能看懂：30 字符以内最佳。
5. 避免"通用名"：不要叫 helper、utils、tools。要么没人记得它，要么和别的 Skill 冲突。

1.3 文件夹的"标准布局"

最完整的 Skill 长这样（实际上只有 SKILL.md 是必需的）：

weekly-reading-list/
├── SKILL.md              # 必需：核心指令
├── README.md             # 推荐：写给"装这个 Skill 的人"看
├── references/           # 可选：参考资料（按需加载）
│   ├── book-categories.md
│   └── scoring-rubric.md
├── scripts/              # 可选：可执行脚本
│   └── fetch_douban.py
├── templates/            # 可选：模板文件
│   └── weekly-list.md
└── assets/               # 可选：图片、字体等
    └── icon.png

我们这一章只做最简单的版本：只有 SKILL.md。复杂版本第九章再讲。

二、SKILL.md 完整结构

一个标准的 SKILL.md 由两部分组成：

---
（YAML frontmatter 元数据，被 Claude 用作"书目卡片"）
---

（Markdown 主体，是 Claude 真正读的"指令书"）

2.1 YAML frontmatter 全字段速查

按 Anthropic 官方文档（截止 2026 年 4 月），Skill frontmatter 支持以下字段：

90% 的 Skill 只需要 name + description 两个字段。其它都是进阶玩法。

2.2 description 怎么写——Skill 的灵魂

第三章我们讲过 description 是 Skill 的灵魂。这里给一个"6 件事必须做"的清单：

1. 第一句话一句话点出"做什么"。
2. 第二句话列触发关键词（中英文都要）。
3. 第三句话覆盖典型场景。
4. 不超过 1024 字符（约 350 中文 / 200 英文单词）。
5. 避免"通用术语"（"通用助手""高效工具"这种没意义）。
6. 不要在 description 里塞指令——那是 instructions 的活。

优秀 description 示例

description: >
  Generate a weekly reading list from user's Douban / Goodreads / Kindle history.
  Categorize by genre, score by reading priority, output as Markdown card.
  触发: "本周读书清单""周读单""reading list""帮我挑这周看什么书"

反例对比

# ❌ 太笼统
description: A reading helper.

# ❌ 太长（这种会拖慢 Claude 决策）
description: >
  This is a comprehensive reading list generator that can help users in many
  scenarios including but not limited to weekly book picks, monthly summaries,
  yearly reviews, book club discussion topics, gift recommendations for friends
  and family, comparison between books, finding similar authors, ...

# ✅ 刚好
description: >
  Generate a weekly reading list (3–5 books) based on user's reading history
  and current mood. Categorize, prioritize, output as Markdown card.
  Triggers: "本周读书清单""周读单""reading list""挑书".

三、手把手写"每周读书清单生成器"

3.1 想清楚目标（最关键的一步）

痛点：你每周想读 3–5 本书，但常常拖延、选择困难。

输入：你的过去阅读历史（豆瓣 / Goodreads / Kindle 导出 / 或纯文本列表），加上"本周心情"或"想学的主题"。

输出：一份 Markdown 读书卡片，含 3–5 本书 + 推荐理由 + 阅读优先级 + 预计时长。

3.2 创建文件夹

打开终端：

mkdir -p ~/.claude/skills/weekly-reading-list
cd ~/.claude/skills/weekly-reading-list

3.3 撰写 SKILL.md

用你喜欢的编辑器打开 SKILL.md，粘贴下面这份完整内容：

---
name: weekly-reading-list
description: >
  根据用户的阅读历史和当下心情/主题，生成本周读书清单（3–5 本书），
  按类别归类、按优先级排序、估算阅读时长。
  输出为 Markdown 卡片。
  触发: "本周读书清单" "周读单" "帮我挑书" "reading list" "weekly book pick"
version: 1.0.0
allowed-tools: Read, Write
---

# 每周读书清单生成器

## 我是谁
我是你的私人读书顾问。基于你的过往阅读、当下兴趣和可用时间，
帮你挑出本周值得读的 3–5 本书。

## 工作流（请严格按这 5 步走）

### 第 1 步：理解用户输入
用户至少会提供：
- 本周心情或想学的主题（如"焦虑""想懂宏观经济""想轻松点"）

可能附带：
- 阅读历史（豆瓣/Kindle 导出文件、或一段读过的书名列表）
- 本周可阅读时长（如"通勤每天 1 小时""周末 4 小时"）
- 偏好（小说/非虚构/技术/历史/哲学等）

如果用户没说时长，默认假设"本周可读 6–8 小时"。

### 第 2 步：候选书池
- 如果用户给了历史，从中找"读过同类作者"作为种子，推同类作者的代表作。
- 如果用户没给历史，根据主题/心情，从经典书单里挑（用你的常识库）。
- 候选数控制在 8–10 本，最后筛 3–5 本入清单。

### 第 3 步：评分与筛选
每本候选书按 4 个维度打分（0–10）：
- relevance: 与用户本周主题/心情的相关度
- difficulty: 阅读难度（10 = 最易读）
- depth: 内容深度（10 = 最深）
- time_fit: 与可用时长的匹配度（10 = 完美匹配）

总分 = relevance × 0.4 + time_fit × 0.3 + depth × 0.2 + difficulty × 0.1
取总分 Top 3–5 入选。

### 第 4 步：分类与排序
按"易→难"排序输入清单，并给每本：
- 类别（用户偏好的主题）
- 一句话推荐理由（不超过 30 字）
- 预计阅读时长（按 200 页/小时 的均值，不要瞎估）
- 阅读建议（先读前言 / 直接跳到第 N 章 / 通勤听有声）

### 第 5 步：输出 Markdown 卡片

# 📚 本周读书清单 — <YYYY-MM-DD>

> 主题：<用户输入的主题>
> 可用时间：<X 小时>
> 共 N 本书 / 预计 Y 小时

## 1. 《书名》— 作者
- 类别：<类别>
- 推荐理由：<≤30 字>
- 预计时长：<时>
- 阅读建议：<>

## 2. ...

## 给你的话
（用一段 50 字以内的话告诉用户：为什么这份清单适合本周的他/她。）

---

最后保存为 ~/reading-lists/list-YYYY-WXX.md（XX 是周数）。

## 风格规范
- 不要推"工具书速成"那类（除非用户明确要）。
- 至少 1 本"轻松点的"作为调剂。
- 推荐理由要"对这个人这周说"，不要 generic。
- 中文用户用中文书名优先（书名号《》，作者用中文名）。
- 不编不存在的书名。如果不确定，标"待核对"。

## 示例（参考用，不要原样复制）

# 📚 本周读书清单 — 2026-04-19

> 主题：想搞懂自己的焦虑
> 可用时间：6 小时
> 共 3 本书 / 预计 5.5 小时

## 1. 《也许你该找个人聊聊》— 洛莉·戈特利布
- 类别：心理学
- 推荐理由：心理咨询师视角，让你看清焦虑的"故事性"
- 预计时长：3 小时
- 阅读建议：直接读，故事性强

## 2. 《被讨厌的勇气》— 岸见一郎
- 类别：哲学
- 推荐理由：用对话拆掉"必须被认可"的执念
- 预计时长：1.5 小时
- 阅读建议：先读"夜晚一对一对话"两章

## 3. 《当下的力量》— 埃克哈特·托利
- 类别：精神成长
- 推荐理由：把焦虑还原为"对未来的想象"
- 预计时长：1 小时
- 阅读建议：通勤听有声版

## 给你的话
你的焦虑不是"病"，是身体在用力跟你说话。这周慢一点，听它说。

保存。

3.4 重启 Claude（让它发现新 Skill）

• Claude Code：在对话里说"reload skills"，或退出再进。
• Claude.ai 网页版：把整个 weekly-reading-list/ 文件夹打包成 zip，上传到 Settings → Skills。
• Claude Desktop：同网页版。

3.5 第一次召唤

打开 Claude，输入：

帮我挑本周读书清单。

主题：想懂宏观经济一点点，但我没基础。
可用时间：通勤每天 1 小时 + 周末 3 小时。
偏好：故事性强一些。

如果一切正常，Claude 会响应：

"正在使用 weekly-reading-list skill...

已经为你挑选了 4 本书……"

然后给你一份完整的清单。

恭喜，你的第一个 Skill 上线了。

四、4 个调试套路：Skill 没按预期工作怎么办

套路 1：Skill 没被自动召唤

现象：你说"帮我挑本周读书清单"，Claude 按"普通聊天"回答你，没说"using weekly-reading-list skill"。

排查：

1. 文件夹路径对不对？跑 ls ~/.claude/skills/weekly-reading-list/ 确认。
2. SKILL.md 里 YAML 格式对不对？用在线 YAML 校验器（https://yamlvalidator.com）粘进去看看。
3. description 有没有用户输入里的"触发关键词"？如果没有，加进去。
4. 让 Claude 列出当前所有 Skill：列出我目前的所有 Skill，含名称和 description 摘要。看看你的在不在。

套路 2：Skill 召唤了但没按指令做

现象：Skill 被调用了，但输出格式跟你写的对不上。

排查：

1. 你的 instructions 是不是太短/太模糊？给一个完整示例（像 3.3 节最后那段一样）。
2. 是不是 instructions 里互相矛盾？比如同时说"3 本书"又说"5 本书"。
3. 是不是用户的输入压过了你的 instructions？
   • 比如你说"3–5 本"，用户说"我要 10 本"——Claude 会优先满足用户。
   • 解决：在 instructions 里加一句"如果用户要求超过 5 本，告知用户最多 5 本，并解释原因"。

套路 3：被错误地召唤了

现象：你只是想跟 Claude 闲聊，它却启动了你的某个 Skill。

排查：

1. description 是不是太"贪"？删掉太通用的词（比如"reading"这种太常出现的词）。
2. 把 description 收紧到一个明确场景。
3. 如果某些场合你确实不想被召唤，可以临时关闭这个 Skill（设置里）。

套路 4：Skill 跑出错（Python 异常等）

现象：调用了 Skill，但 Claude 报错或卡住。

排查：

1. Claude Code 里看错误堆栈，通常是 Python 缺包或者数据格式不对。
2. 在 SKILL.md 里加一条"错误处理"指令：

   ## 错误处理
   - 如果用户给的文件无法解析，告知用户错误细节，并建议怎么修。
   - 不要默默失败。
   

3. 加了 Python 脚本的 Skill，第九章会专门讲怎么调试。

五、用 skill-creator 让 Claude 帮你写 Skill（作弊大招）

Anthropic 官方提供了一个特殊的 Skill 叫 skill-creator，专门用来"用对话方式生成 Skill"。

5.1 安装 skill-creator

最快方式（Claude Code）：

/plugin add github.com/anthropics/skills/skill-creator

或手动：

1. 去 https://github.com/anthropics/skills 下载 skill-creator 文件夹。
2. 复制到 ~/.claude/skills/skill-creator/。

5.2 用它造 Skill

打开 Claude，说：

我想做一个 Skill，能把我每天的微信运动步数（手动告诉它）记下来，
每周给我画一张趋势图、计算总步数、给个等级（青铜/白银/黄金/王者）。

帮我用 skill-creator 把它生成出来。

skill-creator 会：

1. 跟你确认 Skill 名（比如 wechat-steps-tracker）。
2. 问你触发关键词、输入格式、输出格式、风格。
3. 草拟 SKILL.md。
4. 给你看，让你确认。
5. 自动写到 ~/.claude/skills/wechat-steps-tracker/。
6. 提示你重新加载 Skill 列表。

整个过程 5 分钟，比你手写快多了。

5.3 何时用 skill-creator，何时手写

强烈建议：手写完成本章的"读书清单"Skill 之后，再去玩 skill-creator。这样你心里清楚它生成的是啥。

六、给你的 Skill 写一份 README

虽然 SKILL.md 是给 Claude 看的，但如果你想分享 Skill 给别人用，额外写一份 README.md 给"人"看。

模板：

# weekly-reading-list

一个让 Claude 帮你挑本周读书清单的 Skill。

## 装它

### 方式 A: Claude Code 用户
```bash
git clone https://github.com/yourname/weekly-reading-list.git ~/.claude/skills/weekly-reading-list

方式 B: 网页版用户

1. 下载本仓库的 zip。
2. Claude.ai → Settings → Capabilities → Skills → Upload。

用它

直接对 Claude 说：

帮我挑本周读书清单，主题：xxx，可用时间：xxx。

它能做什么

• 基于你的阅读历史和本周心情/主题，挑 3–5 本书。
• 按"易→难"排序，含推荐理由、预计时长、阅读建议。
• 输出 Markdown 卡片，自动保存到 ~/reading-lists/。

它做不了什么

• 不会替你买书。
• 不会真的"理解你的人生"——它只是按你给的输入做合理推断。

反馈

提 Issue 或 PR：github.com/yourname/weekly-reading-list

---

## 七、把 Skill 推送到 GitHub（可选但推荐）

```bash
cd ~/.claude/skills/weekly-reading-list
git init
git add .
git commit -m "Initial release: weekly reading list generator"

# 在 GitHub 创建一个新仓库 weekly-reading-list（不勾 README）
git remote add origin git@github.com:yourname/weekly-reading-list.git
git push -u origin main

发出去之后，朋友就可以直接：

/plugin add github.com/yourname/weekly-reading-list

装到他们的 Claude 里。

第十二章会详细讲"怎么让你的 Skill 被更多人用"。

八、写 Skill 的 5 条心法

心法 1：先写"能跑的"，再追"完美的"

第一版 SKILL.md 不超过 50 行——把核心流程写清。跑通后再加细节。

心法 2：用"测试驱动"的方式写

写完 SKILL.md，立刻给自己 3 个 test prompt：

• 标准输入（用户给完整信息）
• 缺信息输入（用户只说一半）
• 极端输入（用户说"100 本""一辈子的"）

每种都跑一次，看 Claude 反应。这能在你"以为搞定了"之前发现 80% 的问题。

心法 3：写 description 像写"文案"

description 是写给 AI 看的"广告"——告诉它"什么时候该来抢这单"。所以要：

• 醒目（一眼能看出场景）
• 具体（包含真实关键词）
• 可信（不要承诺做不到的）

心法 4：示例胜过千言万语

在 instructions 里塞一个完整示例（像 3.3 节最后那段读书清单），比写 10 条规则有效。

心法 5：把"边界条件"写进去

Skill 出问题，80% 是没考虑到的边界条件：

• 用户输入为空
• 用户输入超过预期长度
• 用户在中途反悔
• 上下文已经有别的 Skill 在跑

把这些显式写进 SKILL.md，Claude 会按你的意思处理，而不是"自由发挥"。

九、本章一图回顾

+------------------------------------------------------------+
|              写自己的第一个 Skill 路线图                    |
+------------------------------------------------------------+
| 1. 想清楚痛点 (输入/输出/触发场景)                          |
| 2. 创建文件夹 ~/.claude/skills/<kebab-case-name>/          |
| 3. 写 SKILL.md                                             |
|    - YAML: name + description (灵魂)                       |
|    - 主体: 工作流 + 风格 + 完整示例                        |
| 4. 重启/重载 Claude                                        |
| 5. 给 3 个 test prompt 跑一遍                              |
| 6. 调 description (没被召唤就改这里)                       |
| 7. 调 instructions (召唤了但格式不对就改这里)              |
| 8. (可选) 写 README.md, 推送到 GitHub                      |
+------------------------------------------------------------+

调试 4 套路:
  没被召唤 → 改 description 加触发词
  没按指令 → 加完整示例 + 边界条件
  错误召唤 → 收紧 description
  脚本出错 → 加错误处理 + 看 Code 堆栈

作弊大招:
  /plugin add github.com/anthropics/skills/skill-creator
  → 让 Claude 帮你写 Skill

给你 3 句话提醒

1. 第一个 Skill 永远是"能跑就行"。优秀的 Skill 都是用 5–10 个版本迭代出来的。
2. 别跳过"测试 3 个 test prompt"。它能在你"得意"前敲打你。
3. 写 Skill 不是写代码——是写"教 AI 怎么干活"的说明书。说明书的核心是清晰，不是炫技。

下一章预告

下一章 第九章 Skill 进阶（脚本/模板/依赖），我们让 Skill 真正"长出肌肉"。

你会学到：怎么在 Skill 里加 Python 脚本（让它真的能查股票画 K 线）；怎么加模板文件（让它输出公司专属格式）；怎么加 references 让 AI 参考公司术语；怎么声明 dependencies 自动装包；怎么让多个 Skill 协作完成一个大任务。

走，进第九章。