中文译本。原文见同目录 README.md

第 17 课：Agent Skills（技能）—— 面向 Agent 的可复用知识

简介

在 第 3 课 中，我们学习了 tools（工具）—— 让 Agent 能调用 API、查询数据库、运行代码等采取行动的函数。Tools 关注的是 做事。

Skills（技能）关注的是 懂事。一个 skill 把领域专长——说明、最佳实践、决策框架和参考材料——打包成模块化单元，Agent 可在需要时发现并使用。

可以这样理解差别：给人一把扳手（tool）和给人一本维修手册（skill）。扳手让他们能拧螺栓；手册告诉他们该拧哪些螺栓、按什么顺序、要注意什么。

ELI5：把 skills 想成厨房里的菜谱卡

专业厨房有 tools（刀、锅、烤箱）和菜谱卡。新厨师可以不看说明就拿起刀。但要做一道特定菜，就需要菜谱卡——告诉他们用哪些工具、什么顺序、什么温度、成品应是什么样子。

Agent skills 也一样。它们是菜谱卡，告诉 Agent 如何处理某类任务、用哪些 tools、好的输出长什么样。

核心要点： Skills 把领域专长编码成可移植、可复用的包。Tools 让 Agent 能行动；Skills 告诉 Agent 如何以及何时行动。

为什么需要 skills

设想这个场景：团队有一个协助 code review 的 Agent。你希望它遵循团队特有的审查清单、标出你们关心的常见模式，并以特定方式组织反馈。

你可以把这些都塞进 Agent 的 system prompt。但 system prompt 很快会挤爆。若把审查说明、部署流程、文档标准和测试约定全塞进一个 prompt，结果是臃肿的 context window，以及样样通、样样松的 Agent。

Skills 通过以下方式解决这个问题：

1. 单独打包专长 —— 每个 skill 是独立文件，聚焦一个领域
2. 按需加载 —— 只在相关时加载 skill，节省 context window 空间
3. 跨团队共享 —— 写得好的 skill 可在项目与 Agent 间复用
4. 独立迭代 —— 更新 skill 不必改 Agent 的核心配置

Context window 问题

这是关键技术动机。Context window 里的每个 token 都有成本——金钱与注意力。若启动时加载 50,000 tokens 的说明，Agent 每一轮都要付这笔账，即使大部分说明与当前任务无关。

Skills 用 progressive disclosure（渐进披露）压低成本：

• 启动时只加载 skill 的名称与描述（每个约 ~100 tokens）
• 触发某个 skill 时，再加载完整说明
• 仅在说明明确需要时才加载参考材料

有分析显示，这种方式可将约 150,000 tokens 的工作流在启动时压到大约 2,000 tokens。

Skill 规范

Skills 遵循在 agentskills.io 维护的开放规范。格式很简单：

目录结构

my-skill/
  SKILL.md          # Required: metadata + instructions
  references/       # Optional: additional documentation
  assets/           # Optional: templates, schemas, data files
  scripts/          # Optional: executable code

唯一必需的文件是 SKILL.md。其余皆可选。

SKILL.md 格式

SKILL.md 有两部分：YAML frontmatter 写元数据，Markdown 正文写说明。

---
name: code-review
description: >
  Reviews pull requests following team standards. Checks for
  security issues, test coverage, naming conventions, and
  documentation. Use when asked to review code or a PR.
---

## Code Review Process

When reviewing code, follow these steps in order:

### 1. Security check
- Look for hardcoded secrets, SQL injection, XSS vulnerabilities
- Check that user input is validated and sanitized
- Verify authentication and authorization on new endpoints

### 2. Test coverage
- New public functions should have tests
- Edge cases should be covered (empty input, null values, errors)
- Check that tests actually assert meaningful behavior

### 3. Naming and structure
- Functions and variables should have descriptive names
- Files should be in the correct directory per project conventions
- No single function should exceed 50 lines

### 4. Documentation
- Public APIs should have docstrings
- Non-obvious logic should have inline comments
- README should be updated if behavior changes

### Output format
Present findings as a list grouped by category (Security, Tests,
Style, Docs). For each finding, include the file path, line number,
severity (high/medium/low), and a suggested fix.

Frontmatter 字段

description 字段至关重要。它是 Agent 决定是否激活该 skill 的主要依据。要写清 skill 做什么以及何时该用。

Progressive disclosure（渐进披露）—— 三层

Skills 被设计为增量加载。这是让它们切实可用的关键架构思想：

第 1 层：Metadata（始终加载）

启动时，Agent 只从每个已安装 skill 的 frontmatter 加载 name 和 description。每个 skill 大约 100 tokens。即使装了 50 个 skills，启动成本也大约只有 5,000 tokens。

Agent 用这些元数据判断：「给定当前任务，这个 skill 相关吗？」

第 2 层：Instructions（激活时加载）

当 Agent 判定某 skill 相关，就加载完整的 SKILL.md 正文。分步说明、决策框架和示例都在这里。建议控制在 5,000 tokens 以内。

第 3 层：Resources（按需加载）

references/、assets/、scripts/ 目录中的文件，仅在第 2 层说明引用它们时才加载。例如：

• references/security-checklist.md —— 扩展的安全审查标准
• assets/api-schema.json —— 用于校验的 API 规范
• assets/response-template.md —— 格式化输出模板
• scripts/run-linter.sh —— Agent 可执行的脚本

三层方式意味着你可以写得很细，却不必在启动时就付 context 成本。

Startup:      [L1: name + description]     ~100 tokens per skill
                        |
Task matches: [L2: full instructions]      ~2,000-5,000 tokens
                        |
As needed:    [L3: reference files]        Variable

Skills vs. tools vs. MCP

这三者工作在不同层级。分清差别有助于决定用哪个：

它们如何协同

典型 Agent 会三者并用：

1. Skills 告诉 Agent 如何处理任务、用哪些 tools
2. Tools（function calling）让 Agent 执行动作
3. MCP 提供连接远程 tool servers 的标准方式

例如：一个 "deploy-to-staging" skill 可能包含如下说明：

• 步骤 1：用 run_tests tool 跑测试套件
• 步骤 2：用 Kubernetes MCP server 检查 staging 环境状态
• 步骤 3：若测试通过且 staging 健康，用 deploy tool 部署
• 步骤 4：检查 health endpoints 验证部署

Skill 提供工作流逻辑；tools 与 MCP servers 提供执行能力。

如何写好 skills

聚焦一个领域

一个 skill 应把一件事做好。不要做一个包罗万象的 "development" skill，而是分别为 code review、部署、文档和测试建独立 skills。

为 LLM 写，不为人类写

Skills 由语言模型解释。要明确写清：

• 何时 使用该 skill（触发条件）
• 按什么 步骤执行（有序过程）
• 如何 处理边界情况（决策点）
• 好的 输出长什么样（示例或模板）

包含决策点

真正的专长包括知道何时偏离标准流程：

### Handling large PRs (>500 lines changed)

If the PR changes more than 500 lines:
- Focus review on the most critical files first (API endpoints, auth, data models)
- Skip cosmetic issues (formatting, naming) unless they affect readability
- Suggest splitting the PR if the changes cover multiple unrelated concerns

展示期望输出

给出 skill 输出应有的样子：

### Example output

**Security - High**
`src/api/auth.py:45` - Password is compared using `==` instead of
`hmac.compare_digest()`. This is vulnerable to timing attacks.
Suggested fix: Replace with `hmac.compare_digest(stored_hash, provided_hash)`

把 L2 说明控制在 5,000 tokens 以内

说明变长时，把详细参考材料挪到 references/ 下的 L3 文件，并在主说明中引用：

For the full security checklist, refer to `references/security-checklist.md`.

Google ADK 中的 Skills

Google 的 Agent Development Kit 通过 SkillToolset 类支持 skills。概念概览如下：

基于文件的 skills（推荐）

把 skill 目录放在 Agent 项目的 skills/ 文件夹中：

my-agent/
  agent.py
  skills/
    code-review/
      SKILL.md
      references/
        security-checklist.md
    deploy/
      SKILL.md
      scripts/
        pre-deploy-check.sh

Agent 从该目录发现并加载 skills。启动时只加载 L1 元数据；Agent 激活 skill 时再加载完整说明。

基于代码的 skills

若需动态创建或修改 skill，ADK 也支持用 Skill 模型类在代码中定义。适合 skill 内容需随运行时条件变化的场景。

详细实现见 ADK Skills documentation。

跨平台的 Skills

Agent Skills 规范已被多个平台采用：

规范由社区工作组维护，发布于 agentskills.io。格式就是目录里的 Markdown 文件，因此 skills 可在支持该规范的平台间移植。

实践示例

示例 1：Database migration skill

---
name: database-migration
description: >
  Creates and reviews database migrations. Use when the user asks to
  add, modify, or remove database tables or columns, or when reviewing
  migration files.
---

## Creating Migrations

1. Verify the current migration state: run `alembic heads` to check for conflicts
2. Create the migration: `alembic revision --autogenerate -m "description"`
3. Review the generated migration file for:
   - Correct up/down operations (both directions should work)
   - No data loss in down migration
   - Appropriate indexes for new columns
   - Nullable columns for existing tables (to avoid breaking existing rows)
4. Test the migration: `alembic upgrade head` then `alembic downgrade -1`

## Common Pitfalls

- Adding a NOT NULL column to an existing table without a default value
  will fail if the table has existing rows. Always add a default or make
  it nullable first, then backfill.
- Renaming columns requires a two-step migration: add new column, migrate
  data, drop old column. Alembic's autogenerate does not handle renames.
- Large table alterations should be done in batches on production. Add a
  note in the migration file if the table has >1M rows.

示例 2：Incident response skill

---
name: incident-response
description: >
  Guides incident response and post-mortem creation. Use when there is
  a production incident, outage, or when creating post-mortem documents.
---

## During an Incident

1. Assess severity using the service dashboard at `monitoring.internal/overview`
2. Check recent deployments: `gcloud run revisions list --service=api --limit=5`
3. Check error rates: `gcloud logging read "severity>=ERROR" --limit=50 --freshness=1h`
4. If a recent deployment is suspect, rollback:
   `gcloud run services update-traffic api --to-revisions=PREVIOUS_REVISION=100`

## After Resolution

Create a post-mortem document using the template in `assets/postmortem-template.md`
with these sections filled in:
- Timeline of events (with timestamps)
- Root cause analysis
- Impact (users affected, duration, data loss if any)
- What went well in the response
- Action items with owners and due dates

何时用 skills，何时用别的方式

关键要点

• Skills 把领域专长打包成可移植、可复用的 Markdown 文件
• 用 progressive disclosure（L1/L2/L3）尽量降低 context window 成本
• Skills 告诉 Agent 如何与何时行动；tools 让 Agent 真正行动
• SKILL.md 是唯一必需组件——frontmatter 写元数据，正文写说明
• 写 skill 要聚焦一个领域，步骤清晰，含决策点与输出示例
• L2 说明控制在 5,000 tokens 以内；细节放到 L3 references
• 多平台支持 skills：Claude Code、ADK、GitHub Copilot、OpenAI、Spring AI
• Skills、tools 与 MCP 在不同层级工作，彼此互补

延伸阅读

• Agent Skills Specification
• ADK Skills Documentation
• Anthropic Skills Repository
• GitHub Copilot Agent Skills
• Skills vs. MCP Tools - LlamaIndex

上一课：MCP Deep Dive | 下一课：Orchestrators ->