Agent Skills 这半年铺得很快，但网上讲概念的多，讲"一个 skill 拆开到底长什么样"的少。这篇从开放标准和官方公开仓库出发，把结构、加载机制和几个容易踩的坑捋一遍。

信息验证截至 2026-10-20。素材来源：Agent Skills 开放标准站点、Anthropic 官方 skill 仓库与文档、公开的第三方整理。

一个 skill 就是一个文件夹

格式上，一个 skill 是一个包含 SKILL.md 的文件夹。文件结构分两部分：YAML frontmatter 写元信息（name、description，以及各客户端可选的扩展字段），后面跟正文指令，文件夹里还可以放脚本、参考文档和模板。

这套格式是开放标准（agentskills.io），所以不只 Claude 能用——Codex、Gemini CLI、GitHub Copilot、Cursor、VS Code、Goose、OpenCode 都读 SKILL.md。纯指令加脚本的 skill 通常能直接跨工具跑；用到某家特有能力的（比如 Claude Code 的 hooks 或它的特定 frontmatter 字段）需要改一点。

关键机制：description 驱动的渐进式披露

这是最容易理解错的一点。装了 skill 不等于它一直在消耗上下文，加载分三层：

层级	加载内容	何时加载
1	name + 一句话 description	每轮都加载，对所有已装 skill
2	SKILL.md 正文（指令、示例、边界）	模型判断相关时才加载
3	附带的脚本、参考文档、模板	正文指令指名调用时

第一层每个 skill 大约百来个 token 的量级；第二层视内容从几百到几千 token。只有 description 是每轮都在竞争注意力的，所以它的写法直接决定这个 skill 会不会被用上。

写"处理季度销售报表"太泛，模型要么在不该触发时触发，要么干脆不触发；写成触发条件才准——比如"把 CRM 导出的原始 CSV 整理成四段式季度报表模板，含预测偏差列"。有实践者提到另一个有效做法：在 description 里显式写"不适用于……"，用排除条件挡掉误触发。

装在哪里、谁能用

按 Anthropic 官方文档的划分：

使用面	怎么装	谁能用	运行时
Claude Code	复制文件夹到用户级或项目级的 skills 目录，或装插件	你自己、你的仓库，或拿到插件的人	完整网络访问
claude.ai / Cowork	设置里上传 zip（需开启代码执行）	只有你本人	取决于设置
Claude API	通过 /v1/skills 端点上传	整个工作区	无网络访问、不能装包

一个官方说明里写得很清楚、但常被忽略的点：自定义 skill 不在各个使用面之间同步。上传到 claude.ai 的不会出现在 API 里，两边也都不会出现在 Claude Code 里。

官方仓库里有什么

Anthropic 的公开仓库 anthropics/skills 是很多人第一站，2026 年 9 月底约 17.9 万 star，含 19 个 skill 文件夹；文档类四个（docx、xlsx、pptx、pdf）是 source-available 而非开源，其余多数 Apache 2.0。README 自称是演示与教学材料，要求使用者自行测试——这个态度对任何 skill 都适用。

常被点名的几个：skill-creator（写 skill、跑 A/B 评测、调 description）、frontend-design（把 UI 从模板化默认样式里推出来）、mcp-builder（指导用 FastMCP 或 TypeScript 写 MCP server）、webapp-testing（用 Playwright 驱动本地 Web 应用做截图与 UI 检查）、claude-api（加载当前的 API 与 SDK 参考，避免模型凭记忆写出过期的调用）。

两个成本项

一是上下文预算。 在 Claude Code 里，已装 skill 的列表预算大约是上下文窗口的 1%。装一堆不用的 skill，会把有用的那些挤出预算——所以建议先装两三个对得上日常任务的，很少超过十个。有工具会列出每个 skill 的开销和从未被调用过的那些，方便定期清理。

二是重叠冲突。 两个写作风格类 skill 同时装，会给出互相矛盾的指令。同类只留一个。

常见问题

Q：skill 和 MCP 有什么区别？

skill 是"教模型怎么做"，MCP 是"给模型接一个活数据源"。只让模型记住格式规范用 skill；真要连实时数据才上 MCP，后者要花一下午配鉴权，还得长期维护。

Q：热门就等于好用吗？

不等于。star 数衡量的是关注度不是质量，更不是安全审查。装载之前读一遍 SKILL.md 和它附带的脚本，这个习惯比看排名有用。

Q：怎么判断一个 skill 到底有没有用？

别看 README 里的示例，拿自己真实的任务跑。有工具会做 A/B——同一批 prompt 装与不装各跑一遍，对比通过率、耗时和 token 开销。

参考

• Agent Skills 开放标准：agentskills.io
• Anthropic Agent Skills 文档：platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• Anthropic 官方仓库：github.com/anthropics/skills
• 社区目录：ComposioHQ/awesome-claude-skills、VoltAgent/awesome-agent-skills