什么是 Agent Skills？

技能怎样一步步加载

一个叫 writing-release-notes 的技能装好以后，智能体并不读它，直到有人要一份最近上线内容的总结。这个请求和描述吻合，智能体才打开 SKILL.md 照着步骤做，第一步是运行附带的脚本。

Anthropic 把这种做法叫作渐进式披露：名称和描述一开始就在上下文里，其余内容都等到用时再读。按开放规范的估算，这一层每个技能约 100 token，装二十个也就 2,000 token 左右，而且一个都还没触发。

步骤里要运行附带的脚本时，脚本代码不进上下文，进去的只有运行结果。在 Anthropic 的 PDF 示例里，填表说明单独放在 forms.md 中，真要填表时 Claude 才会打开它。

两张都是 X 官方嵌入组件的截图，11 月 3 日截取，时间按美国太平洋时间显示。

SKILL.md 文件里写什么

规范要求 SKILL.md 的 YAML 头信息（frontmatter）里有两个字段。name 只能用小写字母、数字和连字符，还得和文件夹同名。description 写清技能做什么、什么时候用。头信息下面是用 Markdown 写的说明，格式随你定。发布说明技能的示例只多加了一个可选字段 license。

---
name: writing-release-notes
description: Writes release notes from a git log or a list of merged pull requests. Use when the user asks for release notes, a changelog entry or a summary of what shipped, even if they do not say "release notes".
license: MIT
---

# Writing release notes

1. Run scripts/group_commits.py to sort the commits into Added, Changed and Fixed.
2. Write one plain sentence per change, in the past tense, with what the user sees first.
3. Leave out refactors and dependency bumps unless they change behavior.
4. For wording rules and examples, read references/style.md.

## Gotchas

- Merge commits repeat the pull request title. Skip them.
- Never invent a version number. Ask if the user did not give one.

• scripts/：智能体能运行的代码。Python、Bash、JavaScript 都常见，能跑哪种要看智能体。
• references/：篇幅较长的文档，比如示例里提到的 style.md，或者一份 API 参考。
• assets/：模板、图片，以及查找表之类的数据文件。

哪些智能体能读 Agent Skills？

有五款编程智能体在文档里写明支持。照它们自己列的位置，没有哪个文件夹能让五个都读到。Claude Code、Cursor 和 Copilot 读 .claude/skills/，.agents/skills/ 则覆盖下表里除 Claude Code 以外的所有智能体。

这种格式由 Anthropic 开发，用在 Claude.ai、Claude Code、Claude Agent SDK 和 Claude 开发者平台上，后来又作为开放标准发布。Codex 的技能也建立在这个标准之上。

Claude.ai 和 Claude API 不读文件夹，只收上传。在 Claude.ai 里，先打开代码执行，再到 Customize > Skills 上传 zip 文件。本文早先的版本说入口在设置里，现已改正。用 API 的话，通过 Skills API 上传，再在请求里把技能和代码执行工具一起指定。

技能和 MCP 服务器是一回事吗？

不是。发布说明技能告诉智能体先做什么、后做什么，哪些合并提交要跳过。假如合并的拉取请求存在智能体访问不到的系统里，要读到它们就得靠 MCP 服务器。MCP 的文档称它是连接 AI 应用与外部系统的开源标准，外部系统包括文件、数据库和搜索引擎等。

技能靠什么触发

智能体决定加不加载一个技能时，读过的只有描述。所以示例的描述把别人可能的问法都列了进去，连“总结一下上线了什么”也算上。规范的描述写作指南拿 Helps with PDFs. 当反面例子，正面例子则写明要做的事：提取文字和表格、填写表单、合并文件。

描述写得再好，简单请求也可能触发不了。智能体通常只在任务超出自己能应付的范围时才去查技能，所以“读一下这个 PDF”这种一步就能做完的请求，未必会用上对应的技能。模型输出还带随机性，同一个请求这次触发了，下次可能就没有。每条测试提示都多跑几遍，近似的提示也算上，看技能是不是每次都被触发。

技能一触发，SKILL.md 的每一行都要占上下文。所以 Agent Skills 指南建议控制在 500 行以内，细节挪进 references/，并写明什么时候读哪个文件。“如果 API 返回非 200 状态码，就读 references/api-errors.md”，比笼统一句“详见 references/”好得多。Anthropic 提醒，被其他参考文件再次引用的文件，Claude 可能只看个开头，所以参考文件从 SKILL.md 出发只嵌一层。

装别人写的技能安全吗？

读过之前，别当它安全。技能会给智能体下指令，还可能给它代码，坏技能两样都能拿来作恶，所以 Anthropic 建议只从可信来源安装技能。

在 Claude Code 里，技能的代码和你电脑上的其他程序一样能联网。从网上下载一份发布说明技能，它运行 scripts/group_commits.py 时就有这样的网络权限。同一个脚本放到 Claude API 上，就跑在沙箱里，既不能联网，也不能装软件包。

Anthropic 的文档说，要像对待安装的软件那样对待技能。来源不太可靠的技能，启用之前先读 SKILL.md、scripts/ 里的每个文件和代码依赖。看到意外的网络请求、异常的文件访问，或者数据经由工具外泄，就该停手。再查一遍文件里有没有指向项目以外的路径，或者把智能体引向不可信外部来源的指令，然后先放进临时项目里试。从外部网址取内容的技能，安全与否还取决于那些网页，而网页在你检查过之后仍可能被改。

对用 GitHub CLI 安装的技能，GitHub 说得更直白：它们未经 GitHub 验证，可能含有提示注入、隐藏指令或恶意脚本。

可选字段 allowed-tools 能预先批准 shell 工具，这样运行终端命令前就不会再问你。规范把这个字段标为实验性，各家智能体支持得不一样。比如 Gemini CLI，激活技能之前会先请你确认。

去哪里找技能，又怎样分享自己的

anthropics/skills 仓库里放着 Anthropic 自己的示例技能，很多是 Apache 2.0 开源的，Word、PDF、PowerPoint 和 Excel 这几个则只是源码可见。README 说它们都是演示材料，要你先在自己的环境里测一遍。在 Claude Code 里运行 /plugin marketplace add anthropics/skills，就能把这个仓库加成插件市场。想把自己的技能交给仓库以外的人，Anthropic 推荐的也是插件。

Mindket 是独立商店，和 Anthropic、OpenAI、Google 都没有关联，也没有得到它们的认可。它的技能页上是粘贴进 AI 对话用的提示词技能，和 SKILL.md 文件夹不是一回事。它的 MCP 服务器页面上，每个条目都附有把那个服务器加进 Claude Code 的命令。你写过别人也用得上的技能，可以在这里出售，免费或用积分计价都行。它的套件是现成文件的 zip 包，有的带着给 Claude Code 用的 skills 文件夹。

下方来源列表里的页面，我们在 2026 年 11 月 2 日读过，GitHub 文档、规范、Anthropic 的工程文章和两份更新日志次日又读了一遍。我们没有实测任何技能。各产品版本之间，文件夹名称和可选字段也会变。

常见问题

资料来源

1. Anthropic 工程博客：用 Agent Skills 为智能体配备应对真实世界的能力 (2026年11月3日 查阅)https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
2. Agent Skills 规范 (2026年11月3日 查阅)https://agentskills.io/specification
3. Agent Skills 概览 (2026年11月2日 查阅)https://agentskills.io/home
4. Agent Skills：技能创作者的最佳实践 (2026年11月2日 查阅)https://agentskills.io/skill-creation/best-practices
5. Agent Skills：优化技能描述 (2026年11月2日 查阅)https://agentskills.io/skill-creation/optimizing-descriptions
6. Agent Skills：在技能中使用脚本 (2026年11月2日 查阅)https://agentskills.io/skill-creation/using-scripts
7. Claude Platform 文档：Agent Skills 概览 (2026年11月2日 查阅)https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
8. Claude Platform 文档：技能编写最佳实践 (2026年11月2日 查阅)https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
9. Claude 帮助中心：在 Claude 中使用技能 (2026年11月2日 查阅)https://support.claude.com/en/articles/12512180-using-skills-in-claude
10. GitHub：anthropics/skills 仓库 (2026年11月2日 查阅)https://github.com/anthropics/skills
11. OpenAI：为 ChatGPT 和 Codex 构建技能 (2026年11月2日 查阅)https://learn.chatgpt.com/docs/build-skills
12. GitHub 文档：关于 Agent Skills (2026年11月2日 查阅)https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
13. GitHub 文档：为 Copilot 创建智能体技能 (2026年11月3日 查阅)https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills
14. VS Code 文档：在 VS Code 中使用 Agent Skills (2026年11月2日 查阅)https://code.visualstudio.com/docs/copilot/customization/agent-skills
15. Cursor 文档：Agent Skills (2026年11月2日 查阅)https://cursor.com/docs/context/skills
16. Gemini CLI 文档：Agent Skills (2026年11月2日 查阅)https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md
17. Model Context Protocol：什么是 MCP？ (2026年11月2日 查阅)https://modelcontextprotocol.io/docs/getting-started/intro
18. GitHub 更新日志：GitHub Copilot 现已支持 Agent Skills (2026年11月3日 查阅)https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/
19. Cursor 更新日志 2.4：子智能体、技能和图像生成 (2026年11月3日 查阅)https://cursor.com/changelog/2-4