SuperAPI AI Directory

skill-reviewer

Coding & development

View repository

Updated 10-16 08:54

About this skill

Skill Reviewer

Conduct a comprehensive audit of the skill based on Anthropic's official Skills development guide. Provides a structured audit framework, scoring system, defect checklist, and improvement suggestions.

Core Responsibilities

  1. Structural Validation - Check folder structure and file naming conventions
  2. YAML Audit - Validate the frontmatter format and required fields
  3. Description Evaluation - Check whether the trigger conditions are clear
  4. Organization Scoring - Evaluate whether the skill is organized by task with common operations prioritized
  5. Instruction Review - Evaluate the quality and completeness of the main instructions
  6. Example Quality - Evaluate example density and executability
  7. Tips Scoring - Evaluate the quality and value of the tips section
  8. Best Practices - Check compliance against the official guide

Workflow

Step 1: Receive the audit request

When the user requests an audit of a skill:

  1. Confirm the skill folder path or read the contents of SKILL.md
  2. Determine the audit strictness level:

Strict mode (must read the full official guide): When the user expresses the following intentions, you must first read the references/anthropic-skills-development-guide.md full guide:

  • Explicitly requests "strict checking", "careful auditing", "comprehensive review"
  • Mentions "high quality requirements", "production level", "pre-release check"
  • Expresses "doesn't want any omissions", "by the highest standards"
  • For team/organization/company projects
  • Preparing for public release or sharing with others

Standard mode:

  • Prioritize reading references/checklist.md(quick checklist)
  • Read the full official guide when encountering questions or edge cases

Step 2: Structural Check

Folder structure validation:

[ ] 技能文件夹使用 kebab-case 命名(如 my-skill)
[ ] SKILL.md 存在且命名精确(区分大小写)
[ ] 无 README.md 在技能文件夹内
[ ] 可选文件夹(如存在)命名规范

Optional folder naming conventions (if present):

  • scripts/ - All lowercase plural, no spaces/underscores
  • references/ - All lowercase plural, no spaces/underscores
  • assets/ - All lowercase plural, no spaces/underscores

❌ Incorrect example: Scripts、script、scripts_backup、References、refs、Assets、asset_files

Score: __/4


Step 3: YAML Frontmatter Check

Required field validation:

[ ] name 字段存在,kebab-case,无空格大写
[ ] description 字段存在,非空
[ ] YAML 分隔符完整(--- 开头和结尾)
[ ] 无 XML 标签(< >)
[ ] name 不以 claude/anthropic 开头

Description quality score (out of 8 points):

[2] 开头说明做什么(主动动词)
    好:"分析 Figma 设计文件并生成开发者交接文档"
    差:"这是关于 Figma 的技能"

[2] 包含触发条件("当用户...时")
    好:"当用户上传 .fig 文件或询问设计规格时使用"
    差:无触发条件

[2] 具体范围(提及具体工具、操作或场景)
    好:"Figma 设计文件、.fig、组件文档、设计交接"
    差:"帮助处理项目"

[2] 合理长度(50-200 字符,不超过 1024)
    太短:无搜索价值
    太长:被截断

Score: __/8


Step 4: Organization Scoring

Organized by task/scenario (rather than by abstract concepts):

[2] 按任务/操作组织章节
    好:"## 编码和解码" → "## 检查字符" → "## 转换格式"
    差:"## 理论" → "## 类型" → "## 高级"

[2] 常见操作优先
    好:基础用法 → 变体 → 高级 → 边界情况
    差:配置说明 → 理论背景 → 最后才是基础用法

[1] 章节自包含(可独立使用)

[1] 深度一致(不混用 h2 与 h4 随机跳转)

Score: __/6


Step 5: Main Instruction Check

Must include:

[ ] 清晰的工作流程或步骤说明
[ ] 至少一个使用示例
[ ] 错误处理或故障排查指南

Recommended (no point deduction):

[ ] 预期输出说明
[ ] 多个场景示例
[ ] 参考文档链接
[ ] "使用场景" 或 "When to Use" 部分

Score: __/6


Step 6: Example Quality Evaluation

Example density calculation:

总行数:___
代码块数量:___
密度:每 ___ 行 1 个代码块

参考目标:每 5-20 行 1 个代码块
< 5 行/块:可能过于碎片化(短命令集或多命令速查除外)
> 30 行/块:需要更多示例

Example density score:

[3] 密度在 5-20 行/块范围内
[2] 密度略低(20-30 行/块)或略高(3-5 行/块)
[0] 密度严重不足(>30 行/块)或过高(<3 行/块)

Quality score for each example (0-3 points):

[ ] 语言标签正确(```bash, ```python 等)
[ ] 语法正确,命令可执行
[ ] 展示了预期输出或结果说明
[ ] 使用真实值(非 foo/bar/baz)
[ ] 无占位符(TODO, FIXME, xxx)
[ ] 自包含或有设置说明

0 分:broken 或有误导性
1 分:可用但简陋(无输出/上下文)
2 分:良好(正确,有输出或说明)
3 分:优秀(可直接复制,真实,覆盖边界)

Example quality score = average score of all examples × density score / 3 = __/9


Step 7: Executability Evaluation

Core question: Can the Agent produce correct results by following these instructions?

[3] 使用祈使句("运行 X"、"创建 Y")
    非:"可以考虑..."或"建议..."或"You might..."

[3] 步骤顺序合理(前置条件在行动之前)

[2] 错误处理(说明失败时怎么做)

[2] 输出/结果描述(如何验证成功)

Rating: __/10


Step 8: Progressive Disclosure Check

[ ] SKILL.md 控制在 500 行以内
[ ] 详细文档是否在 `references/` 中
[ ] 大文件(>300 行)有目录或结构说明

Rating: __/3


Step 9: Tips Rating

Tips section quality assessment:

[2] 5-10 条技巧
    少于 5 条:覆盖不足
    多于 10 条:可能不够精炼

[2] 技巧非显而易见
    好:"Makefile 头号陷阱:缩进必须用 Tab,不能用空格"
    差:"确保测试你的代码"

[2] 技巧具体可执行
    好:"使用 flock 防止 cron 任务重叠执行"
    差:"小心并发执行"

[1] 技巧不矛盾主体内容

[1] 技巧覆盖特定主题的陷阱/踩坑点

Rating: __/8


(Optional) Metadata Reference

Check only when the skill contains a metadata field; for reference only, not scored

[ ] emoji 与技能主题相关
[ ] requires.anyBins 列出技能实际使用的工具(非 generic 如 bash)
[ ] os 数组准确(不包含不支持的平台)
[ ] JSON 格式有效

Rating Summary

SKILL 审核评分卡
═══════════════════════════════════════
技能名称:{name}
审核者:{agent/human}
日期:{date}
审核模式:{严格/常规}

类别                  得分     满分
─────────────────────────────────────
结构检查              __       4
Description 质量       __       8
组织评分              __       6
主体指令              __       6
示例质量              __       9
可执行性              __      10
渐进式披露            __       3
Tips 评分             __       8
─────────────────────────────────────
总分                  __      54

转换为百分制:总分 × 1.85 = ___/100

评级:
  85+  优秀 — 可直接发布
  70-84 良好 — 需要小改进
  50-69 一般 — 需要明显改进
  < 50  较差 — 需要重大修改

结论:{PUBLISH / REVISE / REWORK}

Common Defects

Critical Defects (Block Release)

缺陷:YAML 前置信息无效
检测:YAML 解析错误、缺少必填字段
修复:验证 YAML 格式,确保 name/description 都存在

缺陷:代码示例损坏
检测:语法错误、未定义变量、错误参数
修复:在干净环境中测试每个命令

缺陷:工具要求不匹配(如存在 metadata)
检测:requires 列出内容未在内容中使用
修复:grep 内容提取命令名,更新 requires 匹配

缺陷:误导性描述
检测:描述承诺的内容实际未覆盖
修复:使描述与实际内容一致,或补充缺失内容

Major Defects (Should Be Fixed Before Release)

缺陷:缺少"使用场景"部分
影响:Agent 不知道何时激活技能
修复:添加 4-8 条触发场景说明

缺陷:大段文字无示例
检测:任何超过 10 行无代码块的章节
修复:为每个概念添加具体示例

缺陷:示例缺少语言标签
检测:``` 后无语言标识符
修复:为每个代码块添加 bash/python/javascript/yaml 等

缺陷:缺少 Tips/技巧部分
影响:缺少使技能有价值的经验总结
修复:添加 5-10 条非显而易见的实用技巧

缺陷:按抽象概念组织
检测:章节名为"理论"、"概述"、"背景"、"介绍"
修复:按任务/操作重组:用户要做什么

Minor Defects (Recommended to Fix)

缺陷:占位符值
检测:foo, bar, baz, example.com, TODO, FIXME
修复:替换为真实值

缺陷:格式不一致
检测:混合标题级别、代码块样式不一致
修复:统一标题层次和格式

缺陷:缺少交叉引用
检测:提到其他技能覆盖的工具/概念但未引用
修复:添加"参见 X 技能了解更多"注释

缺陷:过时的命令
检测:旧语法或已弃用工具
修复:更新为当前工具版本和语法

Comparative Review

When comparing skills of the same type:

对比维度:

1. 覆盖广度
   哪个技能覆盖更多用例?

2. 示例质量
   哪个有更多可运行的真实示例?

3. 常见操作深度
   哪个更好地处理 80% 常见场景?

4. 边界情况覆盖
   哪个解决了更多潜在问题和陷阱?

5. 跨平台支持
   哪个适用于更多环境?

6. 时效性
   哪个使用当前工具版本和语法?

胜出者:{技能 A / 技能 B / 平局}
理由:{1-2 句说明}

Quick Review Template

For a quick review when a full rating is not needed:

## 快速审核:{skill-name}

**结构**:[通过/问题:...]
**Description**:[强/弱:原因]
**示例**:[X 个代码块,共 Y 行 — 密度 正常/低/高]
**可执行性**:[Agent 可以/不可以 遵循这些指令,因为...]
**首要缺陷**:[最应该修复的单一问题]
**评分**:__/100
**结论**:[PUBLISH / REVISE / REWORK]

Review Workflow

Self-Check Before Release

# 1. 验证 YAML 前置信息
head -20 skills/my-skill/SKILL.md
# 目视确认 YAML 有效

# 2. 统计代码块数量
grep -c '```' skills/my-skill/SKILL.md
# 总行数除以这个数得密度

# 3. 检查占位符
grep -n -i 'todo\|fixme\|xxx\|foo\|bar\|baz' skills/my-skill/SKILL.md

# 4. 检查缺失语言标签
grep -n '^```$' skills/my-skill/SKILL.md
# 每个代码块都应该有语言标签

# 5. 验证工具要求匹配内容(如存在 metadata)
# 提取 requires,然后 grep 内容检查每个工具

# 6. 测试命令(抽样 3-5 个)
# 在干净 shell 中运行验证

# 7. 运行评分卡
# 目标:良好 35+,优秀 45+

Reviewing Others' Skills

# 安装技能(如适用)
npx molthub@latest install skill-name

# 阅读内容
cat skills/skill-name/SKILL.md

# 运行快速审核模板
# 如分数 < 25,考虑卸载并寻找替代

Reference Files

Layered by use case:

File Purpose When to Read
references/checklist.md Quick Checklist Standard Review Process
references/official-guide-summary.md Condensed Guide Quick reference for commonly used specifications
references/anthropic-skills-development-guide.md Full Official Guide Must read in strict mode; consult when in doubt in standard mode

Strict Mode Trigger Conditions(triggered if any one is met):

  • The user explicitly requests "strict check", "comprehensive review", "careful review"
  • Mentions "high quality", "production-level", "before release"
  • Expresses "don't want any omissions", "by the highest standards"
  • For team/organization/company projects
  • Preparing for public release or sharing

Determine the mode first when reviewing: In strict mode, the full guide must be read before reviewing; in standard mode, consult as needed.


Examples

Example 1: Full Review

User says: "Help me review this skill, the path is ./skills/china-holidays"

Actions:

  1. Read ./skills/china-holidays/SKILL.md
  2. Determine the review mode (standard by default)
  3. Check each item according to the rating card
  4. Generate a review report
  5. Interpret the results and provide improvement suggestions

Result: Output a full review report, including a list of issues, modification suggestions, and the final rating

Example 2: Strict Mode Review

User says: "This skill is going to be released for internal team use, it needs a strict check, there can't be any problems"

Actions:

  1. Trigger strict mode
  2. Mustfirst read anthropic-skills-development-guide.md
  3. Strictly check each item against the official guide
  4. Output a detailed report, ensuring no omissions

Example 3: Quickly Check the description

User says: "How is the description of this skill written?" + attach the content

Actions:

  1. Focus on analyzing the description field
  2. Use the 8-point rating standard
  3. Provide improvement suggestions

Result: Point out issues and provide modification suggestions


Tips

  • Description is the most important — It accounts for more than 40% of actual impact. A perfect skill paired with a bad description will not be found.

  • First, count the code blocks — A skill with fewer than 8 code blocks is almost always too abstract to be useful.

  • Test 3-5 commands in a clean environment — If more than 1 fails, the skill was not tested before release.

  • Organize by task vs organize by concept — This is the most critical structural quality difference. Good skills answer "how to do X", bad skills explain "what X is".

  • A skill with good Tips but weak examples is more valuable than one with good examples but no Tips — Tips encode expertise that examples cannot convey.

  • Check whether requires matches actual usage — A common flaw is listing bash (which all have) instead of the actual tools such as docker, curl, jq.

  • A skill that is too short (<150 lines) is usually not worth publishing — They provide less value than a quick web search. If a skill is too short, it may be a section of a larger skill.

  • The best standard: would you bookmark and use it yourself — If you would not use it yourself, do not publish it.