01 Agent Skills 规范与三级渐进式加载

01 Agent Skills 规范与三级渐进式加载

学习目标

• 理解 Anthropic Skills 仓库中 SKILL.md 的实际格式约定
• 掌握三级渐进式加载在 18 个技能中的具体落地方式
• 分析技能描述字段的触发策略与优化技巧

前置知识

本章涉及 Skill 渐进式知识管理的通用原理，建议先阅读：

• Skill 渐进式知识管理

下文假设你已理解上述概念，直接聚焦 Anthropic Skills 仓库的具体实现。

---

项目实践

SKILL.md 在 Anthropic 仓库中的统一格式

Anthropic Skills 仓库中的所有技能遵循统一格式：

---
name: skill-identifier          # 必填：小写，连词分隔
description: "..."              # 必填：触发描述 + 何时使用
license: "..."                  # 可选：完整条款 / 专有
---

# 技能标题

[指令内容...]

关键观察：在实际的 18 个技能中，description 字段远不止一行简短描述。它通常包含：

1. 核心功能定义：这个技能做什么
2. 触发条件列表：何时应该使用（包括具体关键词和场景）
3. 排除条件：何时不应使用

例如 docx 技能的 description 段落：

“Use this skill whenever the user wants to create, read, edit, or manipulate Word documents… Triggers include: any mention of ‘Word doc’, ‘.docx’, requests to produce professional documents… Also use when extracting or reorganizing content… Do NOT use for PDFs, spreadsheets, Google Docs…”

这种”pushy”风格是刻意的。Anthropic 在 skill-creator 技能中明确说明：Claude 倾向于”undertrigger”（不使用技能即使应该用），因此描述需要包含更多触发关键词来对抗这种倾向。

三级渐进式加载的具体落地

Anthropic Skills 仓库中的 18 个技能展示了三级渐进式加载的多种变体：

三种资源组织模式：

模式	代表技能	特点
自包含型	frontend-design, brand-guidelines	SKILL.md 包含全部指令，无需额外文件
引用参考型	mcp-builder, claude-api	SKILL.md 作为路由器，指向 references/ 中的详细文档
脚本执行型	webapp-testing, web-artifacts-builder	SKILL.md 指导先执行黑盒脚本，再进行定制操作

引用参考型：SKILL.md 作为路由器

mcp-builder 技能的 SKILL.md 只有约 237 行，但引用了 4 个参考文件：

• reference/mcp_best_practices.md - MCP 最佳实践
• reference/node_mcp_server.md - TypeScript 实现指南
• reference/python_mcp_server.md - Python 实现指南
• reference/evaluation.md - 评估创建指南

SKILL.md 中明确标注了何时读取哪个文件：

### Core MCP Documentation (Load First)
- MCP Protocol: Start with sitemap at ...
- MCP Best Practices: View Best Practices

### SDK Documentation (Load During Phase 1/2)
- Python SDK: Fetch from ...
- TypeScript SDK: Fetch from ...

这种设计的核心决策是：SKILL.md 只保留工作流骨架，具体技术细节在 references/ 中按需加载。

脚本执行型：黑盒调用模式

webapp-testing 技能采用了独特的”黑盒脚本”策略：

**Always run scripts with `--help` first** to see usage.
DO NOT read the source until you try running the script first and found that a customized solution is absolutely necessary.
These scripts can be very large and thus pollute your context window.

这个策略解决了一个实际问题：辅助脚本（如 with_server.py）可能包含大量代码和错误处理逻辑。如果让 Claude 先读取源码，会污染上下文窗口。正确的做法是先作为黑盒执行，只有当黑盒执行不满足需求时才读取源码定制。

---

问题与规避

触发不足（Undertriggering）

问题：Claude 倾向于不使用技能，即使技能明显适用。

Anthropic 的解决方案：在 description 中明确列出触发关键词。例如 frontend-design 的描述不仅说”创建前端界面”，还具体列出：

“Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don’t explicitly ask for a ‘dashboard’.”

SKILL.md 膨胀

问题：随着功能增加，SKILL.md 可能超过 500 行，导致上下文浪费。

规避策略：Anthropic 仓库中的大型技能（如 docx ~440 行，skill-creator ~485 行）通过以下方式控制大小：

• 将语言特定的代码示例分离到 references/
• 将子代理指令放在 agents/ 子目录
• 在 SKILL.md 中只放”何时读取哪个文件”的路由逻辑

简单查询不触发

问题：简单的一步查询（如”读这个 PDF”）即使描述匹配也不会触发技能。

规避策略：这是 Claude 的有意设计——它认为自己能直接处理简单任务。测试技能触发时，必须使用足够复杂的查询。

---

设计取舍

为什么用 description 而非显式分类？

Anthropic 选择让 Claude 根据 description 自然语言决定是否使用技能，而非显式的技能分类标签。

优势：更灵活，能处理模糊边界的请求；无需维护分类体系。 代价：需要反复优化 description 才能准确触发；可能出现误触发或漏触发。 替代方案：显式分类 + 关键词匹配（更快但更僵硬）。

为什么 SKILL.md 用 Markdown 而非 JSON/YAML 结构？

优势：对人类编写者友好，易于编辑和审查；Markdown 的标题和列表天然适合组织指令。 代价：解析依赖 LLM 而非确定性解析器；格式不一致。 实际：Anthropic Skills 仓库中各技能的格式差异明显——有些用大量标题，有些用纯段落。

---

参考来源

• Agent Skills 规范：https://agentskills.io/specification
• Anthropic Skills 仓库：https://github.com/anthropics/skills
• Claude 文档中心：https://docs.claude.com/en/docs/claude-code/skills