自定义 Skills：把重复活变成一行召唤

📍 Claude Code 干活

机器人厨师从架子上拿出预制菜盒，准备热一份饭

⚠️ 前置门槛提醒：这一篇会出现一点 markdown 语法(写标题用 #、写列表用 -)。如果你完全没接触过 markdown,建议先跳过这一篇，等读完前面 8 篇 + 在 Claude Code 里写过几次对话(那时你已经天然熟悉 markdown 了)再回来。文章中会有一段 5 行的 markdown 速查，完全没接触过的人能跟上。

你一定撞到过的痛

你每周一写一份周报给老板。每次都跟 Claude 说类似的话：

“帮我写本周周报，要求：

重点先讲完成的 3 件最大的事

每件事写「完成了什么 / 用了多少时间 / 下周计划」

风格：克制、不夸张、动词起头

不要写「我有幸」、「致力于」这种虚词

总长不超过 500 字

素材在 ~/Documents/工作日志/ 这个目录”

说了 5 个星期,5 次都是同一段。每次复制粘贴你都觉得自己像复读机。

疲惫的人在工位上反复打同一段 prompt

Skill 就是为这个而生：把上面那一大段打包成一个文件，以后只要说「帮我写本周周报」或者甚至「该写周报了」,Claude 自动找到这个 Skill，按里面定义的流程跑。

Skill 是什么：跟 slash command 什么关系

左命令需要手动调用，右自动召唤

很多人会问——「上一篇讲的 custom slash command 也是 markdown 文件，跟 Skill 有啥不一样？」

现在它们已经是一回事了。 从 Claude Code 2.1.3（2026 年 1 月）起，自定义命令并入了 Skill：旧写法 .claude/commands/xxx.md 和新写法 .claude/skills/xxx/SKILL.md 都会生成 /xxx 这个命令，用法一样。旧的命令文件照样能用，官方建议新写的一律用 Skill。

一个 Skill 默认两种用法都支持：

谁来调用	怎么做	适合什么场景
你手动	直接打 `/weekly-report`	你记得用它、想马上用；自动召唤不灵时，这是最可靠的办法
Claude 自动	你说「该写周报了」，Claude 看 description 判断要不要用	你懒得记命令，希望 Claude 主动想起来

想限制谁能调用，在文件开头的 frontmatter（两行 --- 中间那块设置，下面会讲）里加一行开关：

disable-model-invocation: true：只能你手动打 /名字，Claude 不会自己用（部署、发邮件这类有副作用的活适合这样设）
user-invocable: false：只给 Claude 自动用，/ 菜单里不显示（适合纯背景知识）

类比：

手动调用 = 微波炉上的「快速加热」按钮——你按它才热
自动召唤 = 智能厨房——你说「我饿了」，它自动给你出一份合适的饭

Skill 是一个厨房两种用法都有：你可以直接按按钮，也可以只说一声「饿了」。

新手的节奏：先写一个 Skill，平时直接打 /名字 用；description 写好了，你说到相关的事时 Claude 也会自动想起它。

一个 Skill 文件长什么样

一份 Skill 文件的截图示意，标注 3 个区段

一个 Skill 就是一个 markdown 文件，结构 3 部分：

---
name: weekly-report
description: 写本周周报,适用于「周报 / 周总结 / 这周做了什么」类请求
---

# 写本周周报

请按以下规则帮我写本周周报:

## 风格
- 克制、不夸张
- 动词起头(❌ 我有幸 / 我致力于 → ✅ 完成了 / 上线了)
- 总长不超过 500 字

## 内容结构
1. 完成的 3 件最大的事(每件:完成了什么 / 用了多少时间 / 下周计划)
2. 遇到的卡点 + 我准备怎么解决
3. 下周重点

## 素材来源
读 ~/Documents/工作日志/ 这个目录下本周的 .md 文件。

3 个核心部分:

1. 顶部 frontmatter(--- 中间这块)

---
name: weekly-report
description: 写本周周报,适用于「周报 / 周总结 / 这周做了什么」类请求
---

name：这个 Skill 的名字（英文小写，横线分隔），也就是你手动调用时打的 /weekly-report；不写就用文件夹名
description:这是最关键的字段——Claude 用它判断「这次请求要不要用这个 Skill」。写得越具体，触发越精准。

2. 主体(markdown 正文)

直接写你要 Claude 怎么干——风格、结构、素材来源、注意事项，全部用人话说清楚。就当你在跟一个新员工交代任务。

3. 可选：子工具调用

进阶用法——你可以在 Skill 里指定它该调用哪些工具(读文件 / 跑命令 / 调用外部 API)。新手第一年不用。

5 行 markdown 速查(没接触过的可以跟上)

如果你完全没接触过 markdown，看这 5 条就能写 Skill:

你想要	写法
一级标题	`# 标题`
二级标题	`## 副标题`
列表	`- 第一条`
加粗	`这段加粗`
代码块	三个反引号包起来(就像这一段)

这 5 条 已经能写 95% 的 Skill。剩下的需要时再查。

怎么写你的第一个 Skill

Step 1：决定写什么

挑一个你这一个月让 Claude 做过 3 次以上同样指令的活。常见的：

写周报 / 月报
改简历(每次都那几条风格规则)
整理发票录入 Excel
写邮件回复(中文 / 英文)
code review(找这几类问题)

第一次写，挑一个最简单的。先体验「写好之后召唤一次成功」的爽。

Step 2：在对应目录创建文件

关键规矩：每个 Skill 是一个文件夹，里面放一个固定名字的 SKILL.md——不是散装的单个 md 文件，名字写错它不认。

全局级(所有项目都能用)

mkdir -p ~/.claude/skills/weekly-report
nano ~/.claude/skills/weekly-report/SKILL.md

把上面的模板内容粘进去，改成你的实际指令。

nano 是 Mac / Linux 终端里的文本编辑器（粘贴完按 Ctrl+O、回车保存，再按 Ctrl+X 退出）。用 Windows 或者不想碰终端编辑器，有两个替代办法（项目级同理）：

用记事本或 VS Code 新建文件，粘进模板，保存到 C:\Users\你的用户名\.claude\skills\weekly-report\ 这个文件夹，文件名写 SKILL.md（记事本的保存类型要选「所有文件」，不然会存成 SKILL.md.txt）
直接在 Claude Code 里说：「在 ~/.claude/skills/weekly-report/ 下建一个 SKILL.md，内容是……」，让它替你建

项目级(只这个项目能用)

mkdir -p .claude/skills/deploy-staging
nano .claude/skills/deploy-staging/SKILL.md

放在你当前项目的根目录下。

节奏建议:

跨项目通用(写周报、改简历)→ 全局级
项目特定(部署 / 测试 / 这个项目的 commit 规范)→ 项目级

Step 3：确认它被认出来了

Claude Code 会盯着 skills 目录的变化：新增、修改、删除 Skill，保存后当前会话就生效，不用重开。

唯一的例外：如果 ~/.claude/skills 这个目录是会话开着的时候才新建的（第一次写 Skill 往往就是这样），Claude Code 还没在盯它。这时运行一次 /reload-skills（重新扫描 Skill 目录）；在这个会话里之后每改一次都要再运行一次，或者干脆关掉 Claude Code 重开，以后的改动就自动生效了。

用 /skills 能看到它有没有被认出来。

Step 4：试试看

最直接的办法：打 /weekly-report 手动召唤，它马上按你写的流程跑。

再试试自动召唤，说类似这样：

「该写周报了。」

或者：

「本周做了哪些事？帮我整理一下给老板。」

Claude 应该自动召唤刚才写的 weekly-report Skill——你会看到它读了你的工作日志目录,按你定的格式写,风格符合你的要求。

没召唤出来也别急：先看 description 里有没有你刚才说的词（下一节讲怎么写），要紧的时候直接打 /weekly-report 就行。

第一次跑通的爽感——你会立刻明白这一篇为什么值得读。

Skill 自动召唤的原理

Claude 看到请求，自动从架上拿对应的 Skill

Claude 不会扫描你 Skill 的全部内容(那样太烧 token)——它只读 description 字段。

所以：description 写得好 = Skill 召唤准 + 不召唤错。

写 description 的 3 条原则:

✅ 1. 包含「触发词」

❌ 不好的描述：

「用来生成报告。」

✅ 好的描述：

「写本周周报。适用于「周报 / 周总结 / 这周做了什么 / 该交报告了」类请求。」

把用户可能说的触发词全列出来——Claude 看到这些词就会想到这个 Skill。

✅ 2. 描述「适用场景」

❌ 不好的描述：

「改简历。」

✅ 好的描述：

「按特定风格修改简历。适用于「改简历 / 简历润色 / 加强简历」请求。如果是写新简历或重新组织结构，不适用此 Skill。」

说清楚什么时候用、什么时候不用——避免 Claude 误召唤。

✅ 3. 长度控制在 50-150 字

太短 → 触发不准太长 → 浪费 context

把 Skill 分享给团队

一份 Skill 文件的示意：本质就是一个 markdown 文件，能像代码一样用 git 管理

Skill 本质上就是一个 markdown 文件,可以像普通代码一样 git 管理 / 分享。

方法 1：项目级 Skills 跟代码一起走

在你的项目根目录运行：

git add .claude/skills/
git commit -m "Add team skills"
git push

队友 pull 代码后，自动获得整套项目 Skills。一致性立马拉满。

方法 2：个人 Skills 库做成单独的 git 仓库（repo）

先在 GitHub 网页上新建一个空的私有仓库 my-claude-skills（不要勾选自动添加 README；个人 Skill 里常有你的本机路径和个人习惯，建议设成私有）。然后运行下面这些命令，用 git 仓库管理你的全局 Skills：

cd ~/.claude/skills
git init
echo "synced/" >> .gitignore
git add .
git commit -m "init"
git branch -M main
git remote add origin git@github.com:你的账号/my-claude-skills.git
git push -u origin main

几个容易卡住的地方：

synced/ 文件夹别推上去：用 claude.ai 账号登录时，Claude Code 会把账号里的 Skill（包括 Anthropic 自带的 pdf、xlsx 等）自动同步到 ~/.claude/skills/synced/。上面的 echo "synced/" >> .gitignore 把它写进 .gitignore（git 的忽略清单），既不会把这些同步来的 Skill 推到 GitHub，换电脑时也不会和自动同步互相覆盖
不能跳过 git add 和 git commit：仓库里一次提交都没有就推送，会报 error: src refspec main does not match any
git branch -M main 也别省：很多电脑上 git init 建出来的分支叫 master，不改名就推 main 同样报这个错
第一次用 git 的话，git commit 前要先设置名字和邮箱（git config --global user.name "你的名字"、git config --global user.email "你的邮箱"）
git@github.com: 开头的地址要先配好 SSH 密钥；没配过就换成 https://github.com/你的账号/my-claude-skills.git。已经 git remote add 过的话，再 add 一次会报 remote origin already exists，要用 git remote set-url origin https://github.com/你的账号/my-claude-skills.git 改；推送时终端让你输密码，填的是 GitHub 上生成的访问令牌（token），不是登录密码
装了 GitHub 命令行工具 gh 并用 gh auth login 登录过的话，也可以不去网页建仓库：提交完直接运行 gh repo create my-claude-skills --private --source=. --remote=origin --push，一步建好仓库并推送，后面的 git remote add 和 git push 就不用再跑了

换电脑时：git clone 一下，你的所有 Skill 立刻全在新机器上。如果新电脑上 ~/.claude/skills 已经存在而且不是空的，clone 会失败，先把它改名挪走再 clone。

方法 3:GitHub gist 分享单个 Skill

如果你写了一个特别好用的 Skill 想分享给社区，把它发成 gist（GitHub 上分享单个文件的小仓库）。别人下载后要放成 ~/.claude/skills/名字/SKILL.md 这样的「文件夹 + SKILL.md」结构才会被认出来。

反过来，用别人的 Skill 之前先把 SKILL.md 读一遍：Skill 能用 !`命令` 这种写法在加载时直接执行 shell 命令，还能用 allowed-tools 预先放行工具，跟装插件一样要把好关。

5 个值得抄走的 Skill 模板

下面 5 个是社区里反响最好的 Skill 类型，可以照抄改你自己的：

Skill 名	一句话作用
`weekly-report`	按特定风格写周报
`improve-resume`	改简历(动词起头 / 数据具体 / 删虚词)
`email-reply`	写邮件回复(中英文 + 三种语气)
`my-code-review`	自动 review 当前的 git diff（找 bug / 性能 / 风格问题）
`commit-message`	看一下已暂存的改动（staged changes），写一条好的 commit message

每个都是「这事我每周都做 3-5 次」级别的频率，Skill 化收益最大。

注意 code review 那个别直接叫 code-review：Claude Code 已经自带 /code-review，先试试内置的；自己写同名 Skill 会把内置的顶替掉，所以模板换了个名字。

三个新手最容易踩的坑

❌ 坑 1:description 写得太宽泛，被误召唤

description: 「写文档。」

踩坑:Claude 看到任何「写一段话」的请求都会召唤这个 Skill,把不相关的请求按周报格式写。

修正:精确描述用途 + 列出触发词 + 列出不适用场景。

❌ 坑 2:Skill 文件太长，塞太多东西

Skill 写了 500 行，什么都讲了。

踩坑:Skill 被召唤时全文加载进 context——500 行 = 10k+ token 直接消耗。

修正:Skill 写指令本身，不要塞数据 / 例子库。需要数据时让 Claude 自己去读对应的目录。长的参考资料、例子放进同一个 Skill 文件夹里的附属文件（比如 reference.md、examples.md），在 SKILL.md 里写一句「需要看完整例子时读 examples.md」，用到时才加载。官方建议 SKILL.md 控制在 500 行以内。

❌ 坑 3:Skill 越写越多，自己都忘了有什么

「我写了 30 个 Skills，但每次都忘了哪个适用现在的场景。」

踩坑:Skill 大多靠 Claude 自动召唤，你不一定要记（记得的直接打 /名字）。但太多 + 描述写得不清 = Claude 召唤混乱。

修正:

每月看一次 ~/.claude/skills/ 目录，删掉 3 个月没触发过的；运行 /skill-doctor 能看到每个 Skill 占多少上下文、用过几次，从没用过的会被标出来
用 /skills 命令看当前所有 active skill 的列表
description 写得互相不重叠(不要两个 Skill 都说「写报告」)

一个真实场景演练

你:     该写周报了。

Claude: (自动召唤 weekly-report Skill)
        我看了你 ~/Documents/工作日志/ 里这周的 5 份日志,
        本周你完成的 3 件最大的事是:
        1. 上线了用户增长漏斗 v2,日活(DAU)从 8k → 12k(2 天工作量)
        2. 修复了支付回调失败的 bug(1 天)
        3. 跟设计对齐了 Q3 的视觉系统(1 天)

        下周重点:跟数据团队对接漏斗报表自动化。
        卡点:数据库压力升高,需要 DBA 一起拍方案。

        全文 432 字,符合你 500 字内的要求。要直接保存到 周报2026-05.md 吗?

你:     好。

整个对话不到 30 秒——这是 Skill 的真实威力。

下一步

读完这一篇你应该会：

写出第一个 Skill(weekly-report 是最好的练手)
理解 Skill 跟 slash command 的关系：现在是一回事，你手动打 /名字、Claude 自动召唤都行
知道 Skill description 怎么写才准

想把团队规范做成 /xxx、给命令加参数、让它跑在子智能体里，看进阶篇自定义 Slash Command：把团队规范变成 /xxx。

下一篇，「Claude Code 干活」板块的最后一篇：

→ Plugins：别人写好的工具装上就用 —— 不用自己写，直接用社区现成的 Skill / Tool 打包

想及时看到更新，可以收藏 niuxue.org 主页。