怎么写一个 Agent Skill

这篇适合谁

适合反复让智能体做同一类任务、想把说明一次写好、以后直接复用的人。需要会一点 Markdown，并且会建文件夹。读完你应该能写出一个合格的 SKILL.md，把它放到 Claude Code 能找到的位置，并用参考校验工具检查。

技能是什么

技能（skill）是一组指令、脚本和资源组成的文件夹，Claude 会按需动态加载，以提高它在专门任务上的表现 ^[2]。技能本身不会自动运行。它给智能体提供了完成某一类工作的说明，由智能体判断什么时候适用。

Agent Skills 格式是开放的。快速开始写明，同一个技能可以在任何兼容的智能体里使用，包括 Claude Code 和 OpenAI Codex ^[10]。

一个技能的结构

每个技能都有一个 SKILL.md 文件。它必须以 YAML frontmatter 开头，后面接 Markdown 正文 ^[3]。仓库里的 template/SKILL.md 提供了这个最小模板 ^[4]：

---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---

# Insert instructions below

除了这一个必需文件，技能目录还可以包含三个可选文件夹 ^[3]。scripts/ 放可执行代码，references/ 放文档，例如 REFERENCE.md、FORMS.md 或 finance.md 这样的领域文件，assets/ 放模板、图片和数据文件等静态资源 ^[3]。脚本应当自成一体，或者写清依赖；错误信息要有帮助；边界情况要处理妥当 ^[3]。

主文件 SKILL.md 保持在 500 行以内。详细的参考资料移到单独的文件里，并且引用层级只保持一层，路径相对于技能根目录 ^[3]。

frontmatter 的规则

规范定义了六个字段。name 和 description 必填，license、compatibility、metadata 和 allowed-tools 可选 ^[3]。

• **name** 长度为 1 到 64 个字符，只能包含 Unicode 小写字母和数字（a-z、0-9）以及连字符。不能以连字符开头或结尾，不能连续出现两个连字符，并且必须和父目录名一致 ^[3]。
• **description** 长度为 1 到 1024 个字符。它应同时说明技能做什么、什么时候用，并包含能帮助智能体识别相关任务的具体关键词 ^[3]。
• **license 写许可证名称或随附的许可证文件名。compatibility** 如果填写，长度为 1 到 500 个字符 ^[3]。
• **metadata 是字符串键到字符串值的映射。allowed-tools** 是以空格分隔的预先批准工具列表，规范中标注为实验性 ^[3]。

Claude Code 遵循这个开放标准，并增加了更多字段，例如 argument-hint、disable-model-invocation、user-invocable、model、effort、context、agent、hooks、paths 和 when_to_use ^[5]。其中有两个早点知道更好。disable-model-invocation: true 会阻止 Claude 自动加载这个技能，user-invocable: false 则把它从 / 菜单中隐藏，只让 Claude 自己调用 ^[5]。

注意一点：如果你要把技能上传到 claude.ai，或者通过 Skills API、anthropics/skills 里的 package_skill.py 打包，那么只能使用这六个标准字段，多写任何别的字段都会直接报错 ^[5]。

智能体如何加载技能

智能体分三个阶段加载技能，分别叫发现（discovery）、激活（activation）和执行（execution）^[6]。启动时智能体只加载每个技能的 name 和 description。只有技能被激活时，才加载完整的 SKILL.md 正文；scripts/、references/ 和 assets/ 里的文件只在需要时才加载 ^[3]。

所以 description 很关键。Claude 在启动时把 frontmatter 读进系统提示，用户的请求正是拿它来匹配 ^[7]。在 Claude Code 里，技能列表中 description 与 when_to_use 合并后的文本会在 1,536 个字符处截断 ^[5]。

放在哪里

在 Claude Code 里，个人技能放在 ~/.claude/skills/<skill-name>/SKILL.md，项目技能放在 .claude/skills/<skill-name>/SKILL.md。项目技能可以提交进仓库，团队成员也就能用上 ^[5]。嵌套的 <subdir>/.claude/skills/<skill-name>/SKILL.md，以及通过 --add-dir 传入的目录里的技能，同样会被加载 ^[5]。插件里的技能以 /plugin-name:skill-name 的形式调用。例如名为 my-plugin 的插件里，skills/review/SKILL.md 对应的命令是 /my-plugin:review ^[8]。

规范没有规定技能目录必须放在哪里，它只规定目录里应该有什么 ^[9]。跨客户端共享时，常见的约定是 <project>/.agents/skills/ 和 ~/.agents/skills/，有些实现还会扫描 .claude/skills/ 以求兼容 ^[9]。

想在 Claude Code 里试用公开的示例，先执行 /plugin marketplace add anthropics/skills，再用 /plugin install document-skills@anthropic-agent-skills 或 /plugin install example-skills@anthropic-agent-skills 安装其中一组 ^[2]。仓库里有 docx、pdf、pptx 和 xlsx 四个文档类技能 ^[2]。

在 Claude Agent SDK 里，技能同样是各自目录中的 SKILL.md 文件。SDK 从由 TypeScript 的 settingSources 或 Python 的 setting_sources 控制的位置加载它们 ^[11]。

上线前先校验

规范推荐使用参考库 skills-ref 检查技能，命令是 skills-ref validate ./my-skill ^[3]。每次改动 frontmatter 之后都应该跑一遍，因为 name 和目录名不一致是最容易漏掉的错误。

我们的做法

TellWorld 的新闻更新就是一个技能。它放在项目仓库的 .claude/skills/news-update/SKILL.md，由 /news-update 触发，也可以直接用大白话说「更新新闻」之类的话来触发 ^[1]。它的 description 里写了中文的触发说法，比如请求更新或拉取新闻，这样智能体才能把普通请求匹配到它上面 ^[1]。

这个技能写成了七个有编号的步骤：设定时间窗口和批次名；把搜集工作分给三个 Haiku 子智能体；做入库前的整理和事实核查；写作、导入并配图；更新置顶列表；上线并留存记录；最后给出一份简短报告 ^[1]。

时间窗口从 content/tasks/news-state.json 里保存的 until 时间戳开始，到当前时间结束 ^[1]。技能只有在导入和上线都成功之后才会更新这个状态文件，所以失败的一次运行下次会从旧的时间戳重新开始 ^[1]。如果窗口不足一天，技能会先问用户再继续；如果超过 45 天，它会提醒可能漏掉一些小新闻 ^[1]。

技能里还包含交给每个子智能体的完整提示词模板，写明了子智能体的搜集范围、对照已有 key 去重的规则、输出文件的名字，以及「除此之外什么都不做」的要求 ^[1]。

后来的一次修改，把外部写作模型换成了 Claude 子智能体，把外部图片接口换成了 Codex 生图。改动涉及 SKILL.md 和 CLAUDE.md 两个文件，大约 30 行 ^[1]。

限制和常见问题

• 智能体可能不选这个技能。 如果技能没有被触发，先检查 description。把用户真正会打的词加进去，并写清什么时候用它 ^[3]。
• 上传规则比规范更严。 在 Claude Code 里能用的技能，如果带了额外的 frontmatter 字段，上传 claude.ai 时可能失败 ^[5]。
• 长技能会占用上下文。 把参考资料移进 references/，让它只在需要时加载 ^[3]。
• 部分格式已有预置技能。 Anthropic 的预置 Agent Skills 覆盖 PowerPoint、Excel、Word 和 PDF，可以在 claude.ai、Claude API、AWS 上的 Claude Platform 和 Microsoft Foundry 中使用。自定义技能可以在 Claude Code 中创建，通过 Claude API 上传，或在 claude.ai 设置中添加 ^[7]。

下一步

先读规范，确认字段的确切规则 ^[3]；再读 Claude Code 的技能页面，了解额外字段和调用控制 ^[5]。anthropics/skills 仓库里有示例和模板 ^[2][4]。快速开始展示了在兼容智能体里的第一步 ^[10]。Claude Agent SDK 的页面则说明如何在代码中加载技能 ^[11]。