anthropics/skills：Anthropic 官方 Agent Skills 仓库解析

Anthropic 在 GitHub 上维护着一个名为 anthropics/skills 的仓库，目前已获得 127k stars、14.9k forks。这不是一个普通的工具库，而是一套让 Claude 具备可扩展能力的标准化规范。

什么是 Agent Skills？

官方给出的定义非常简洁：

Skills are folders of instructions, scripts, and resources that Claude loads dynamically.

Skills 是文件夹，而不是代码包。里面装的是指令、脚本和资源，Claude 在需要的时候动态加载。这个设计理念很重要：不是让 Claude 调用 API，而是让 Claude 读懂"该怎么做"的说明书。

这种设计背后有一个深刻的洞察：LLM 的能力瓶颈不在于不会推理，而在于不知道当前任务应该遵循什么规范、调用什么工具、按照什么流程走。Skills 就是填补这个空白的机制。

仓库结构

anthropics/skills 仓库分为三个核心部分：

anthropics/skills/
├── skills/          # 17 个示例 skill，直接可用
├── spec/            # SKILL.md 格式规范文档
└── template/        # 创建新 skill 的起始模板

skills/ 目录：17 个示例

官方提供了以下 17 个示例 skill，覆盖了从创意设计到工程开发的多个场景：

值得注意的是，许可证方面，大多数 skill 采用 Apache 2.0 协议开源，但部分文档类 skill 是 source-available（可见但有限制），使用前需要确认。

spec/ 目录：规范文档

spec 目录定义了 SKILL.md 的标准格式，是整个 skills 生态系统的"宪法"。

template/ 目录：起始模板

提供了一个最小化的 skill 模板，用于快速创建新 skill。

SKILL.md 格式详解

每个 skill 的核心是一个 SKILL.md 文件。格式如下：

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[具体指令内容]

## Examples

[示例用法]

## Guidelines

[使用规范和限制]

Frontmatter 字段

YAML frontmatter 中 name 和 description 是必填字段：

• name：skill 的唯一标识符，用于引用和安装
• description：这是最关键的字段——它是 agent 决定是否调用这个 skill 的唯一依据

这里有一个微妙但极其重要的设计：description 不是给人看的文档，而是给 Claude 看的调用判断依据。当 Claude 面对一个任务时，它会扫描所有已安装 skill 的 description，根据语义匹配决定是否加载某个 skill。

这意味着一个好的 description 需要：

1. 准确描述 skill 能做什么
2. 清晰说明在什么情况下应该使用
3. 也可以说明什么情况下不应该使用（negative examples）

正文部分

SKILL.md 的正文是给 Claude 的操作指令，通常包含：

• 核心能力说明：这个 skill 能做什么
• 工作流程：步骤化的操作指南
• 示例：具体的输入输出示例
• 约束条件：禁止事项和边界情况

三个精选 Skill 解析

1. webapp-testing：决策树驱动的测试自动化

webapp-testing skill 教 Claude 使用 Playwright 进行 Web 应用自动化测试。它的设计亮点是决策树结构：

收到测试任务
├── 有测试框架？
│   ├── 是 → 集成到现有框架
│   └── 否 → 初始化 Playwright
├── 有 spec 文件？
│   ├── 是 → 读懂再写
│   └── 否 → 从零创建
└── 运行后失败？
    ├── selector 问题 → 用 locator 策略
    └── 异步问题 → 加 waitFor

这种决策树设计让 Claude 面对任意测试场景时都有清晰的行动路径，而不是"随机应变"。

2. mcp-builder：MCP Server 开发完整指南

mcp-builder skill 是构建 Model Context Protocol server 的详细指南。它涵盖：

• MCP 协议基础（Tools、Resources、Prompts 三种能力）
• TypeScript SDK 使用方式
• 标准 server 结构模板
• 常见工具类型的实现模式（文件操作、API 调用、数据库查询）
• 调试和测试方法

这个 skill 本身就是一个"教 Claude 教别人"的设计——它让 Claude 具备了指导开发者构建 MCP 服务的能力。

3. skill-creator：用 skill 创建 skill

skill-creator 是 anthropics/skills 中最元级别的 skill——它教 Claude 如何创建新的 skill。

它包含：

• SKILL.md 格式规范的详细说明
• 好的 description 怎么写（以及常见错误）
• 指令编写的最佳实践
• skill 的测试方法

这种递归设计体现了 Anthropic 的一个思路：让 skill 系统能够自我增殖和完善。

三种使用方式

方式一：Claude Code Plugin（推荐）

如果你在使用 Claude Code（即 claude.ai 的代码模式），可以通过插件市场安装：

# 添加 anthropics/skills 作为插件源
/plugin marketplace add anthropics/skills

# 安装示例 skill 集合
/plugin install example-skills@anthropic-agent-skills

安装后，Claude Code 会自动感知这些 skill，并在相关任务时动态加载。

方式二：Claude.ai 界面

Claude.ai 已经对付费用户开放了自定义 skill 功能。你可以：

1. 在 Claude.ai 的设置中找到"Skills"选项
2. 上传你的 SKILL.md 文件
3. Claude 在对话中会自动检测并使用已安装的 skill

方式三：API 集成

通过 Anthropic 的 Skills API，可以在自己的应用中集成 skill：

# Skills API Quickstart 示例
import anthropic

client = anthropic.Anthropic()

# 在 system prompt 中注入 skill 内容
with open('skills/webapp-testing/SKILL.md', 'r') as f:
    skill_content = f.read()

response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=4096,
    system=f"You have access to the following skill:\n\n{skill_content}",
    messages=[{"role": "user", "content": "请帮我写一个登录页面的 E2E 测试"}]
)

设计洞察

1. Description 是 agent 的感知器官

整个 skill 系统中最核心的设计决策是：description 是 agent 选择 skill 的唯一依据。

这不是偶然的设计，而是深思熟虑的架构选择：

• 它迫使 skill 作者写出精准的语义描述
• 它让 Claude 的 skill 选择过程透明可预测
• 它与 RAG 系统的"检索"逻辑一脉相承

2. 黑盒调用脚本

skills 中包含的脚本（Python、Shell 等）是黑盒调用的。Claude 不会去读懂脚本的实现细节，它只需要知道"在什么情况下调用这个脚本，传什么参数，期望什么输出"。

这是一个重要的设计原则：把执行逻辑下沉到脚本，把决策逻辑留给 LLM。

3. 明确的禁止事项

优秀的 skill 不只告诉 Claude 能做什么，还明确说明不能做什么。比如 webapp-testing 中会说明：

• 不要修改被测试的应用代码
• 不要在没有确认的情况下删除测试文件
• 不要假设测试环境的状态

这种负向约束对 LLM 尤其重要——因为 LLM 天然倾向于"尽力完成任务"，有时候会越权操作。

如何写一个好的 Skill

基于 anthropics/skills 的设计模式，总结几条写好 skill 的原则：

1. Description 第一 description 写好了，skill 成功了一半。要能在 2-3 句话内说清楚：这个 skill 做什么、什么时候用、不适合用在哪里。

2. 流程要有分支 真实任务不是线性的。好的 skill 用决策树覆盖各种情况，而不是假设只有"happy path"。

3. 具体胜于抽象 “用合适的方式处理文件"不如"用 Python pathlib 读取文件，encoding 用 utf-8”。LLM 面对具体指令时表现更稳定。

4. 约束要明确 告诉 Claude 什么不能做，和告诉它什么能做同样重要。

5. 用示例说话 一个好的 input/output 示例，胜过三段解释文字。

anthropics/skills 仓库的意义不只在于提供了 17 个现成工具，更在于它定义了一套可复用、可分发的 agent 能力规范。随着 Skills 生态的发展，我们可能会看到一个类似 npm 的 skill 市场——任何人都可以发布自己的 skill，任何 Claude 都可以安装使用。

这是 AI 能力模块化的开始。