#Agent Skills — 开放式 Agent 技能标准

Agent Skills 是一种轻量级、开放格式，用于为 AI Agent 定义可复用的能力模块。最初由 Anthropic 开发，现已作为开放标准发布，被众多 AI 产品和客户端采用。

#概念：为什么需要 Agent Skills

AI Agent 的能力不是天生的——它是通过指令、脚本、参考资料逐步构建起来的。传统做法每次都要用自然语言重新描述这些指令，既低效又不一致。

Agent Skills 解决的就是这个问题：把专业知识、工作流、工具用法打包成一个标准化的模块，一次编写，处处可用。

打个比方：

SKILL.md 就是这份"菜谱"——包含这个技能叫什么、什么时候用、以及具体怎么做。

#核心设计理念

#领域专业知识

将专业知识——从法律审核流程到数据分析管线再到演示文稿格式化——打包为可复用的指令和资源：

• 📋 法律审核技能：包含审核清单、条款模板、风险分类标准
• 📊 数据分析技能：包含数据处理管线、可视化规范、报告模板
• 🎨 PPT 生成技能：包含品牌色板、布局模板、字体规范

#可重复工作流

将多步骤任务转化为一致、可审计的操作流程。同一个技能每次激活都按照相同的流程执行，保证输出质量的一致性。

#跨产品复用

一次构建技能，可在任何兼容 Agent Skills 的 Agent 中跨产品使用。Claude Code、Codex、Cursor、Gemini CLI 等工具都支持或正在适配该标准。

#目录结构

一个 Agent Skill 就是一个目录，最少只需要一个 SKILL.md 文件：

my-skill/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码（Python/Bash/JS）
├── references/       # 可选：文档资料（按需加载）
├── assets/           # 可选：模板、图片、数据文件
└── ...               # 任何其他文件或目录

#各目录的职责

#SKILL.md 格式规范

SKILL.md 文件包含 YAML 前置元数据（frontmatter） + Markdown 正文两部分。

#完整字段一览

#name 字段规则

name 的命名约束：

• ✅ 允许：pdf-processing、data-analysis、code-review
• ❌ 不允许：PDF-Processing（大写）、-pdf（以连字符开头）、pdf--processing（连续连字符）

#最小示例

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs or when the user mentions PDFs, forms, or document extraction.
---

#完整示例

---
name: pdf-processing
description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
license: Apache-2.0
compatibility: Requires Python 3.14+ and uv
metadata:
  author: example-org
  version: '1.0'
allowed-tools: Bash(git:*) Bash(python:*) Read
---
# PDF Processing

## Step-by-step instructions

...(技能的具体指令写在这里)...

#description 怎么写

description: Extracts text and tables from PDF files, fills PDF forms,
and merges multiple PDFs. Use when working with PDF documents or when
the user mentions PDFs, forms, or document extraction.

description: Helps with PDFs.

#渐进式披露机制

Agent 通过三个阶段渐进加载技能，避免一次性占满上下文：

┌──────────────────────────────────────────────────────────┐
│  阶段 ① 发现（Discovery）                                │
│  启动时加载所有技能 name + description                    │
│  每个技能仅 ~100 tokens，可携带数十个技能而不占空间        │
├──────────────────────────────────────────────────────────┤
│  阶段 ② 激活（Activation）                               │
│  任务匹配 description 时，加载完整 SKILL.md                │
│  建议控制在 500 行 / 5000 tokens 以内                     │
├──────────────────────────────────────────────────────────┤
│  阶段 ③ 执行（Execution）                                │
│  Agent 按指令执行，必要时运行 scripts/、读取 references/   │
│  资源文件按需加载，不进入上下文                            │
└──────────────────────────────────────────────────────────┘

这个设计的巧妙之处在于：你可以安装几十个技能，但 Agent 的上下文窗口几乎不增加。只在真正需要时才把"菜谱"翻开。

#创建你的第一个 Skill

#Step 1：创建目录和 SKILL.md

mkdir -p my-first-skill

# my-first-skill/SKILL.md

---

name: my-first-skill
description: Formats Markdown documents according to project style guide.
Use when the user asks to format, prettify, or clean up Markdown files.

---

# Markdown Formatter

## Instructions

1. Read the target Markdown file
2. Apply these formatting rules:
   - Single blank line between sections
   - No trailing whitespace
   - Code blocks use language tags
   - Headers use sentence case
3. Write the formatted result back

## Edge cases

- If the file already matches the style, say so and skip
- If the file doesn't exist, report the error

#Step 2：添加参考资料（可选）

mkdir -p my-first-skill/references

# my-first-skill/references/style-guide.md

## Project Style Guide

- Indentation: 2 spaces
- Quotes: single
- Semicolons: no
- Line width: 100 characters

在 SKILL.md 中引用它：

Refer to [the complete style guide](references/style-guide.md) for detailed formatting rules.

#Step 3：添加可执行脚本（可选）

mkdir -p my-first-skill/scripts

# my-first-skill/scripts/check_trailing_ws.py
"""Check for trailing whitespace in Markdown files."""
import sys

def check(filepath: str) -> list[int]:
    lines_with_trailing = []
    with open(filepath, encoding='utf-8') as f:
        for i, line in enumerate(f, 1):
            if line.rstrip('\n').endswith(' '):
                lines_with_trailing.append(i)
    return lines_with_trailing

if __name__ == '__main__':
    for path in sys.argv[1:]:
        bad = check(path)
        if bad:
            print(f'{path}: trailing whitespace on lines {bad}')

在 SKILL.md 中引用：

Before writing, run the trailing whitespace check:
scripts/check_trailing_ws.py <file>

#验证技能

使用 skills-ref 参考库验证你的技能是否符合规范：

# 安装
pip install skills-ref

# 验证
skills-ref validate ./my-first-skill

这会检查：

• ✅ frontmatter 格式是否正确
• ✅ name 是否符合命名规则
• ✅ name 是否与目录名一致
• ✅ description 是否非空且不超长
• ✅ 可选字段格式是否正确

#在 Claude Code 中使用

#安装社区技能

Claude Code 原生支持 Agent Skills。最常用的技能来源是 Anthropic 官方技能仓库：

# 克隆社区技能仓库到 ~/.claude/skills/
git clone https://github.com/anthropics/skills.git ~/.claude/skills/

也支持安装单独的技能：

# 放在 ~/.claude/skills/ 下的任意子目录
mkdir -p ~/.claude/skills/pdf-processing
cp /path/to/pdf-processing/SKILL.md ~/.claude/skills/pdf-processing/

Claude Code 启动时会扫描 ~/.claude/skills/ 目录，自动加载所有技能到发现层（阶段①）。

#技能加载验证

启动 Claude Code 后，可以看到技能加载日志：

[Skills] Loaded 12 skills from ~/.claude/skills/
  - pdf-processing (PDF extraction and manipulation)
  - data-analysis (Statistical analysis and chart generation)
  - code-review (Code review with project conventions)
  ...

#注意：Skills 和 Agents 的区别

简单理解：Skills 教 Agent 怎么做，Agents 定义谁来做什么。

#最佳实践

#1. 保持 SKILL.md 精简

• 控制在 500 行以内
• 详细的参考资料放到 references/ 目录
• Agent 按需加载引用文件，不占用基础上下文

#2. 写好 description

• description 是技能唯一在发现阶段可见的内容
• Agent 靠它判断是否激活技能，写模糊了技能永远不会被触发
• 包含具体触发场景和关键词（如 "Use when the user mentions PDFs, forms, or document extraction"）

#3. 文件引用保持一层深

✅ SKILL.md → references/style-guide.md
✅ SKILL.md → scripts/extract.py
❌ SKILL.md → references/guide.md → references/deep-dive.md → ...（太深，Agent 可能跟丢）

#4. 为脚本做好错误处理

Agent 运行脚本时没有交互式终端——脚本失败了，Agent 只能看输出：

# ✅ 好的：有明确的错误信息和退出码
if not filepath.exists():
    print(f"Error: {filepath} not found", file=sys.stderr)
    sys.exit(1)

# ❌ 差的：静默失败或输出模糊
if not filepath.exists():
    pass  # 啥也不说，Agent 一头雾水

#5. 利用渐进式披露设计大型技能

如果一个技能涉及很多细分场景，不要把所有内容塞进 SKILL.md。按场景拆分到 references/：

financial-analysis/
├── SKILL.md                # 发现 + 入口 + 路由逻辑
├── references/
│   ├── stock-valuation.md  # 股价估值方法
│   ├── risk-analysis.md    # 风险评估框架
│   └── portfolio.md        # 投资组合优化
└── scripts/
    ├── fetch_data.py       # 获取市场数据
    └── monte_carlo.py      # 蒙特卡洛模拟

SKILL.md 中只写路由逻辑：

## Task routing

- For stock valuation: read references/stock-valuation.md
- For risk analysis: read references/risk-analysis.md
- For portfolio optimization: read references/portfolio.md

这样每次只加载需要的 1/3 内容，大幅节省上下文。

#社区与生态

#官方技能仓库

#精选社区技能

#社区讨论

• Discord — 官方社区讨论区
• GitHub Issues — 规范讨论与建议

#常见问题

#Agent Skills 和 MCP 服务器有什么区别？

两者互补：Skill 里的脚本可以调用 MCP 工具，MCP 工具也可以由 Skill 激活后驱动。

#Agent Skills 和 AGENTS.md 路由协议怎么配合？

• AGENTS.md 定义哪个 Skill 框架优先（Superpowers vs Gstack 等）
• 每个 Skill 框架内部的技能按 Agent Skills 标准 组织
• 两者不冲突：AGENTS.md 是调度层，Agent Skills 是能力层

详见 AGENTS 全局路由协议。

#必须发布到 GitHub 才能用吗？

不用。Skills 是纯本地的目录结构。你可以：

• 📁 自己的私有 Skill 直接放在 ~/.claude/skills/ 下就能用
• 🔗 克隆社区仓库到本地使用
• 🌐 发布到 GitHub 方便分享和协作（推荐加上 agent-skills topic）

#所有 Agent 产品都支持 Agent Skills 吗？

Agent Skills 是开放标准，主流 Agent 产品都在适配中：

• ✅ Claude Code — 原生支持
• ✅ Codex（OpenAI）— 通过 codex-plugin-cc 兼容
• 🔄 Cursor、Gemini CLI 等 — 适配中

完整客户端列表见 agentskills.io/clients。

#相关资源

• agentskills.io — 官方网站：规范、教程、客户端列表
• agentskills.io/specification — 完整格式规范
• github.com/agentskills/agentskills — 仓库（规范 + 验证工具）
• github.com/anthropics/skills — Anthropic 官方技能集
• Superpowers — Claude Code 结构化工作流框架（基于 Agent Skills）
• AGENTS 全局路由协议 — 多技能框架的调度与优先级

#下一步

• 多智能体工作流 — 了解 Claude Code 的多 Agent 架构
• MCP 服务器 — 给 Agent 添加工具能力
• AGENTS 全局路由协议 — 多框架共存时的路由策略
• Comet — 提交前的自动化验证 Skill