Agent Skills 编写规范

本文综合 Vercel AI SDK、Anthropic Claude、OpenAI 三大生态系统的最佳实践，系统阐述 AI Agent Skills 的定义、结构设计、编写规范与质量保障体系。

1. 什么是 Agent Skill

Skill 是 Agent 可以调用的可重用功能模块，是将大语言模型的生成能力向自主执行过程延伸的核心构件。

它并非简单的文本指令集，而是一个包含元数据、自然语言指令、可执行脚本及参考资源的解耦复合包。

通过将特定领域的专业知识（如代码优化规则、设计规范）封装成独立模块按需加载，有效解决大语言模型处理长流程任务时的上下文膨胀和幻觉问题。

2. 三层渐进式披露架构

高质量的 Skill 采用**渐进式披露（Progressive Disclosure）**的三层架构设计，以最大化上下文窗口的利用效率：

1
2
3
4
5

第一层：元数据（~100 tokens，启动时始终加载）
    ↓
第二层：SKILL.md 主体（≤5000 tokens / 500行，Skill 被激活时加载）
    ↓
第三层：资源层（scripts/ references/ assets/，按需加载）

2.1 第一层：元数据（Metadata）

• 加载时机：启动/初始化阶段始终加载（约 100 tokens）
• 作用：作为大模型的"决策边界"，用于语义匹配和路由

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

---
name: analyzing-spreadsheets          # 1-64字符，小写动名词形式
description: >
  用于分析和处理 Excel/CSV 电子表格数据的技能。
  当需要对表格数据进行清洗、排序、统计汇总时使用。
  不要调用此技能当用户需要修改系统配置，或当数据量超过1GB时。
license: MIT                          # 可选
compatibility: ">=1.0.0"              # 可选
metadata:                             # 可选
  author: "Data Team"
  version: "1.1.0"
allowed-tools:                        # 可选 - 权限最小化
  - read_file
  - write_file
  - python_interpreter
---

2.2 第二层：SKILL.md 主体指令

• 加载时机：Skill 被激活时加载
• 核心要求：强烈建议保持在 500 行以内（或 5000 tokens 以下）
• 定位：整个 Skill 的导航中心

2.3 第三层：资源层（Resources）

• 加载时机：根据指令按需加载

引用规则：必须使用相对路径，保持一级深度，避免深层嵌套的参考链。

3. 目录结构模板

1
2
3
4
5
6
7
8
9
10
11
12

skill-root/
├── SKILL.md                    # 主体指令（导航中心）
├── scripts/
│   ├── validate_json.js        # 校验 LLM 输出
│   ├── calculate_tax.py        # 复杂计算（LLM 容易算错）
│   └── run_tests.sh            # TDD 质量门禁脚本
├── references/
│   ├── api_endpoints.md        # API 全量端点列表
│   ├── ui_guidelines.md        # 色彩系统和无障碍规范
│   └── error_codes.md          # 故障排除和错误代码表
└── assets/
    └── config_template.json    # 配置模板

4. SKILL.md 完整模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

---
name: analyzing-spreadsheets
description: >
  用于分析和处理 Excel/CSV 电子表格数据的技能。
  当需要对表格数据进行清洗、排序、统计汇总时使用。
  不要调用此技能当用户需要修改系统配置，或当数据量超过1GB时。
metadata:
  author: "Data Team"
  version: "1.1.0"
allowed-tools: ["read_file", "write_file", "python_interpreter"]
---

# 分析电子表格 (Analyzing Spreadsheets)

## 1. 核心目标与意图
本技能旨在帮助代理以确定性的方式清洗和分析结构化表格数据。

## 2. 适用场景（何时应用）
- 清洗包含空值或格式错误的 CSV 文件
- 按特定列进行数据分组和聚合运算

## 3. 工作流程与执行步骤
1. **读取数据**：首先使用 `read_file` 工具读取目标表格
2. **数据清洗**：调用 `scripts/clean_data.py` 处理缺失值
3. **分析输出**：根据用户需求生成结构化（JSON）分析报告

## 4. 关键规则与优先级
- **[CRITICAL]** 绝对不要删除原始文件，始终将结果输出到新文件
- **[HIGH]** 要求以 JSON 格式输出，以便下游系统解析

## 5. 代码与使用示例
python scripts/clean_data.py --input raw.csv --output cleaned.csv

## 6. 详细参考资料导航
- 数据结构规范 → references/data_structures.md
- 常见错误与 FAQ → references/error_codes.md

5. 编写规范

5.1 name 字段命名规范

5.2 description 编写规范

description 是大模型的决策边界，决定了 Skill 是否被正确路由和激活。最多 1024 字符。

必须做到：

• 使用第三人称、客观专业的语气（"这个 Skill" / "该工具"）
• 包含具体的关键术语
• 清晰回答"什么"、"何时使用"以及"何时不使用"
• 包含 3-5 个负面示例（"不要调用此 Skill 当…"）

反面教材：

❌ 我是一个可以帮您优化代码的工具。如果你觉得代码运行慢，就可以来找我，我会告诉你怎么修改代码更好。

错误原因：使用了第一人称"我"，描述极其模糊，没有关键术语，没有触发边界，缺乏负面示例。

正面教材：

✅ 用于对 React 和 Next.js 应用进行综合性能优化的技能。当需要解决异步瀑布流、减小 JavaScript 包大小或进行 RSC 服务端渲染优化时使用该技能。不要在处理后端数据库迁移、配置 Nginx 服务器或进行纯 CSS 样式修改时调用此技能。

添加负面示例和边界情况能将误触发率降低 20% 以上。

5.3 触发条件编写

1
2
3
4
5
6
7
8
9

**何时使用本技能：**
- 需要分析 .csv 或 .xlsx 格式的财务数据时
- 用户要求生成基于表格的趋势预测报告时
- 提取多张表格的交集数据时

**何时不使用（不要调用此技能当）：**
- 输入数据为非结构化文本（如 PDF 论文）时
- 需要执行实时网络数据抓取时（应使用 web-scraping 技能）
- 涉及直接修改系统底层数据库记录的操作时

5.4 简洁性原则

• 上下文窗口是极其宝贵的公共资源
• 默认假设 Agent 已经很聪明，不要重复解释其已知概念
• 删除冗余修饰词，只添加 Skill 特有的信息
• 每个 token 都要合理

5.5 信息组织技巧

• 使用表格组织复杂信息
• 使用前缀系统（如 async-、bundle-）标记相关项目
• 提供清晰的优先级标记（CRITICAL、HIGH、LOW）引导大模型关注点
• 包含完整的代码片段和输入输出示例以减少幻觉

6. 关键设计模式

6.1 声明式指令与命令式工具的解耦

核心原则：意图归代理，执行归工具

• 用自然语言精确定义任务边界（声明式）
• 复杂逻辑运算、正则匹配等交由专属脚本执行（命令式）
• 消除 LLM 的计算弱点

6.2 自由度与任务脆弱性匹配

根据任务的风险程度调整指令的具体程度：

6.3 动态能力获取

不强制要求所有规则硬编码。通过动态抓取工具（如 WebFetch）在执行时获取最新规范，使 Skill 成为一个"规则网关"：

1
2
3
4
5
6
7

## 步骤 1：获取最新设计规范
在审查任何 UI 组件之前，必须首先调用 `fetch_url` 工具：
fetch_url https://design.company.com/api/latest-guidelines.json

## 步骤 2：执行审查
比对本地代码与获取到的规范，按以下格式输出：
{文件路径}:{行号} - {违规说明} (参考规则：{规范ID})

6.4 强制性工作流（质量门禁）

不再依赖 LLM 的单次输出信任，设置不可逾越的质量门禁：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

#!/bin/bash
# scripts/tdd_gate.sh - 强制 TDD 质量门禁
TEST_FILE=$1
CODE_FILE=$2

if [ ! -f "$TEST_FILE" ]; then
  echo "[ERROR] 质量门禁拦截：必须先编写测试文件 $TEST_FILE！"
  exit 1
fi

npm run test -- $TEST_FILE
if [ $? -ne 0 ]; then
  echo "[ERROR] 测试未通过。请重新审视 $CODE_FILE 的逻辑。"
  exit 1
fi

echo "[SUCCESS] 测试通过，允许提交更改。"

7. 三大生态系统范式对比

共识点（行业高度一致）：

• 渐进式披露的三层加载架构
• 简洁性原则（假设 Agent 已经聪明）
• 系统化验证和质量门禁

8. 四步系统化验证流程

每个 Skill 发布前必须通过全部四步验证：

1

1. 发现验证 → 2. 逻辑验证 → 3. 边界测试 → 4. 架构优化

第一步：发现验证

• 创建 3 个应该触发的提示词
• 创建 3 个不应该触发的提示词
• 测试 LLM 对 description 的路由解释是否 100% 准确

第二步：逻辑验证

• 模拟 Agent 执行全流程
• 标记任何执行阻碍（Execution Blockers）
• 确保步骤具备确定性，不强制模型产生幻觉

第三步：边界情况测试

• 输入不支持的配置
• 测试极端输入数据
• 模拟服务断网的失败状态
• 验证 Agent 能否优雅退出或提示错误

第四步：架构优化

• 审查 SKILL.md 是否在 500 行以内
• 密集规则是否已移至 references/
• 大型配置是否已移至 assets/
• Token 使用是否高效

9. 安全与可靠性策略

9.1 安全与权限治理

• 权限最小化：使用短期有效且范围受限的凭证
• 输出清理：严格过滤输出，防止间接提示词注入
• 审计追踪：记录每次工具调用的完整 Payload 和推理轨迹
• 人工干预（HITL）：涉及资金/删除/生产部署的操作必须二次确认

9.2 容错与异常处理

9.3 状态可见与透明度

• 实时决策日志：展示当前调用的 API 和推理阶段
• 进度指示器：长链条任务提供分步任务清单
• 差异化预览：修改前生成 Diff 视图或 Git worktrees 预览
• 万能撤销：支持一键回滚，失败尝试不污染主代码库

10. Token 预算管理策略

1. 渐进式披露：初始化仅加载 ~100 tokens 元数据 → 激活时加载 ≤5000 tokens 主体 → 按需读取资源层
2. 消除冗余：删除不必要的修饰词和重复概念
3. 上下文压缩（Compaction）：长运行任务定期总结并清理早期推理轨迹，防止 Token 耗尽崩溃

11. 版本与生命周期管理

版本管理

• 在元数据中明确包含 version 字段
• 维护变更日志（Changelog）记录迭代历史
• 使用 Git 分支策略，破坏性更改发布新版本并提供向后兼容性指南

生命周期

1

发现与分发 → 部署与监控 → 数据驱动优化 → (循环)

• 发现与分发：通过标准化规范打包（如 agentskills.io），一键安装与跨平台分发
• 生产监控：观测工具调用准确率、Token 消耗分布、幻觉触发点
• 持续改进：收集运行时推理痕迹（Traces）进行标注，不断优化 description 的正负面示例

12. 速查清单

Skill 发布前检查清单：

• [ ] name 使用小写动名词形式，1-64 字符
• [ ] description 包含正向和负向触发条件
• [ ] SKILL.md 不超过 500 行 / 5000 tokens
• [ ] 复杂计算已交由 scripts/ 中的脚本处理
• [ ] 密集规则已移至 references/ 目录
• [ ] 使用相对路径引用资源，保持一级深度
• [ ] 通过发现验证（3 正 + 3 负提示词测试）
• [ ] 通过逻辑验证（无执行阻碍）
• [ ] 通过边界情况测试
• [ ] Token 使用高效，无冗余信息
• [ ] 高风险操作已设置人工干预门禁
• [ ] 版本号已在元数据中标注

• ← Previous Post
• Next Post →