第 11 章：Agent Skills

本章导读

• 核心问题：如何把一类任务的方法沉淀成可复用 Skill。
• 关键词：Skill、SKILL.md、Progressive Disclosure、Examples、Resources、Scripts
• 学习产出：把 CI 失败分析沉淀为 ci-failure-analysis Skill。

1. 本章要解决什么问题

前两章讨论了 Tool：Agent 如何行动，以及多个工具如何被编排。

但真实工作不只需要工具。

例如一个企业研发 Agent 即使拥有这些工具：

read_file
search_code
apply_patch
run_tests
get_git_diff

它仍然可能不知道：

• 这个公司如何写单元测试；
• 这个项目如何做数据库迁移；
• 这个团队如何写 PR 描述；
• 这个领域如何分析风险；
• 这个文档格式有什么规范；
• 这个任务应该遵循什么操作流程。

这些不是 Tool 能解决的问题。

Tool 提供“能做什么”。

Skill 提供“如何做好一类事情”。

本章核心观点是：

Skill 是把过程性知识、领域知识、示例、资源和可执行代码打包给 Agent 的能力单元。

本章回答：

• 什么是 Agent Skill；
• Skill 与 Prompt、Tool、Memory 的区别；
• Skill 的基本组成是什么；
• 为什么 Skill 需要 progressive disclosure；
• 企业如何建设 Skill Registry；
• 如何在 Java / Spring Boot Agent Framework 中落地 Skill。

2. 对应 Anthropic 文章

本章主要对应 Anthropic Engineering 的文章：

• Equipping agents for the real world with Agent Skills

Anthropic 对 Skills 的定义非常清晰：

Skills are organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.

也就是说，Skill 不是一段 Prompt，而是一个文件夹化、可发现、可动态加载的能力包。

Anthropic 还把 Skills 类比为“给新员工的 onboarding guide”。

这个类比很重要。

一个新员工即使很聪明，也需要知道：

• 公司流程；
• 项目规范；
• 工具用法；
• 常见坑；
• 示例模板；
• 领域知识。

Agent 也一样。

3. Skill 与 Prompt、Tool、Memory 的区别

3.1 Prompt：当前任务的临时指令

Prompt 适合表达当前任务要求，例如：

请为 OrderService 增加单元测试。
要求覆盖用户未登录场景。

Prompt 的特点：

• 临时；
• 面向当前任务；
• 生命周期短；
• 不一定可复用。

3.2 Tool：可执行动作

Tool 适合表达 Agent 可以调用的外部能力，例如：

search_code
read_file
run_tests
create_jira_issue

Tool 的特点：

• 动作明确；
• 输入输出结构化；
• 可执行；
• 有权限和审计。

3.3 Memory：历史经验和偏好

Memory 保存跨会话经验，例如：

用户喜欢简洁回答。
这个项目修改状态枚举时必须同步状态机。

Memory 的特点：

• 来自历史；
• 需要检索；
• 需要治理；
• 可能过期或错误。

3.4 Skill：可复用做事方法

Skill 描述如何完成一类任务。

例如：

Spring Boot 单元测试生成 Skill
数据库迁移 Skill
PR Review Skill
CI 失败分析 Skill
OpenAPI 文档生成 Skill

Skill 的特点：

• 可复用；
• 面向任务类型；
• 可以包含说明、知识、示例、资源和脚本；
• 可动态加载；
• 可以组合 Tool。

可以这样理解四者关系：

Prompt：这次要做什么
Tool：可以调用什么动作
Memory：过去学到了什么
Skill：这类事应该怎么做

4. Skill 的组成

Anthropic 的 Skill 以目录为单位，最小结构是：

my-skill/
  SKILL.md

更完整的结构可以是：

spring-boot-test-skill/
  SKILL.md
  examples/
    service-test.md
    controller-test.md
  scripts/
    detect-test-command.sh
  resources/
    junit5-cheatsheet.md
    mockito-guidelines.md

4.1 SKILL.md

SKILL.md 是 Skill 的入口。

它通常包含 YAML frontmatter：

---
name: spring-boot-unit-test
description: Use this skill when writing or fixing unit tests for Spring Boot services using JUnit 5 and Mockito.
---

然后是正文：

# Spring Boot Unit Test Skill

## When to use

Use when the task asks to add, fix, or review unit tests for Spring Boot service classes.

## Procedure

1. Identify the class under test.
2. Find existing tests with similar patterns.
3. Prefer constructor injection.
4. Use Mockito only for external dependencies.
5. Run the targeted Maven test command.

## Output

Return changed files, test command, and test result.

4.2 Instruction

Instruction 是 Skill 的核心流程说明。

它回答：

遇到这类任务时应该怎么做？
步骤是什么？
注意事项是什么？
完成标准是什么？

Instruction 应具体、可执行。

坏例子：

请写高质量测试。

好例子：

先搜索同包下已有测试，复用项目中的 fixture builder。
新增 service 层逻辑时，至少覆盖成功路径和一个失败路径。
运行 ./mvnw -Dtest=ClassNameTest test 验证。

4.3 Knowledge

Knowledge 是领域知识。

例如 Spring Boot 测试 Skill 可能包含：

• JUnit 5 注解；
• Mockito 使用规范；
• 项目测试分层；
• 常见断言；
• fixture 约定。

Knowledge 不应该变成百科全书。

它应该围绕当前 Skill 的任务范围组织。

4.4 Examples

示例对 Agent 非常重要。

例如：

一个 service 测试示例
一个 controller 测试示例
一个异常路径测试示例
一个反例：不要 mock 被测对象本身

示例可以让模型更容易遵循团队风格。

但示例也占用上下文，所以应通过 progressive disclosure 动态加载。

4.5 Resources

Resources 是附加资料。

例如：

• 模板文件；
• 参考文档；
• 检查清单；
• API 说明；
• 领域词汇表。

Agent 不一定一开始加载全部资源，而是在需要时读取。

4.6 Code / Scripts

Skill 可以包含脚本或代码。

例如：

scripts/detect-test-command.sh
scripts/extract-openapi.py
scripts/validate-pr-description.js

这很重要，因为 Skill 不只是“告诉 Agent 怎么做”，还可以提供可执行辅助工具。

5. Progressive Disclosure：渐进式加载

Anthropic 的 Skills 设计中，一个关键思想是 progressive disclosure。

也就是：

第一层：只加载所有 Skill 的 name 和 description
第二层：任务相关时加载 SKILL.md 全文
第三层：需要时再读取 examples、resources、scripts

这样做的原因是：

• Skill 可能很多；
• 全部加载会占满上下文；
• 大部分任务只需要少数 Skill；
• Agent 需要先知道有哪些 Skill 可用，再决定加载哪个。

这和 Tool Selection 非常类似。

企业平台不应该把所有 Skill 全部注入模型。

而应该：

根据任务 → 选择候选 Skill → 加载 Skill 摘要 → 必要时加载详细资源

6. Skill 生命周期

企业 Skill 应该有完整生命周期。

Create
  ↓
Review
  ↓
Test
  ↓
Publish
  ↓
Use
  ↓
Monitor
  ↓
Update / Deprecate

6.1 Create

由工程师、架构师、平台团队或 Agent 辅助创建。

6.2 Review

Skill 会影响 Agent 行为，因此必须评审：

• 是否包含敏感信息；
• 是否指令清晰；
• 是否与公司规范一致；
• 是否有过期风险；
• 是否包含危险操作。

6.3 Test

Skill 应有测试任务。

例如 Spring Boot Test Skill 可以用几个样例项目验证。

6.4 Publish

发布到 Skill Registry。

应记录版本、作者、适用范围、依赖工具。

6.5 Monitor

监控 Skill 使用效果：

• 被加载次数；
• 成功率；
• 常见失败；
• 用户反馈；
• token 成本。

6.6 Update / Deprecate

项目规范变化时，Skill 也要更新。

过期 Skill 应下线或标记 deprecated。

7. 架构图 / 流程图

7.1 Skill 结构

7.2 Skill 加载流程

7.3 Skill 与 Tool 的关系

8. Java / Spring Boot 落地方案

8.1 SkillMetadata

public record SkillMetadata(
    String name,
    String description,
    String version,
    Set<String> tags,
    Set<String> requiredTools,
    SkillScope scope
) {}

8.2 Skill

public record Skill(
    SkillMetadata metadata,
    String instruction,
    List<SkillResource> resources,
    List<SkillExample> examples,
    List<SkillScript> scripts
) {}

8.3 SkillRegistry

public interface SkillRegistry {
    List<SkillMetadata> listMetadata(SkillSelectionRequest request);
    Optional<Skill> load(String skillName, SkillLoadOptions options);
    void publish(Skill skill);
}

8.4 SkillSelector

public interface SkillSelector {
    List<SkillMetadata> select(
        AgentTask task,
        AgentContext context,
        List<SkillMetadata> candidates
    );
}

Skill 选择可以根据：

• 任务类型；
• 关键词；
• 项目技术栈；
• 用户角色；
• 可用工具；
• 历史效果。

8.5 SkillContextInjector

public interface SkillContextInjector {
    List<ContextChunk> inject(List<Skill> skills, ContextBudget budget);
}

注入时要控制预算。

通常只注入：

• Skill 名称；
• 使用场景；
• 核心步骤；
• 当前任务相关示例。

资源和脚本保留引用，按需加载。

8.6 Skill 文件解析

SKILL.md 可以用 YAML frontmatter：

public interface SkillParser {
    Skill parse(Path skillDirectory);
}

解析结果：

metadata ← YAML frontmatter
instruction ← Markdown body
resources ← resources/ directory
examples ← examples/ directory
scripts ← scripts/ directory

9. 企业案例：Spring Boot 单元测试 Skill

目录：

skills/spring-boot-unit-test/
  SKILL.md
  examples/
    service-test.md
    controller-test.md
  resources/
    junit5.md
    mockito.md

SKILL.md：

---
name: spring-boot-unit-test
description: Use when adding or fixing unit tests for Spring Boot services using JUnit 5 and Mockito.
version: 1.0.0
requiredTools:
  - search_code
  - read_file_range
  - run_test_command
---

# Spring Boot Unit Test Skill

## Procedure

1. Identify the class under test.
2. Search for existing tests in the same package.
3. Follow project fixtures and naming conventions.
4. Cover success and failure paths.
5. Run targeted tests before final answer.

## Rules

- Do not mock the class under test.
- Prefer constructor injection.
- Do not introduce new test dependencies without approval.
- Report the exact test command and result.

这个 Skill 能让 Agent 更稳定地完成同类任务。

10. 常见误区

10.1 把 Skill 当成长 Prompt

Skill 不是一段很长的 Prompt，而是可发现、可加载、可组合的能力包。

10.2 所有 Skill 全量注入

这会污染上下文。

应采用 progressive disclosure。

10.3 Skill 没有版本

Skill 会随组织规范变化，必须版本化。

10.4 Skill 没有测试

Skill 会改变 Agent 行为，应像代码一样测试。

10.5 Skill 与 Tool 边界混乱

Tool 是动作，Skill 是方法。

不要把业务流程全部塞进 Tool，也不要让 Skill 承担实际执行。

11. 贯穿案例：CI 失败分析 Agent

CI 失败分析适合沉淀为一个 Skill。

Skill 名称可以是：

ci-failure-analysis

它不是工具，而是一套分析方法。

SKILL.md 可以定义：

When to use:
  当用户要求分析 CI、构建、测试或流水线失败时使用。

Procedure:
  1. 先读取 CI 失败摘要。
  2. 判断失败类型：test、compile、dependency、infra、lint。
  3. 对测试失败，提取 failed test、exception、key stack frame。
  4. 对比最近 Git Diff。
  5. 只读取相关代码片段。
  6. 输出 evidence-backed report。

Rules:
  - 只读模式下不能声称已修复。
  - 每个根因判断必须有证据。

这个 Skill 可以复用 summarize_ci_failure、get_git_diff、search_code、read_file_range 等工具。

它体现了 Skill 与 Tool 的区别：Tool 负责读取日志和代码，Skill 负责告诉 Agent 如何分析 CI 失败。

12. 本章小结

本章讨论了 Agent Skills。

核心结论：

1. Skill 提供可复用的任务方法，而不仅是临时指令。
2. Skill 可以包含 Instruction、Knowledge、Examples、Resources、Code。
3. Skill 与 Prompt、Tool、Memory 各有边界。
4. Progressive disclosure 是 Skill 可扩展的关键。
5. 企业应建设 Skill Registry，并对 Skill 做版本、评审、测试和监控。

一句话总结：

Tool 让 Agent 能做事，Skill 让 Agent 知道一类事情应该怎么做。

13. 实践任务

任务 1：设计一个 Skill

选择一个任务，设计 Skill 目录：

skills/your-skill/
  SKILL.md
  examples/
  resources/
  scripts/

任务 2：编写 SKILL.md

要求包含：

• name；
• description；
• when to use；
• procedure；
• rules；
• output format；
• required tools。

任务 3：实现 SkillRegistry

用 Java 实现一个本地文件系统 SkillRegistry，能扫描 skills/ 目录并读取 metadata。

任务 4：设计 Skill 评估任务

为你的 Skill 准备 3 个测试任务，观察 Agent 是否更稳定地完成任务。