Agent Skills 中文手册

01什么是 Agent Skills？ 必用

Agent Skills 是一种轻量级、开放的格式，用于扩展 AI Agent 能力，提供专业知识和工作流程。核心是一个包含 SKILL.md 文件的文件夹，该文件包含元数据和指令，告诉 agent 如何执行特定任务。

02为什么需要 Agent Skills？ 必用

统一格式让同一份技能可以在不同 agent 产品间复用，一次构建、到处运行。渐进式披露确保 agent 只加载需要的上下文，节省 token。

• 跨平台复用：写一份 PDF 处理技能，Claude Code、Cursor、Gemini CLI 都能用
• 上下文效率：渐进式披露机制让 agent 只加载当前任务相关的技能，不浪费 token
• 标准化：MIT 许可的开放标准，由 Anthropic 发起，社区共建

03工作原理：渐进式披露 必用

三个阶段：

1. Discovery（发现）：Agent 启动时仅加载每个可用技能的名称和描述（约 100 tokens），足够让 agent 知道何时可能相关
2. Activation（激活）：当任务匹配技能描述时，agent 将完整的 SKILL.md 指令加载到上下文中（建议 <5000 tokens）
3. Execution（执行）：agent 遵循指令，按需执行捆绑代码或加载引用的文件

04目录结构规范 必用

一个 skill 就是一个目录，至少包含 SKILL.md。可选目录：scripts/（可执行代码）、references/（文档资料）、assets/（模板资源）。

my-skill/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：文档资料
└── assets/           # 可选：模板和资源

05SKILL.md 格式规范 必用

SKILL.md 必须包含 YAML frontmatter（至少 name 和 description）加上 Markdown 正文内容。正文可包含任意格式的步骤说明、示例、边缘情况处理等。

---
name: my-skill
description: 描述这个技能做什么以及在何时使用。
license: Apache-2.0
compatibility: Requires Python 3.10+
metadata:
  author: my-org
  version: "1.0"
---

# My Skill

## 步骤说明
1. 第一步...
2. 第二步...

06Frontmatter 字段详解 高频

07正文内容编写指南 高频

frontmatter 之后的 Markdown 正文包含技能指令。建议包含：

• 分步说明
• 输入输出示例
• 常见边缘情况处理

# 技能名称

## 功能概述
[简短描述]

## 使用步骤
1. 第一步...
2. 第二步...

## 示例
[输入/输出示例]

## 注意事项
[边缘情况和常见问题]

08可选目录约定 中频

09文件引用规范 低频

在 SKILL.md 中引用其他文件时，使用相对路径。保持一层深度，避免深层嵌套引用链。

参见[参考指南](references/REFERENCE.md)

运行提取脚本：
scripts/extract.py

10与现有技能生态对比 低频

Agent Skills 是跨客户端的开放标准，与 Claude Code 的 .claude/skills、Cursor 的 settings 各有定位，但格式正在趋同。

11技能验证方法 低频

使用 skills-ref 工具验证 SKILL.md 是否符合规范：检查 frontmatter 合法性、命名规范、字段约束等。

# 安装 skills-ref
npm install -g skills-ref

# 验证技能
skills-ref validate ./my-skill

12创建技能完整示例 高频

从 0 到 1 创建一个简单的 Markdown 代码格式化技能：

# 1. 创建目录
mkdir my-skills/markdown-format && cd my-skills/markdown-format

# 2. 创建 SKILL.md
cat > SKILL.md << 'EOF'
---
name: markdown-format
description: 格式化 Markdown 文件，应用标题加粗、列表缩进、代码块语言标记。Use when working with Markdown documents or formatting notes.
---

# Markdown Format Skill

## 步骤
1. 读取目标文件
2. 应用格式化规则
3. 保存结果

## 格式化规则
- 标题级别正确
- 列表缩进一致
- 代码块标注语言
EOF

# 3. 验证
skills-ref validate ./markdown-format

13技能编写最佳实践 中频

• 保持 SKILL.md 简洁（<500 行），详细参考放 references/
• description 要具体有用（含关键词），避免笼统描述
• 脚本要自包含、错误提示友好
• 文件引用保持扁平结构

✅ 好的 description：
"Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents..."

❌ 差的 description：
"Helps with PDFs."

14已支持的 Agent 客户端 中频

Agent Skills 是开放标准，已支持 40+ 个 agent 产品，涵盖 IDE、CLI、平台级 agent。一次编写，到处运行。

15参考资源汇总 低频