Mindket
简体中文
English简体中文
登录注册
商店MCP技能计算器学习价格博客
发现
研究311写作59商务95法律13财务33营销173开发1,409效率386教育81陪伴14
帮助与支持
语言
English简体中文
Agent Skills 课程：写好、测好、装好 SKILL.md 技能第 1 节，共 4 节

技能描述怎么写：写好名称和描述，技能才会被加载

Mindket 编辑部 · 发布于 · 更新于 · 阅读约 7 分钟

黑色横幅，标题是“Agent Skills 技能课”，下面一行写着“写好、测好、装好会按时触发的 SKILL.md 技能”。

技能描述是智能体决定要不要打开你的 SKILL.md 之前，读到的唯一内容。把它写成一条指令：技能做什么，然后什么时候用，用的是用户会敲出来的词。这一课把一条含糊的描述改成能触发的描述，再讲技能一直不触发时怎么排查。

本节内容

  • 描述写成两半：技能做什么，什么时候用，并且用第三人称。
  • 把使用场景写出来，包括用户根本没说出技能主题的请求。
  • 主要用途放在最前面，因为 Claude Code 会在技能清单里截断过长的描述。
  • 技能不触发时，按顺序查：关键词、技能列表、换种说法、斜杠命令。
全部课程
本页目录
  1. 开始之前
  2. 六步改好一条含糊的描述
  3. 智能体做决定之前读到什么
  4. 技能一声不响的时候
  5. Anthropic 的 Alex Albert 和 Boris Cherny 怎么说技能的用处
  6. 常见错误
  7. 自己试一试
  8. 下一课
  9. 自测一下
  10. 常见问题
  11. 资料来源

开始之前

你需要 Claude Code（或任何读取 SKILL.md 的智能体）和一个终端。这一课只改一个文件。技能的正文现在可以只有一行，因为要测的是描述。正文留到第 2 课再写。

贯穿全课的示例，是一个审查 OpenAPI 规范变更的技能，为这门课而写。命令都来自来源列表里的 Agent Skills 和 Claude Code 文档。

这里的每个事实都来自来源列表里的页面，阅读日期为 2026 年 11 月 4 日。本课不是实测，示例技能是为本课写的。

六步改好一条含糊的描述

Anthropic 的编写指南说，Claude 靠描述从可能上百个技能里挑出该用的那个。它还说，描述会被注入系统提示，所以要用第三人称：写“Processes Excel files”，别写“I can help you process Excel files”。

多数人的初稿是在介绍技能本身：“Helps with API changes.”Agent Skills 规范把“Helps with PDFs.”当作糟糕描述的例子。下面这版写清了技能做什么、什么时候用，也照顾到了从不提“OpenAPI”的用户。

---
name: reviewing-api-changes
description: Reviews changes to an OpenAPI or Swagger spec for breaking changes such as removed fields, renamed paths and stricter validation. Use when the user asks whether an API change is safe to ship, compares two versions of an API, or edits a spec file, even if they never say "breaking change".
---

# Reviewing API changes

Instructions come in lesson 2.
  1. 建文件夹：mkdir -p ~/.claude/skills/reviewing-api-changes。只给一个仓库用，就在仓库里建 .claude/skills/reviewing-api-changes。
  2. 起名字。规范允许小写字母、数字和连字符，最长 64 个字符，名称必须和文件夹同名。Anthropic 建议用 processing-pdfs 这样的动名词形式，避开 helper、utils，名称里也不能出现 anthropic 和 claude。
  3. 先存一版初稿，描述只写一行：description: Helps with API changes. 这就是要超过的那一版。
  4. 把它改成两半。先写技能做什么，用具体的动词：审查规范里被删掉的字段、改名的路径、变严的校验。再写“Use when”，后面跟使用场景。
  5. 补上不提主题的请求。Agent Skills 指南让你把适用场景列出来，即使用户没有明说那个领域，所以示例最后写了 even if they never say "breaking change"。
  6. 保存后，问 Claude Code：What skills are available?，确认技能在列表里。再用自己的话提需求，比如“这个 API 改动能发布吗？”。没有任何反应的话，运行 /reviewing-api-changes 按名字直接调用。

智能体做决定之前读到什么

启动时，智能体只加载每个技能的名称和描述。请求对上了，它才读完整的 SKILL.md。Agent Skills 指南自己就得出了结论：触发的全部重担都压在描述上。

有一点会改变你的测试方式。智能体往往只在任务需要它自己做不到的知识或能力时才去查技能，所以一个简单的单步请求，哪怕和描述完全吻合，也可能不用技能。技能要在专门的工作上才能触发：不熟悉的格式、公司内部的约定、步骤顺序固定的流程。

Claude Code 还有自己的限制。它会把 description 和 when_to_use 拼在一起，在技能清单里截断合并后的文字，所以放在最后的关键词可能根本到不了模型。装了几十个技能的话，Claude Code 给整份清单的预算也有上限，超出时先丢掉最少用的技能的描述。

描述背后的几个数字

~100

个 token：每个技能的名称和描述在启动时占用的上下文

来源：Claude 平台文档：Agent Skills (2026年11月4日 查阅)

1,024

个字符：开放规范允许的描述长度上限

来源：Agent Skills 规范 (2026年11月4日 查阅)

1,536

个字符：Claude Code 在技能清单里保留的 description 与 when_to_use 合计长度

来源：Claude Code 文档：Skills (2026年11月4日 查阅)

1%

的模型上下文窗口：Claude Code 给整份技能清单的预算

来源：Claude Code 文档：Skills (2026年11月4日 查阅)

同一个技能的三种描述
描述智能体能拿它做什么
Helps with API changes.没有具体的东西可以匹配：没有场景，也没有用户会敲的词。
I can help you review API changes.第一人称。Anthropic 提醒，人称混用会造成技能发现的问题。
Reviews OpenAPI or Swagger spec changes for breaking changes. Use when the user asks whether an API change is safe to ship, even if they never say "breaking change".写清了技能做什么、什么时候该动手，也覆盖了没有点名主题的请求。

技能一声不响的时候

先查 YAML。头信息解析失败时，Claude Code 仍会加载正文，只是元数据全空，所以 /reviewing-api-changes 能用，自动匹配却永远不会发生。用 claude --debug 能看到解析错误，claude plugin validate ~/.claude/skills 能列出头信息解析失败的 SKILL.md（需要 Claude Code v2.1.233 或更高版本）。

YAML 没问题的话，Claude Code 文档给出了后面要查的顺序，见下方。再往后就看清单本身：/doctor 会估算技能清单占用的上下文，/skill-doctor（v2.1.252 或更高版本）会显示每个技能的开销和使用频率。

反过来，技能在不该触发的请求上触发，文档给了两个办法：把描述写得更具体，或者加上 disable-model-invocation: true，让技能只在你输入命令时运行。Agent Skills 指南再加一条：在描述里写明技能不做什么，尤其是和相邻技能交界的地方。

Claude Code 排查技能不触发的顺序

  1. 看描述里有没有关键词

    里面有用户自然会说的词吗？

  2. 问“What skills are available?”

    技能必须出现在回答里。

  3. 换种说法提需求

    试试更接近描述的措辞。

  4. 运行 /skill-name

    技能允许用户调用的话，按名字调用能分清是匹配出了问题，还是加载出了问题。

  5. 检查名称

    命令也认不出来的话，可能是 Claude Code 拒绝了这个名称，比如含有不换行空格或尖括号。

  6. 检查 paths

    设了 paths 的技能，只对 Claude 当前工作目录里的文件才会激活。

Anthropic 的 Alex Albert 和 Boris Cherny 怎么说技能的用处

在 Anthropic 做研究的 Alex Albert，2025 年 10 月在 X 上发布了 Skills。他的发布帖说，技能是打包好的专业知识，由 Claude 按需加载。这正是这一课只盯着一个字段的原因：请求对上之前，Claude 上下文里关于这个技能的，就只有描述。

Claude Code 的作者 Boris Cherny，2026 年 1 月底分享了 Claude Code 团队的技巧。其中一条讲什么时候值得写技能：一天要做不止一次的事。把这件每天都做的事写进描述的“Use when”那一半，用你平时提这个需求时的说法，技能就有了能对上的请求。

一件事一天要做不止一次，就把它做成技能或命令

Boris Cherny, Claude Code 的作者，Anthropic，引文为译文 · X (2026年11月5日 查阅)
Boris Cherny（@bcherny）2026 年 1 月 31 日在 X 上分享的 Claude Code 团队技巧第 4 条：创建你自己的技能并提交到 git，在每个项目里复用。一件事一天要做不止一次，就把它做成技能或命令。
Boris Cherny 在 X 上，2026 年 1 月 31 日
Alex Albert（@alexalbert__）2025 年 10 月 16 日在 X 上的帖子：今天我们在 claude.ai、Claude Code 和 API 里推出 Skills，它让你把专业知识打包成可复用的能力，在智能体处理更复杂的任务时由 Claude 按需加载。
Alex Albert 在 X 上，2025 年 10 月 16 日

X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日，时间为 UTC。X 在第一条帖子处用“Show more”截断了后面的内容。点击截图可到 X 上打开原帖。

常见错误

  • 只介绍技能，没写触发条件。“Helps with X”说的是它是什么，不是什么时候该用它。
  • 把失败的那一条提示里的词照搬进描述。Agent Skills 指南把这叫过拟合，要你找出失败提示共有的那一类需求。
  • 主要用途放在最后。Claude Code 会截断合并后的 description 和 when_to_use，被砍掉的正是末尾。
  • 在描述里写尖括号。Claude Code 会把它们显示成 < 和 >，占位符请改用方括号。
  • 给要带着走的技能加 when_to_use。Claude Code 认它，但 claude.ai 上传只接受规范里的六个字段，多出的键会让上传失败。

自己试一试

拿一个你已有的技能，或者本课的示例，在纸上写六条提示：三条该加载技能，三条不该。三条正例里，有一条要避开技能的主题词。三条反例里，有两条是和技能用词相近的近似请求，比如让它从零写一份 OpenAPI 规范。

每条提示都在新会话里跑一遍，记下命中还是没命中。把这张纸留着，第 3 课会把它变成可重复的测试。

  • 开头几个词有没有用具体的动词点明这项工作？
  • 有没有写明什么时候用？
  • 是不是第三人称？
  • 主要用途是不是放在最前面？
  • 有没有一句话能管到根本没提主题的用户？

下一课

描述能触发，只是做完了一半。第 2 课讲技能加载之后的事：什么留在 SKILL.md，什么挪进 references/ 和 scripts/，以及怎样告诉智能体什么时候去打开每个文件。

claude.ai、开放规范和 Claude Code 各自的长度限制，Mindket 讲怎样创建 Agent Skill 的文章里有一张表，讲什么是 Agent Skills 的那篇则讲这个格式本身。别人写的技能在 Mindket 上以套件的形式上架，想看真实的描述长什么样，可以去翻翻。

自测一下

  1. 下面哪条描述的写法符合这一课的建议？

    查看答案

    C. Reviews OpenAPI spec changes for breaking changes. Use when the user asks whether an API change is safe to ship. 它写清了技能做什么、什么时候用，并且用第三人称，另外两条要么太含糊，要么用了第一人称。

  2. 一个技能输入斜杠命令能用，却从不自己触发，你该先查什么？

    查看答案

    A. frontmatter 能不能被解析，比如用 claude --debug 查看 frontmatter 有错时，正文仍会加载但元数据是空的，所以命令能用，自动匹配却永远不会发生。

  3. 主要用途应该放在描述的什么位置，为什么？

    查看答案

    D. 放在开头，因为 Claude Code 会从末尾开始截断过长的描述 Claude Code 会在技能清单里截断合并后的描述文字，放在最后的关键短语可能根本到不了模型。

  4. 一个技能总在不该触发的请求上触发，哪个办法能保留它，又只在你输入它的命令时才运行？

    查看答案

    B. 设置 disable-model-invocation: true 设置 disable-model-invocation: true 后，技能只在你输入它的命令时运行，另一个办法是把描述写得更具体。

常见问题

技能描述最长能写多少？

开放的 Agent Skills 规范允许最多 1,024 个字符，不过几句话通常就够了。Claude Code 在技能清单里只保留 description 和 when_to_use 合计 1,536 个字符，所以主要用途要写在最前面。

同一条描述能在 Claude Code、Codex 和 Cursor 里通用吗？

基本可以。OpenAI 的 Codex 指南要求描述简短，把用途和触发词放在前面，并写明技能什么时候该触发、什么时候不该。Cursor 的文档对这个字段的定义一样：技能做什么，什么时候用。要带着走的技能，别放 when_to_use 这类额外字段。

Claude Code 里的 when_to_use 是做什么的？

它是个可选字段，用来补充触发场景，比如触发用语或示例请求。Claude Code 会把它接在描述后面放进技能清单，并算进同一个截断上限。它不属于开放规范，所以要带着走的技能，最好把内容都写进 description。

为什么 Claude 有时加载我的技能，有时不加载？

模型的行为不是确定的，同一个请求这次可能加载技能，下次就没有。Agent Skills 指南建议，每条测试提示多跑几次，先从三次起步，再来评判一条描述。

描述里一定要写“Use when”吗？

没有哪条规则要求这几个词，但描述必须写明什么时候该动手。Agent Skills 指南推荐用“Use this skill when...”这样的祈使句式，因为智能体正在判断要不要行动，这句话就是在告诉它。

可以让 Claude 帮我写描述吗？

可以。Anthropic 说 Claude 本身就熟悉技能格式，你可以让它起草。要调优的话，Anthropic 的 skill-creator 插件会生成该触发和不该触发的提示，统计命中率，并提出修改建议。第 3 课会演示。

资料来源

  1. Agent Skills specification (2026年11月4日 查阅)https://agentskills.io/specification
  2. Agent Skills: Optimizing skill descriptions (2026年11月4日 查阅)https://agentskills.io/skill-creation/optimizing-descriptions
  3. Claude Platform docs: Skill authoring best practices (2026年11月4日 查阅)https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
  4. Claude Platform docs: Agent Skills (2026年11月4日 查阅)https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
  5. Claude Code docs: Skills (2026年11月4日 查阅)https://code.claude.com/docs/en/skills
  6. OpenAI: Build skills (Codex) (2026年11月4日 查阅)https://learn.chatgpt.com/docs/build-skills
  7. Cursor docs: Agent Skills (2026年11月4日 查阅)https://cursor.com/docs/context/skills
  8. Boris Cherny on X: tips from the Claude Code team, skills, 31 January 2026 (2026年11月5日 查阅)https://x.com/bcherny/status/2017742748984742078
  9. Alex Albert on X: introducing Skills, 16 October 2025 (2026年11月5日 查阅)https://x.com/alexalbert__/status/1978877498411880550

分享本节课

看看别人写的描述

以套件形式上架的技能会展示名称、描述和背后的文件夹。

浏览套件

本节课的 Markdown 版本 · Agent Skills 课程：写好、测好、装好 SKILL.md 技能 · 全部课程