agentskill-sh/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 |