从零上手 Agent Skills：给 AI 智能体写一份可复用的「技能说明书」

2026年8月14日，Anthropic 开源了 Agent Skills 框架，仓库发布 24 小时内 GitHub 星标突破 16.9 万，被社区称为「AI 智能体的 npm」。其实这套机制并非新事物：它于 2025 年 10 月随 Claude Code 推出，2025 年 12 月 18 日由 Anthropic 发布为开放标准（规范见 agentskills.io）。核心思想一句话：把反复粘贴的提示词，打包成智能体按需加载的「技能文件」。

一、Agent Skills 是什么

Agent Skills 的本质是一个目录，里面必须有一个 SKILL.md 文件，可选带 scripts/（脚本）、references/（参考文档）、assets/（模板资源）。SKILL.md 分两部分：开头的 YAML 元数据 + 后面的 Markdown 指令。

它和 MCP（模型上下文协议）分工不同：MCP 连接外部世界（实时 API、数据库），Skills 编码思考方式（工作流、领域知识、输出规范）。两者互补，常用组合是一个 Skill 定义流程，MCP 提供流程需要的实时数据。

二、关键机制：渐进披露（Progressive Disclosure）

这是 Agent Skills 最精巧的设计，也是它区别于「把说明写进项目规则文件」的原因。规则文件会长期占用上下文，而 Skills 只按需加载：

好处很明显：机器上装几十个技能，日常只付出几十行元数据的上下文成本，真正用到时才读正文。

三、动手写第一个 Skill：5 个步骤

以一个「技术文章写作」技能为例：

第 1 步：识别可复用的流程。 选一个你反复粘贴同样指令的重复性工作——好的技能都始于具体的、令人厌烦的重复。

第 2 步：创建目录结构。 最小形态就是一个文件夹加一个 SKILL.md：

tech-article-writing/
└── SKILL.md

第 3 步：写 SKILL.md。 参考官方 template-skill 骨架（anthropics/skills 仓库的 template 目录）：

---
name: tech-article-writing
description: 撰写 AI 产品、模型评测与科技行业文章。当用户要求写科技类文章、模型对比或产品介绍时使用。
---

# 技术文章写作

## 收到写作任务后
1. 先确认文章核心角度与目标读者
2. 查找一手资料，交叉验证关键事实
3. 按「开头给事实、分节展开、文末给结论」的结构写初稿
4. 检查禁用句式和 AI 味表达，输出前自查一遍

## 输出格式
- 标题用一级标题，正文小节约 300-500 字一节
- 数据尽量用表格呈现
- 文末注明信息来源口径

第 4 步：重点打磨 description。 这是整份文件最重要的一行。智能体靠它决定"这个技能要不要用"，含糊的描述（如"处理文档"）会导致该用时不用、不该用时误用。写法是"做什么 + 什么场景触发 + 不做什么"。

第 5 步：测试与分发。 Anthropic 建议为每个技能准备至少 3 个正向测试用例和 2 个负向用例，验证触发与产出是否符合预期。分发方式：个人用放到 ~/.claude/skills/，团队用提交到仓库的 .claude/skills/，组织级可通过平台配置下发。

四、注意事项

• SKILL.md 正文控制在 500 行以内，接近上限时把细节拆到 references/，否则会拖慢加载。
• 引用层级不要过深。 智能体对嵌套引用可能只读部分内容，references 应直接从 SKILL.md 一级链接，避免 A 引 B、B 引 C 的链式结构。
• 元数据里的 license、allowed-tools 字段：allowed-tools 可限定技能能用的工具，体现最小权限原则；两者都不影响激活，但建议规范填写。
• 不要用规则文件替代 Skills 的场景判断。 通用团队规范适合放规则文件，具体、可复用的任务流程才值得做成 Skill。
• 留意平台差异。 Claude Code 特有的字段（如 context: fork、hooks）在暂不支持的标准运行环境中会被安全忽略，不影响兼容性。

小结

Agent Skills 的价值不在于"多一个配置文件格式"，而在于它把智能体的能力扩展从"写死提示词"变成了"按需加载的模块"。8 月框架开源后，社区仓库已有数百万贡献。对开发者来说，与其继续维护越来越臃肿的提示词库，不如从今天这个最小的 SKILL.md 开始，把你的重复工作流逐个沉淀成可复用、可分享、可版本化的技能。

以上信息为公开报道口径，以官方为准。