agentskill-sh/ags/review-skill

Claude Code and agent skill by agentskill-sh/ags

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Review and improve AI agent skills (SKILL.md files) against best practices from the Agent Skills specification and Anthropic's authoring guidelines. Scores skills on 10 quality dimensions, identifies specific issues, and rewrites problem areas. Use when creating, editing, auditing, or improving agent skills. Triggers on: review skill, improve skill, audit SKILL.md, check skill quality, skill best practices, optimize skill description.

Install

npx vskill@latest install agentskill-sh/ags/review-skill

SKILL.md

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)

ProblemFix
Description too vagueAdd what it does + when to use it + trigger keywords
Description uses first/second personRewrite in third person imperative
Explains things the agent already knowsDelete. Only add what the agent lacks.
Multiple equal options presentedPick a default, mention alternatives briefly
No examples providedAdd 1-2 input/output pairs
Deeply nested file referencesFlatten to one level from SKILL.md
SKILL.md over 500 linesMove reference material to references/
Magic numbers in scriptsAdd comments explaining why each value
Scripts fail silentlyAdd explicit error messages with guidance
No validation step in workflowAdd a validate-then-proceed loop
Time-sensitive informationRemove dates, use "current" / "legacy" sections
Inconsistent terminologyPick one term per concept, use throughout
No frontmatter name fieldAdd name (lowercase, hyphens, max 64 chars)
No frontmatter descriptionAdd description (max 1024 chars)
Windows-style pathsReplace backslashes with forward slashes

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
39
Repository forks
10
7-day trend score
18

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/agentskill-sh/ags/review-skill/badge)](https://verified-skill.com/skills/agentskill-sh/ags/review-skill)

Something wrong with this skill or its page? Tell us.