通过 Agent Skills 管理上下文

研究现有流程如何使用 Agent Skills 模块化管理上下文

前言

使用 Agentic AI 解决问题时,上下文管理至关重要,而 Anthropic 推出的 Agent Skills🔗 上下文管理模式近期也成为业界的一种主流标准,在 Claude Code🔗、Codex🔗、Opencode🔗 等工具中都有支持。通过研究如何将其整合进现有流程,可以提升开发效率。

现有问题

项目积累了许多与项目相关的文档。以我的案例来说,记录了一系列针对特定项目的文档;真实情况也可能不一定与程序开发相关,而是不同领域相关的知识、规则或示例:

project
├── xxx.md
├── HowToFetchData.md
├── HowToFormValidation.md
├── HowToOrganizeComponent.md
└── HowToTesting.md

例如要写测试,就可以把相关领域文档拿出来丢给 Agentic AI:

Terminal window
基于 @HowToTesting.md,完成 @Foobar.test.ts 中的测试

可以说这是最直白、灵活的上下文管理方式,但这样的工作方式仍然像一盘散沙,需要通过命令为每一次指令进行指定:

  • 上下文遗漏:可能忘记提供关键文档,导致 AI 生成不符合项目规范的代码。
  • 重复性工作:每次对话都需要重新指定上下文。
  • 没有特别规范:格式随意。

通过 Agent Skills 自动管理上下文

想要更智能地让 Agent 自行判断并抓取相关上下文,就可以通过 Skills 实现。其运行关键是「渐进式揭露」,在每次 Agent 执行时,只在需要时加载 Skills 上下文:

  • 探索:Agent 仅加载每个可用技能的 name 和 description 元数据,判断其是否与当前任务相关
  • 启动:当任务与技能描述匹配时,Agent 会读取完整的 SKILL.md 指令并将其应用到上下文中
  • 执行:按需加载引用的文件或执行捆绑的代码
Terminal window
my-skill/
├── SKILL.md # 必需: 指令 + 元数据
├── scripts/ # 可选: 可执行代码
├── references/ # 可选: 可动态引用文档
└── assets/ # 可选: 静态资源

使用 Scripts 的例子

举例来说,我的项目有一个生成 OpenAPI🔗 脚本的步骤,包装在 swagger.sh shell script 里面,通常会在开发结束后执行,以便生成 API 文档;这就可以通过编写技能及其关联文档来揭露特定技能。

Terminal window
swagger/
├── SKILL.md
└── scripts/
└── doc-gen.sh
SKILL.md
---
name: swagger
description: 使用 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 中,可以这样引用这些文件:

SKILL.md
---
name: complete-skill
description: 处理数据并生成报告的完整技能,包含参考文档和静态资源
---
## 功能说明
此技能用于处理数据并生成报告。
## 详细参考
请参阅 [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

可以相互辅助的关系
  1. 用提示词指挥 Agent
  2. 用 Skills 规划特定领域知识上下文,传授智能体特定流程
  3. 用 MCP 可靠、统一地整合所有外部能力

使用 Agent Skills 是不是意味着无限的上下文?

大量 Skills 仍会提高 AI Agent 错误引用的概率

使用 Agent Skills 并不意味着真正无限的上下文窗口,而是通过渐进式揭露(progressive disclosure)和外部执行机制,有效管理模型上下文。

延伸阅读