代码语言

知识点思维导图

29 个知识节点

参考资料

Skill（02） - 跑通第一个 Skill

读完后，你应能完成以下任务：

绘制“Skill（02） - 跑通第一个 Skill / 开始前：技能放在哪”的关键对象与数据流，解释“还有「项目级」目录（ /.claude/skills/，只在该项目生效），适合跟团队共享。”，并用源码位置、日志或 Trace 标注证据。

为“Skill（02） - 跑通第一个 Skill / 第 1 步：建一个技能文件夹”设计正常与异常输入，验证“技能就是一个文件夹，文件夹名 = 技能名。”，输出首个偏差位置与回归测试结果。

实现“Skill（02） - 跑通第一个 Skill / 第 2 步：写最小可用的 SKILL.md”的最小代码或配置，检验“注意 name 的值（polish-text）要和文件夹名一致，这是个好习惯，能省掉很多迷惑。”，输出命令、结果与 Diff，并说明不适用边界。

本章目标：不求甚解，先体验完整闭环——创建文件夹 → 写最小 SKILL.md → 触发 → 看到效果。学完你会有一个真正能跑的「第一个 Skill」。

一、开始前：技能放在哪

Claude Code 会从几个固定位置去找技能。你现在只需要记住最常用的一个——个人级技能目录：

~/.claude/skills/

放进这个目录的技能，在你所有项目里都能用。我们这一章就用它。

还有「项目级」目录（<项目>/.claude/skills/，只在该项目生效），适合跟团队共享。作用域的事第 12 章再细讲，现在先用个人级跑起来。

二、第 1 步：建一个技能文件夹

技能就是一个文件夹，文件夹名 = 技能名。我们做一个「把文字改写得更专业」的小技能：

mkdir -p ~/.claude/skills/polish-text

记住一条铁律：文件夹里必须有一个叫 SKILL.md 的文件（名字、大小写都不能错），这是入口。

三、第 2 步：写最小可用的 SKILL.md

在 ~/.claude/skills/polish-text/ 下新建 SKILL.md，内容如下：

---
name: polish-text
description: 当用户需要润色、改写文字，让表达更专业、更通顺时使用。适用于优化邮件、文档、消息措辞的场景。
---

# 文字润色

把用户给的文字改写得更专业、更清晰，要求：

1. 保持原意不变，不要添加用户没说的信息。
2. 让句子通顺、用词得体，去掉口水话。
3. 默认保持中文，除非用户要求其他语言。

输出时，先给「润色后的版本」，再用一行说明「主要改了什么」。

就这么短。一个能用的 Skill，最少只需要 frontmatter（name + description）+ 一段正文。

注意 name 的值（polish-text）要和文件夹名一致，这是个好习惯，能省掉很多迷惑。

四、第 3 步：触发它

现在你的目录应该长这样：

~/.claude/skills/
└── polish-text/
    └── SKILL.md

打开一个新的 Claude Code 会话（或当前会话），像平常一样说话，不要提技能名字：

帮我把这句话改得专业点：「这个事我觉得应该没啥问题，你们看着办吧。」

如果一切正常，Claude 会自动识别出这是「润色文字」的需求，加载 polish-text 技能，然后按你写的规则给出：

润色后：此事我评估暂无明显风险，具体执行方式请你们酌情决定。 主要改了什么：去掉口语词「啥」「看着办」，改为更稳妥得体的书面表达。

🎉 闭环跑通了——你没说「用 polish-text」，它却自己上场了。这就是 Skill 的魅力。

五、第 4 步：确认它真的被触发了

新手最大的疑惑是：「它到底是用了我的技能，还是 Claude 自己随便答的？」两个简单办法验证：

办法一：在正文里埋一句「暗号」。 比如临时在正文末尾加一行：

输出的最后永远附上一行：「—— by polish-text skill」

再问一次，如果结尾出现了这句暗号，说明技能确实被加载了。验证完记得删掉。

办法二：直接问 Claude。 在 Claude Code 里可以用 /skills（或相关命令）查看当前可用技能列表，确认 polish-text 在里面。

六、常见错误（90% 的人卡在这）

❌ 文件名写错：写成了 skill.md、Skill.md、SKILLS.md。必须是 SKILL.md，全大写、单数、.md 后缀。错一个字符就找不到。
❌ frontmatter 格式坏了：--- 上下没对齐、或写成了三个以上的横线、或 description: 后面没空格。 YAML 对格式敏感，坏了整个技能就加载不了。
❌ 放错目录：建在了 ~/.claude/skill/（少了 s）或别的地方。个人级必须是 ~/.claude/skills/（复数）。
❌ description 太干：只写了「润色」两个字。描述太短，Claude 不知道什么场景该用它，触发率骤降（第 05 章专门救这个）。
❌ 改了不生效：有时新建/改完技能，当前会话没刷新。开个新会话再试，是最稳的验证方式。

七、最佳实践

先跑通，再雕花。第一版能被触发、能出东西就算成功，别一上来就追求完美。
文件夹名 = name = 语义清晰的英文短横线命名（如 polish-text、code-review），方便自己和团队认。
用「暗号大法」做冒烟测试。任何新技能，先埋暗号确认能触发，再去打磨内容。
一次只动一处。改完一个地方就测一次，出了问题好定位。

八、动手实践：02 章 Demo · 你的第一个可运行 Skill：polish-text

这是一个真实可用的文字润色技能。本 Demo 的目标只有一个：让你亲手把它装上、跑通、看到效果。

8.1 文件结构

03-跑通第一个skill-demo/
├── README.md              # 你正在看的说明
└── polish-text/           # 技能本体（整个文件夹就是一个 Skill）
    └── SKILL.md           # 技能说明书

8.2 三步装上它

复制到个人技能目录

# 把整个 polish-text 文件夹复制到 ~/.claude/skills/ 下
cp -r polish-text ~/.claude/skills/

复制完，确认结构正确：

ls ~/.claude/skills/polish-text/
# 应该看到：SKILL.md

开个新会话触发它

打开 Claude Code，正常说话，不要提技能名：

帮我把这句话改得专业点：「这个事我觉得应该没啥问题，你们看着办吧。」

看效果

如果装对了，Claude 会自动用上这个技能，先给出润色后的版本，再附一行「主要改了什么」。

8.3 验证它真的被触发了（埋暗号大法）

不确定是不是真用了技能？做个冒烟测试：

编辑 ~/.claude/skills/polish-text/SKILL.md，在正文最后加一行：
```
输出的最后永远附上一行：「—— by polish-text skill」
```
开新会话再问一次润色。
如果结尾出现了 —— by polish-text skill，✅ 说明技能确实被加载了。
验证完把这行删掉。

8.4 故意搞坏，加深理解（可选）

想真正记住那些坑？故意制造一次错误再修好：

把 SKILL.md 改名成 skill.md，再问 → 技能失效（文件名必须全大写）。改回来。
把 frontmatter 第一行的 --- 删掉一个横线，再问 → 加载失败（YAML 格式坏了）。改回来。

亲手踩一遍，比记十条规则都管用。

8.5 你会收获什么

拥有第一个真正能跑的 Skill。
掌握「装 → 触发 → 验证」的完整流程，后面每一章的 Demo 都是这个套路。
对「文件名、目录、YAML 格式」三大高频坑有了肌肉记忆。

8.6 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

polish-text/SKILL.md

---
name: polish-text
description: 当用户需要润色、改写文字，让表达更专业、更通顺时使用。适用于优化邮件、文档、消息措辞的场景。
---

# 文字润色

把用户给的文字改写得更专业、更清晰，要求：

1. 保持原意不变，不要添加用户没说的信息。
2. 让句子通顺、用词得体，去掉口水话。
3. 默认保持中文，除非用户要求其他语言。

输出时，先给「润色后的版本」，再用一行说明「主要改了什么」。

九、总结

开始前：技能放在哪：还有「项目级」目录（ /.claude/skills/，只在该项目生效），适合跟团队共享。
第 1 步：建一个技能文件夹：技能就是一个文件夹，文件夹名 = 技能名。
第 2 步：写最小可用的 SKILL.md：注意 name 的值（polish-text）要和文件夹名一致，这是个好习惯，能省掉很多迷惑。
第 3 步：触发它：润色后：此事我评估暂无明显风险，具体执行方式请你们酌情决定。
常见错误（90% 的人卡在这）：必须是 SKILL.md，全大写、单数、.md 后缀。