Skill Standardization

何时使用此技能

• 从头创建新的 SKILL.md 文件
• 审计现有技能是否符合 Agent Skills 规范
• 将旧版技能格式（非标准标题、前置元数据）转换为标准格式
• 优化技能描述，使其在相关提示时更可靠地触发
• 为技能添加评估测试用例 (evals/evals.json)
• 批量验证目录中的所有技能以确保一致性

Agent Skills 规范参考

前置元数据字段

标准目录结构

skill-name/
├── SKILL.md          # 必需
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：详细文档
├── assets/           # 可选：模板、图片、数据
└── evals/            # 可选：评估测试用例
    └── evals.json

渐进式加载层级

操作指南

步骤 1：验证现有技能

在技能目录上运行验证脚本：

bash scripts/validate_skill.sh path/to/skill-directory

验证目录中的所有技能：

bash scripts/validate_skill.sh --all .agent-skills/

脚本会检查：

• 必需的前置元数据字段 (name, description)
• name 格式：小写，无连续连字符，与目录名匹配
• description 长度：1–1024 字符
• allowed-tools 格式：空格分隔（不是 YAML 列表）
• 推荐的章节是否存在
• 文件长度：超过 500 行时发出警告

步骤 2：编写有效的描述

description 字段决定了技能何时触发。描述不佳意味着技能永远不会被激活；描述过于宽泛则会在错误的时间触发。

模板：

description: >
  [技能的功能 — 列出具体的操作。]
  当 [触发条件] 时使用。即使用户没有明确提到 [领域关键词] — 也会在以下情况触发：[同义词列表]。

原则（来自 agentskills.io）：

1. 祈使句表述 — “当…时使用此技能” 而不是 “此技能可以…”
2. 用户意图，而非实现 — 描述用户想要实现的目标
3. 明确说明边缘情况 — “即使他们没有说 X”
4. 列出触发关键词 — 同义词、用户可能输入的相关术语
5. 保持在 1024 字符以内 — 编辑过程中描述会变长；注意限制

优化前后对比：

# 优化前（效果差 — 从不触发）
description: Helps with PDFs.

# 优化后（效果好 — 可靠触发）
description: >
  从 PDF 文件中提取文本和表格，填写表单，合并和拆分文档。
  当用户需要处理 PDF 文件时使用，即使用户没有明确说 'PDF' — 触发词包括：填写表单、从文档中提取文本、合并文件、读取扫描页面。

步骤 3：创建新的 SKILL.md

使用此模板作为起点：

---
name: skill-name
description: >
  [技能的功能以及它处理的具体操作。]
  当 [触发条件] 时使用。触发词包括：[关键词列表]。
allowed-tools: Bash Read Write Edit Glob Grep
metadata:
  tags: 标签1, 标签2, 标签3
  version: "1.0"
---

# 技能标题

## 何时使用此技能
- 场景 1
- 场景 2

## 操作指南

### 步骤 1：[操作]
内容...

### 步骤 2：[操作]
内容...

## 使用示例

### 示例 1：[场景]
输入：...
输出：...

## 最佳实践
1. 实践 1
2. 实践 2

## 参考链接
- [链接文本](url)

步骤 4：转换旧版章节标题

步骤 5：添加评估测试用例

创建 evals/evals.json 文件，包含 2–5 个真实的测试提示：

{
  "skill_name": "你的技能名称",
  "evals": [
    {
      "id": 1,
      "prompt": "应该触发此技能的真实用户消息",
      "expected_output": "成功状态的描述",
      "assertions": [
        "具体可验证的断言（文件是否存在、计数是否正确、格式是否有效）",
        "另一个具体断言"
      ]
    }
  ]
}

好的断言是可验证的：文件存在、JSON 有效、图表有 3 个柱子。避免使用像“输出良好”这样模糊的断言。

可用脚本

• scripts/validate_skill.sh — 根据 Agent Skills 规范验证 SKILL.md

使用示例

示例 1：验证一个技能目录

bash scripts/validate_skill.sh .agent-skills/my-skill/

输出：

正在验证: .agent-skills/my-skill/SKILL.md
✓ 必需字段: name = 'my-skill'
✓ 必需字段: description 存在
✗ 描述长度: 1087 字符 (最大 1024)
✓ 名称格式: 有效的小写格式
✗ 名称/目录不匹配: name='myskill' 而目录名为 'my-skill'
✓ 推荐章节: 何时使用此技能
✓ 推荐章节: 操作指南
⚠ 缺少推荐章节: 使用示例
✓ 文件长度: 234 行 (正常)

发现问题: 2 个错误, 1 个警告

示例 2：批量验证所有技能

bash scripts/validate_skill.sh --all .agent-skills/

示例 3：修复常见的前置元数据问题

# 错误写法 — 在某些验证器中，metadata 内的 tags 使用列表格式不符合规范
metadata:
  tags: [tag1, tag2]   # 列表语法
  platforms: Claude    # 非规范字段

# 正确写法 — 符合 Agent Skills 规范
metadata:
  tags: tag1, tag2     # 字符串值
allowed-tools: Bash Read Write  # 空格分隔，不是 YAML 列表

最佳实践

1. 描述质量优先 — 描述不佳意味着技能永远不会被激活；在优化其他部分之前先优化描述
2. 保持 SKILL.md 在 500 行以内 — 将详细的参考文档移到 references/ 目录
3. 固定脚本版本 — 使用 uvx ruff@0.8.0 而不是仅仅 ruff 以确保可重现性
4. 脚本中不要有交互式提示 — 代理在非交互式 shell 中运行；使用 --flag 输入，永远不要用 TTY 提示
5. 脚本输出结构化数据 — 优先使用 JSON/CSV 而不是自由格式文本；数据输出到 stdout，诊断信息输出到 stderr
6. 发布前添加评估 — 至少 2–3 个涵盖核心和边缘情况的测试用例

参考链接

• Agent Skills 规范
• 优化技能描述
• 评估技能
• 使用脚本
• 添加技能支持