skill-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Review

Skill审核

Overview

概述

Validates agent skills against the Agent Skills standard and compiled best practices. Reviews structure, frontmatter, description quality, progressive disclosure, and common anti-patterns.

根据Agent Skills标准和汇总的最佳实践验证Agent技能。审核内容包括结构、frontmatter、描述质量、渐进式披露以及常见反模式。

When to Use

使用场景

User asks to review or validate a skill
User is creating a new skill and wants feedback
User asks "is this skill well-written?"
User mentions skill quality, best practices, or improvement

用户要求审核或验证技能
用户正在创建新技能并需要反馈
用户询问“is this skill well-written?”
用户提及技能质量、最佳实践或改进需求

Review Process

审核流程

Phase 1: Load References

阶段1：加载参考资料

Before reviewing, read:

```
references/best-practices.md
```
— Comprehensive guidelines
```
references/checklist.md
```
— Quick validation checklist

审核前，请阅读：

```
references/best-practices.md
```
— 综合指南
```
references/checklist.md
```
— 快速验证清单

Phase 2: Identify Target

阶段2：确定审核目标

Determine what to review:

Single skill: Review
```
skills/<name>/SKILL.md
```
and its structure
All skills: Audit entire
```
skills/
```
directory
New skill draft: Review provided content before creation

明确审核对象：

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

Phase 3: Structural Audit

阶段3：结构审计

Check the skill directory structure:

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

Verify:

SKILL.md exists
Directory name matches
```
name
```
in frontmatter
References are one level deep (no nested chains)
Scripts use forward slashes (no Windows paths)
No extraneous files (README.md, CHANGELOG.md, etc.)
Script paths in SKILL.md body (
```
scripts/foo.py
```
) exist in directory
If scripts use external binaries, dependencies are documented

检查技能目录结构：

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
```
）在目录中存在
若脚本使用外部二进制文件，已记录依赖关系

Phase 4: Frontmatter Validation

阶段4：Frontmatter验证

Check YAML frontmatter:

yaml

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

Validate:

```
name
```
: Lowercase with hyphens only (
```
[a-z0-9-]
```
)
```
name
```
: ≤64 characters
```
name
```
: No "anthropic" or "claude" in name
```
description
```
: Non-empty, ≤1024 characters
```
description
```
: Third-person voice (not "I can" or "You can")
```
description
```
: Includes what it does AND when to trigger
```
description
```
: Contains specific trigger phrases

检查YAML前置元数据：

yaml

---
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
```
：包含具体触发短语

Phase 5: Description Quality

阶段5：描述质量评估

The description is the triggering mechanism. Evaluate:

Good descriptions include:

Specific actions: "Extract text and tables from PDF files"
Trigger phrases: "Use when analyzing Excel files, spreadsheets, or .xlsx"
Synonyms users might say: "tabular data, CSV, workbooks"

Bad descriptions:

Vague: "Helps with documents"
Generic: "Processes data"
Missing triggers: "Analyzes spreadsheets" (no "when to use")

描述是技能的触发机制，评估要点：

优质描述特征：

具体动作：例如“Extract text and tables from PDF files”
触发短语：例如“Use when analyzing Excel files, spreadsheets, or .xlsx”
包含用户可能使用的同义词：例如“tabular data, CSV, workbooks”

劣质描述特征：

模糊表述：例如“Helps with documents”
泛化表述：例如“Processes data”
缺失触发场景：例如“Analyzes spreadsheets”（未说明何时使用）

Phase 6: Body Analysis

阶段6：正文内容分析

Review SKILL.md body content:

Length:

Under 500 lines (check with
```
wc -l
```
)
If longer, split into reference files

Progressive Disclosure:

Quick start or overview near top
Details moved to references/
Long reference files (>100 lines) have TOC

Token Efficiency:

No obvious explanations (Claude already knows)
Examples over lengthy prose
Each line justifies its token cost

Degrees of Freedom:

High freedom for context-dependent tasks
Low freedom for fragile/error-prone tasks
Defaults provided when multiple options exist

审核SKILL.md正文内容：

长度：

少于500行（可使用
```
wc -l
```
命令检查）
若内容过长，拆分至参考文件中

渐进式披露：

顶部有快速入门或概述
详细内容移至references/目录
长参考文件（超过100行）包含目录（TOC）

Token效率：

无冗余解释（Claude已具备相关知识）
优先使用示例而非冗长文字
每一行内容都对应合理的Token成本

自由度控制：

上下文相关任务保留高自由度
易出错/脆弱任务限制自由度
存在多种选项时提供默认值

Phase 7: Anti-Pattern Check

阶段7：反模式检查

Scan for common issues:

Anti-Pattern	Look For
Windows paths	`scripts\file.py` instead of `scripts/file.py`
Nested references	A.md → B.md → C.md chains
Time-sensitive info	"If before August 2025..."
Magic numbers	Unexplained values
Too many options	"You can use X, or Y, or Z..." without default
Inconsistent terms	Mixing "endpoint"/"URL"/"route"
User-facing docs	README, CHANGELOG, installation guides
First/second person descriptions	"I can help" or "You can use"

扫描常见问题：

反模式	检查要点
Windows路径	使用 `scripts\file.py` 而非 `scripts/file.py`
嵌套参考	存在A.md → B.md → C.md的链式嵌套
时效性信息	例如“If before August 2025...”
魔术数字	未解释的数值
过多选项	例如“You can use X, or Y, or Z...”但未提供默认值
术语不一致	混用“endpoint”/“URL”/“route”等术语
用户面向文档	包含README、CHANGELOG、安装指南等
第一/第二人称描述	例如“I can help”或“You can use”

Phase 8: Report Findings

阶段8：输出审核结果

Present findings using this format:

undefined

使用以下格式呈现结果：

undefined

Skill Review: [skill-name]

Skill审核：[skill-name]

Summary

总结

[1-2 sentence overall assessment]

[1-2句话的整体评估]

Structure

结构

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

[✓/✗] 目录组织 [✓/✗] 文件存在性 [✓/✗] 参考资料深度

Frontmatter

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

[✓/✗] name字段验证 [✓/✗] description字段验证

Description Quality

描述质量

Score: [Strong / Adequate / Needs Work] Issues: [List specific problems] Suggested rewrite (if needed):

yaml

description: >-
  [Improved description]

评分：[优秀 / 合格 / 需要改进] 问题：[列出具体问题] 建议重写（若需要）：

yaml

description: >-
  [改进后的描述]

Body Analysis

正文分析

Line count: [X] lines Token efficiency: [Good / Could trim] Progressive disclosure: [✓/✗]

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

Anti-Patterns Found

发现的反模式

[Issue 1] — Location:
```
file:line
```
[Issue 2] — Location:
```
file:line
```

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

Recommendations

建议

[Actionable fix]
[Actionable fix]

undefined

[可执行的修复方案]
[可执行的修复方案]

undefined

Quick Review Mode

快速审核模式

For rapid validation, run through the checklist in

references/checklist.md

and report only failures.

如需快速验证，请按照

references/checklist.md

中的清单执行，仅报告未通过项。

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.

用于快速审核的参考验证清单。