# 官方 Skill 最佳实践检查项

来源：Anthropic Agent Skills Specification (agentskills.io) + github.com/anthropics/skills

## Frontmatter 规范

| 字段 | 必需 | 约束 |
|------|------|------|
| `name` | 是 | ≤64 字符，小写字母+数字+连字符，不能以连字符开头/结尾，不能连续连字符，必须与目录名一致 |
| `description` | 是 | ≤1024 字符，非空，描述做什么+何时使用 |
| `allowed-tools` | 否 | 空格分隔的预授权工具列表，如 `Bash(git:*) Read` |
| `metadata` | 否 | 任意 key-value，如 `author: team-name`、`version: "1.0"` |
| `compatibility` | 否 | ≤500 字符，环境要求，如 `"Requires git, docker"` |
| `license` | 否 | 许可证名称或文件引用 |

## Description 写作要点

- 用祈使句："Use this skill when..." 而非 "This skill does..."
- 聚焦用户意图，不是实现细节
- 宁可写得"强势"一点——明确列出触发场景，包括间接提及
- 硬限 1024 字符
- 包含 should-trigger 和 should-not-trigger 的边界

## 渐进式披露（三级加载）

| 级别 | 内容 | 加载时机 | 预算 |
|------|------|---------|------|
| L1 | name + description | 始终加载 | ~100 tokens/skill |
| L2 | SKILL.md 正文 | 触发时加载 | < 5000 tokens |
| L3 | references/scripts/assets | 按需加载 | 无硬限，但越少越好 |

## 内容价值优先级（高→低）

1. **Gotchas** — 环境特有的反直觉事实（如"此项目的 apiClient 已解包 response.data.data"）
2. **Output templates** — 具体输出格式结构，比散文描述有效
3. **Checklists** — 多步骤流程的检查清单
4. **Validation loops** — 执行→验证→修复→重复的闭环
5. **Plan-validate-execute** — 先计划、对照事实源验证、再执行
6. **Bundled scripts** — agent 反复写相同逻辑时，固化为脚本

## 控制粒度校准

| 自由度 | 适用场景 | 形式 |
|--------|---------|------|
| 高 | 多种可行方式、决策依上下文 | 文本指引、启发式 |
| 中 | 有首选模式、允许变体 | 伪代码、带参数脚本 |
| 低 | 操作脆弱易错、需高一致性 | 具体脚本、严格步骤 |

原则：**给默认值，不给菜单**；**教方法（procedure），不教结果（declaration）**。

## 常见反模式

| 反模式 | 问题 | 修正 |
|--------|------|------|
| SKILL.md > 500 行 | 吃上下文窗口 | ≤150 行理想，≤300 行可接受，详细内容移 references |
| 教基础知识 | 浪费 token | 删除 agent 已知的内容 |
| 万能 skill | 触发不可靠，职责模糊 | 拆成聚焦的独立 skill |
| 模糊 description | 激活不可靠 | 写具体触发场景和关键词 |
| 深层嵌套引用 | reference 引用另一个 reference | 保持一层深度 |
| 只声明不教方法 | agent 不知道怎么做 | 提供步骤和检查清单 |
| 所有内容平铺 | 核心流程和边界情况混在一起 | 核心在 SKILL.md，边界在 references |

## Eval 体系（参考，当前项目未实现）

官方 skill-creator 支持的测试框架：
- `evals/evals.json` — 测试用例（user prompt + 断言）
- With-skill vs without-skill 对比
- 断言评分：PASS/FAIL + 具体证据
- `benchmark.json` — 聚合统计（均值、标准差、delta）
- Description 优化循环：train/test 分割，最多 5 轮迭代