教程2026-10-19 · 智涌AI

10 分钟写出第一个 Agent Skill：SKILL.md 怎么写、怎么校验、4 个坑

如果你每次让 AI 校对公众号稿，都要把「中英文之间加空格、别用半角逗号」这几条规矩再粘贴一遍，那就该把它写成一个 Skill 了。我在自己的 Linux 机器上照着 Agent Skills 规范从零写了一个，又用官方工具校验、打包了一遍，下面只写实际跑出来的结果。

本文依据的一手资料：agentskills.io 上的 Agent Skills 规范、Claude 文档里的《Skill authoring best practices》、Claude Code 的 Skills 文档，以及 Anthropic 开源的 anthropics/skills 仓库（本文核对的是 2026-10-09 的最新提交）里的 skill-creator。之前我们拆过一个现成的 Skill（古人说唱 Battle），这篇讲怎么自己写一个。

Skill 是什么：一份按需加载的说明书

一个 Skill 就是一个文件夹，里面至少有一个 SKILL.md：开头是 YAML 头信息（name 和 description 必填），后面是用 Markdown 写的操作说明，旁边还可以放 scripts/、references/、assets/。

它和把规则写进 CLAUDE.md 或系统提示词的区别在于渐进加载。规范写得很具体：启动时只加载所有 Skill 的 name 和 description（约 100 token）；判断任务相关时才读 SKILL.md 正文（建议少于 5000 token、500 行以内）；脚本和参考文件要用时才读，脚本甚至可以只执行、不进上下文。所以装几十个 Skill 也不会把上下文撑满。

Claude Code 文档给的判断标准很好用：当你总在对话里粘贴同一段说明、检查清单或多步流程，或者 CLAUDE.md 里某一节已经从「事实」长成了「流程」，就该写成 Skill。

前置条件

Python 3.10+（我用的是 3.13），用来跑检查脚本和校验工具；
一个支持 Skills 的 Agent。本文以 Claude Code 为例：个人 Skill 放在 ~/.claude/skills/<名字>/，所有项目都能用；项目 Skill 放在仓库的 .claude/skills/，跟着代码走；
一个你经常重复交代的任务。我选的是「中文排版检查」，规则固定、结果能用脚本验证，最适合当第一个 Skill。

第一步：起名字，写 description

先建目录，目录名必须和 name 一致：

mkdir -p ~/.claude/skills/checking-zh-copy/scripts
cd ~/.claude/skills/checking-zh-copy

name 的规则：最多 64 个字符，只能用小写字母、数字和连字符，不能以连字符开头或结尾，不能出现连续的 --。Claude 文档推荐用动名词，例如 processing-pdfs，避免 helper、utils 这种含糊的名字。

description 才是重点，Agent 就是靠它决定什么时候调用你的 Skill。它最多 1024 个字符，要同时写清做什么和什么时候用，并且用第三人称来写（它会被注入系统提示词，人称不一致会影响识别）。skill-creator 里还提醒了一句：模型目前倾向于「该用的时候不用」，所以 description 可以写得积极一点，把用户可能的各种说法都列进去。

第二步：写 SKILL.md 正文

---
name: checking-zh-copy
description: 检查并修正中文文案的排版问题：中英文/数字之间缺空格、中文句子里混用半角逗号句号、连续感叹号。当用户要求校对、润色、检查排版，或提到公众号稿、文案、README 中文版时使用，即使用户没说「排版」两个字。
---

# 中文文案排版检查

1. 运行 `python3 scripts/check.py 文件路径`，它会逐行列出问题（行号、类型、原文片段）。
2. 只改脚本报出的问题，不改措辞、不改观点。
3. 改完再跑一遍脚本，直到输出 `OK`。
4. 最后给用户一张「改了哪几处」的清单。

例外：代码块、URL、命令行里的内容不要改。

这十几行对应了最佳实践里的三条：只写模型不知道的（不用解释什么是排版）；易错的步骤交给脚本（低自由度，结果稳定）；形成反馈闭环（检查 → 修改 → 再检查，直到 OK）。

第三步：写一个检查脚本

把能确定判断的规则写成脚本，比每次让模型「注意一下」可靠得多，也省 token。我的 scripts/check.py 核心只有三条正则：

RULES = [
    ("中英文之间缺空格", re.compile(r"[\u4e00-\u9fff][A-Za-z0-9]|[A-Za-z0-9][\u4e00-\u9fff]")),
    ("中文后用了半角标点", re.compile(r"[\u4e00-\u9fff][,.!?;:]")),
    ("连续感叹号", re.compile(r"[!！]{2,}")),
]
# 跳过 ``` 代码块，去掉 URL 和 `行内代码` 后逐行匹配；
# 没问题输出 OK、退出码 0，有问题列出明细、退出码 1

拿一句「用Claude写周报,效率翻倍!!」测试，脚本报了 5 处：两处缺空格、两处半角标点、一处连续感叹号，退出码为 1；代码块里的 npm i -g foo,bar 被正确跳过。退出码很重要，Agent 靠它判断这一轮是否通过。

规则能写成脚本的，就别写成提示词：脚本只执行、不进上下文，结果每次都一样。

第四步：用官方工具校验、打包

有两个现成的校验工具。一个是 anthropics/skills 仓库里 skill-creator 自带的脚本，另一个是规范页面推荐的参考库 skills-ref（PyPI 上当前是 0.1.1）：

# 1) skill-creator 自带
git clone --depth 1 https://github.com/anthropics/skills
pip install pyyaml
python3 skills/skills/skill-creator/scripts/quick_validate.py ~/.claude/skills/checking-zh-copy
# → Skill is valid!

# 2) 规范参考库（注意命令名，见下面的坑）
pip install skills-ref
agentskills validate ~/.claude/skills/checking-zh-copy
# → Valid skill: checking-zh-copy

# 3) 打包成 .skill（本质是 zip），方便分享
cd skills/skills/skill-creator
python3 -m scripts.package_skill ~/.claude/skills/checking-zh-copy ./out

打包产物 checking-zh-copy.skill 只有 1.5 KB，用 unzip -l 看就是 SKILL.md 加 scripts/check.py。agentskills to-prompt 还能输出 Agent 启动时实际看到的 <available_skills> 片段，可以用来检查 description 读起来是否清楚。

放进 ~/.claude/skills/ 后，在 Claude Code 里可以直接输入 /checking-zh-copy 调用；说「帮我校对这篇公众号稿」时，Claude 也会根据 description 自己决定是否加载它。如果你只想手动调用、不想让它自动触发，可以在头信息里加 disable-model-invocation: true。

常见坑：我实测踩到的 4 个

我故意写错了几个版本，分别交给两个工具校验：

写错的地方	quick_validate.py	agentskills validate
name 带大写	报错	报错
目录名和 name 不一致	通过	报错
description 带尖括号	报错	通过
name 带 claude	通过	通过

坑 1：两个工具各管一半。目录名不一致只有 agentskills 能查出来，description 带尖括号只有 quick_validate.py 能查出来。两个都跑一遍最稳。
坑 2：name 用了保留词。Claude 文档写明 name 不能包含 anthropic、claude，但这两个工具都放行了 claude-zh-copy。起名时自己检查一下，别等上传后才发现。
坑 3：命令名对不上。规范页面写的是 skills-ref validate，但 pip 装的 0.1.1 版提供的命令其实是 agentskills，直接敲 skills-ref 会提示 command not found。
坑 4：description 写成一句「帮你处理文档」。格式完全合法，但 Agent 几乎不会触发它。写清场景和用户的原话（校对、润色、公众号稿），比把正文写长更有用。

完成标准

两个校验工具都显示 valid，目录名和 name 一致，name 不含保留词；
脚本对有问题的样例返回非 0，修好后输出 OK；
在 Agent 里用 /名字 能调用；换几种说法（比如「帮我看看这段文案」）也能自动触发。官方建议至少准备 3 个测试场景，如果打算用不同模型，Haiku、Sonnet、Opus 都试一遍。

说明：我在机器上验证了目录结构、两个校验工具、脚本和打包；自动触发效果和模型、客户端有关，请以你自己的 Agent 实测为准。

最后

挑一件你这周重复交代了 3 次以上的事，照上面四步写成你的第一个 Skill，今天就放进 ~/.claude/skills/ 试一次。

信息来源