review-skill

Skill Reviewer

Review agent skills against best practices and rewrite weak areas.

When to Use

• After writing or editing a SKILL.md
• Before publishing a skill to agentskill.sh or sharing with a team
• When a skill underperforms (low ratings, poor triggering, inconsistent output)
• When asked to audit, review, or improve a skill

Review Process

Step 1: Read the Skill

Read the full SKILL.md and all referenced files (references/, scripts/, assets/). Note the skill's purpose, target audience, and complexity.

Step 2: Score Against 10 Dimensions

Evaluate each dimension on a 1-5 scale using the rubric in references/rubric.md.

Skill Review: <skill-name>

| # | Dimension              | Score | Key Issue                        |
|---|------------------------|-------|----------------------------------|
| 1 | Frontmatter            | ?/5   |                                  |
| 2 | Description Quality    | ?/5   |                                  |
| 3 | Conciseness            | ?/5   |                                  |
| 4 | Structure              | ?/5   |                                  |
| 5 | Instruction Clarity    | ?/5   |                                  |
| 6 | Freedom Calibration    | ?/5   |                                  |
| 7 | Error Handling         | ?/5   |                                  |
| 8 | Progressive Disclosure | ?/5   |                                  |
| 9 | Scripts Quality        | ?/5   |                                  |
|10 | Completeness           | ?/5   |                                  |

Overall: ?/50

Step 3: List Specific Issues

For each dimension scoring 3 or below, list concrete issues:

### Issues

1. [D2] Description is 15 characters, too vague to trigger reliably
2. [D3] Lines 45-80 explain what a CSV is; the agent already knows this
3. [D6] Three PDF libraries listed as equal options; pick a default

Step 4: Rewrite Problem Areas

For each issue, show the current text and a rewritten version. Apply changes directly if the user asks for it, otherwise present as suggestions.

### Fix: [D2] Description too vague

BEFORE:
description: Helps with PDFs.

AFTER:
description: >
  Extract text and tables from PDF files, fill PDF forms, merge
  documents. Use when working with PDF files or when the user
  mentions PDFs, forms, or document extraction.

Step 5: Estimate Token Impact

Count approximate tokens for the full SKILL.md body (excluding frontmatter). Flag if over 5,000 tokens with specific sections to move to references/.

Scoring Reference

The full rubric with examples is in references/rubric.md.

Quick thresholds:

• 40-50/50: Production-ready. Minor polish at most.
• 30-39/50: Good foundation. Address flagged issues before publishing.
• 20-29/50: Needs significant work. Multiple dimensions require rewriting.
• Below 20/50: Fundamental issues. Consider restructuring from scratch.

Common Fixes (Quick Reference)

Problem	Fix
Description too vague	Add what it does + when to use it + trigger keywords
Description uses first/second person	Rewrite in third person imperative
Explains things the agent already knows	Delete. Only add what the agent lacks.
Multiple equal options presented	Pick a default, mention alternatives briefly
No examples provided	Add 1-2 input/output pairs
Deeply nested file references	Flatten to one level from SKILL.md
SKILL.md over 500 lines	Move reference material to references/
Magic numbers in scripts	Add comments explaining why each value
Scripts fail silently	Add explicit error messages with guidance
No validation step in workflow	Add a validate-then-proceed loop
Time-sensitive information	Remove dates, use "current" / "legacy" sections
Inconsistent terminology	Pick one term per concept, use throughout
No frontmatter name field	Add name (lowercase, hyphens, max 64 chars)
No frontmatter description	Add description (max 1024 chars)
Windows-style paths	Replace backslashes with forward slashes