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
- Structural Validation - Check folder structure and file naming conventions
- YAML Audit - Validate the frontmatter format and required fields
- Description Evaluation - Check whether the trigger conditions are clear
- Organization Scoring - Evaluate whether the skill is organized by task with common operations prioritized
- Instruction Review - Evaluate the quality and completeness of the main instructions
- Example Quality - Evaluate example density and executability
- Tips Scoring - Evaluate the quality and value of the tips section
- Best Practices - Check compliance against the official guide
Workflow
Step 1: Receive the audit request
When the user requests an audit of a skill:
- Confirm the skill folder path or read the contents of SKILL.md
- 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:
- Read
./skills/china-holidays/SKILL.md - Determine the review mode (standard by default)
- Check each item according to the rating card
- Generate a review report
- 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:
- Trigger strict mode
- Mustfirst read
anthropic-skills-development-guide.md - Strictly check each item against the official guide
- 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:
- Focus on analyzing the description field
- Use the 8-point rating standard
- 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.