前言
使用 Agentic AI 解决问题时,上下文管理至关重要,而 Anthropic 推出的 Agent Skills 上下文管理模式近期也成为业界的一种主流标准,在 Claude Code、Codex、Opencode 等工具中都有支持。通过研究如何将其整合进现有流程,可以提升开发效率。
现有问题
项目积累了许多与项目相关的文档。以我的案例来说,记录了一系列针对特定项目的文档;真实情况也可能不一定与程序开发相关,而是不同领域相关的知识、规则或示例:
project├── xxx.md├── HowToFetchData.md├── HowToFormValidation.md├── HowToOrganizeComponent.md└── HowToTesting.md例如要写测试,就可以把相关领域文档拿出来丢给 Agentic AI:
基于 @HowToTesting.md,完成 @Foobar.test.ts 中的测试可以说这是最直白、灵活的上下文管理方式,但这样的工作方式仍然像一盘散沙,需要通过命令为每一次指令进行指定:
- 上下文遗漏:可能忘记提供关键文档,导致 AI 生成不符合项目规范的代码。
- 重复性工作:每次对话都需要重新指定上下文。
- 没有特别规范:格式随意。
通过 Agent Skills 自动管理上下文
想要更智能地让 Agent 自行判断并抓取相关上下文,就可以通过 Skills 实现。其运行关键是「渐进式揭露」,在每次 Agent 执行时,只在需要时加载 Skills 上下文:
- 探索:Agent 仅加载每个可用技能的
name和description元数据,判断其是否与当前任务相关 - 启动:当任务与技能描述匹配时,Agent 会读取完整的
SKILL.md指令并将其应用到上下文中 - 执行:按需加载引用的文件或执行捆绑的代码
my-skill/├── SKILL.md # 必需: 指令 + 元数据├── scripts/ # 可选: 可执行代码├── references/ # 可选: 可动态引用文档└── assets/ # 可选: 静态资源使用 Scripts 的例子
举例来说,我的项目有一个生成 OpenAPI 脚本的步骤,包装在 swagger.sh shell script 里面,通常会在开发结束后执行,以便生成 API 文档;这就可以通过编写技能及其关联文档来揭露特定技能。
swagger/├── SKILL.md└── scripts/ └── doc-gen.sh---name: swaggerdescription: 使用 swaggo/swag 为 Go 项目提供完整的 Swagger 文档管理---
## 我能做什么
此技能包含 `scripts/doc-gen.sh` 脚本,并提供在 Go 项目中管理 Swagger API 文档的指引:
...使用 references 和 assets 的例子
为了更好地说明 references/ 和 assets/ 的使用,以下是一个更完整的技能示例,包含 references 与 assets 目录:
complete-skill/├── SKILL.md├── scripts/│ └── process-data.sh├── references/│ ├── API_REFERENCE.md│ └── error-codes.md└── assets/ ├── templates/ │ └── config-template.json └── diagrams/ └── workflow.png在 SKILL.md 中,可以这样引用这些文件:
---name: complete-skilldescription: 处理数据并生成报告的完整技能,包含参考文档和静态资源---
## 功能说明
此技能用于处理数据并生成报告。
## 详细参考
请参阅 [API 参考](references/API_REFERENCE.md) 获取完整的 API 文档。
如果遇到错误,请检查 [错误代码表](references/error-codes.md)。
## 使用示例
使用 [配置模板](assets/templates/config-template.json) 作为起点。
工作流程图请参考 [工作流程图](assets/diagrams/workflow.png)。这样,Agent 可以在需要时动态加载这些额外资源,而不会在初始加载时占用过多上下文。
元数据规范
元数据 = 用于描述数据的数据,会存放在 Markdown 格式开头的 frontmatter 中。不同规范有各自扩展的元数据,因此可以参考所用工具的文档。
name- 最多 64 个字符
- 必须只包含小写字母、数字和连字符
- 不能包含 XML 标签
- 不能包含保留字:「anthropic」、「claude」
description- 不能为空
- 最多 1024 个字符
- 不能包含 XML 标签
MCP vs Agent Skills
可以相互辅助的关系
- 用提示词指挥 Agent
- 用 Skills 规划特定领域知识上下文,传授智能体特定流程
- 用 MCP 可靠、统一地整合所有外部能力
使用 Agent Skills 是不是意味着无限的上下文?
大量 Skills 仍会提高 AI Agent 错误引用的概率
使用 Agent Skills 并不意味着真正无限的上下文窗口,而是通过渐进式揭露(progressive disclosure)和外部执行机制,有效管理模型上下文。
延伸阅读
- Agent Skills - Claude Docs
- Agent Skills - agentskills.io
- Agent Skill 从使用到原理,一次讲清 - 马克的技术工作坊
- When Single-Agent with Skills Replace Multi-Agent Systems and When They Fail