skill-review

技能审查

概述

依据 Agent Skills 标准和整理出的最佳实践，验证 Agent 技能。审查结构、frontmatter、描述质量、渐进式披露和常见反模式。

适用场景

• 用户要求审查或验证某项技能
• 用户正在创建新技能并希望获得反馈
• 用户询问“这项技能写得好吗？”
• 用户提到技能质量、最佳实践或改进

审查流程

阶段 1：加载参考资料

审查前，阅读：

• references/best-practices.md — 全面的指南
• references/checklist.md — 快速验证清单

阶段 2：确定目标

确定审查内容：

• 单项技能：审查 skills/<name>/SKILL.md 及其结构
• 所有技能：审计整个 skills/ 目录
• 新技能草稿：在创建前审查所提供的内容

阶段 3：结构审计

检查技能目录结构：

skill-name/
├── SKILL.md              # Required
├── references/           # Optional - loaded docs
├── scripts/              # Optional - executable code
└── assets/               # Optional - output files (not loaded)

验证：

• SKILL.md 存在
• 目录名称与 frontmatter 中的 name 一致
• 参考文件仅嵌套一层（没有嵌套链）
• 脚本使用正斜杠（不使用 Windows 路径）
• 没有多余文件（README.md、CHANGELOG.md 等）
• SKILL.md 正文中的脚本路径（scripts/foo.py）在目录中确实存在
• 如果脚本使用外部二进制文件，则已记录相关依赖项

阶段 4：Frontmatter 验证

检查 YAML frontmatter：

---
name: skill-name          # Required: lowercase, hyphens, ≤64 chars
description: >-           # Required: ≤1024 chars, third-person
  What it does. When to use it.
---

验证：

• name：仅使用小写字母和连字符（[a-z0-9-]）
• name：不超过 64 个字符
• name：名称中不包含 “anthropic” 或 “claude”
• description：非空，不超过 1024 个字符
• description：使用第三人称表述（不能写成 “I can” 或 “You can”）
• description：包含功能及触发时机
• description：包含具体的触发短语

阶段 5：描述质量

描述是触发机制。评估：

优质描述包含：

• 具体操作：“从 PDF 文件中提取文本和表格”
• 触发短语：“分析 Excel 文件、电子表格或 .xlsx 时使用”
• 用户可能会说的同义词：“表格数据、CSV、工作簿”

不佳描述：

• 含糊：“帮助处理文档”
• 泛泛而谈：“处理数据”
• 缺少触发条件：“分析电子表格”（没有“何时使用”）

阶段 6：正文分析

审查 SKILL.md 正文内容：

长度：

• 少于 500 行（使用 wc -l 检查）
• 如果更长，则拆分到参考文件中

渐进式披露：

• 顶部附近有快速入门或概述
• 详细内容移至 references/
• 较长的参考文件（>100 行）包含目录

Token 效率：

• 没有显而易见的解释（Claude 已经了解）
• 优先使用示例，而非冗长的说明
• 每一行都有其 token 成本上的价值

自由度：

• 对依赖上下文的任务给予较高自由度
• 对脆弱或容易出错的任务给予较低自由度
• 存在多种选项时提供默认选项

阶段 7：反模式检查

检查常见问题：

反模式	检查内容
Windows 路径	使用 scripts\file.py，而不是 scripts/file.py
嵌套参考	A.md → B.md → C.md 链
时效性信息	“如果在 2025 年 8 月之前……”
神奇数字	未解释的数值
选项过多	“可以使用 X、Y 或 Z……”但没有默认选项
术语不一致	混用“endpoint”/“URL”/“route”
面向用户的文档	README、CHANGELOG、安装指南
第一/第二人称描述	“我可以帮忙”或“你可以使用”

阶段 8：报告发现

使用以下格式呈现发现：

## Skill Review: [skill-name]

### Summary
[1-2 sentence overall assessment]

### Structure
[✓/✗] Directory organization
[✓/✗] File presence
[✓/✗] Reference depth

### Frontmatter
[✓/✗] name validation
[✓/✗] description validation

### Description Quality
**Score**: [Strong / Adequate / Needs Work]
**Issues**: [List specific problems]
**Suggested rewrite** (if needed):
```yaml
description: >-
  [Improved description]

正文分析

行数：[X] 行 Token 效率：[良好 / 可以精简] 渐进式披露：[✓/✗]

发现的反模式

• [问题 1] — 位置：file:line
• [问题 2] — 位置：file:line

建议

1. [可执行的修复措施]
2. [可执行的修复措施]

## Quick Review Mode

For rapid validation, run through the checklist in `references/checklist.md` and report only failures.

## Resources

### references/best-practices.md
Comprehensive guide covering architecture, design principles, writing effective descriptions, bundled resources, workflow patterns, and advanced patterns from production skills.

### references/checklist.md
Quick-reference validation checklist for fast reviews.