# review-skill

Adopt this skill: https://proskills.md/skills/other/agentskill-sh-ags-skills-review-skill

Page: https://proskills.md/skills/other/agentskill-sh-ags-skills-review-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/review-skill/SKILL.md
size: 4738
sha: a07b706688e95ab48795dd38c70d6ca3152b9e6b
upstream: https://github.com/agentskill-sh/ags/blob/main/skills/review-skill/SKILL.md

````text
---
name: review-skill
description: >
  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.
metadata:
  author: agentskill-sh
  version: "1.0"
includes:
  - references/**
---

# 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](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](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 |
````

## File: skills/review-skill/references/rubric.md
size: 10372
sha: 4636007e0aa1a676d0f48fd6805f6bd9054c8803
upstream: https://github.com/agentskill-sh/ags/blob/main/skills/review-skill/references/rubric.md

```text
# Skill Review Rubric

Evaluate each dimension on a 1-5 scale. Score honestly. A 3 is acceptable, not a failure.

---

## D1: Frontmatter (Spec Compliance)

Does the YAML frontmatter follow the Agent Skills specification?

| Score | Criteria |
|-------|----------|
| **5** | `name` and `description` present and valid. Optional fields (`license`, `compatibility`, `metadata`, `includes`) used where appropriate. Name matches directory, lowercase-hyphens only, no reserved words. |
| **4** | Required fields valid. One minor issue (e.g., name doesn't match directory, missing useful optional field). |
| **3** | Required fields present but one has issues (description too short, name uses uppercase). |
| **2** | Missing one required field, or name/description violate constraints. |
| **1** | No frontmatter, or both required fields missing/invalid. |

**Checks:**
- `name`: 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens
- `description`: 1-1024 chars, non-empty
- No XML tags in name or description
- Name must not contain "anthropic" or "claude"
- `metadata` values should be strings

---

## D2: Description Quality (Triggering)

Will agents select this skill for the right tasks?

| Score | Criteria |
|-------|----------|
| **5** | States what the skill does AND when to use it. Includes trigger keywords and edge-case contexts. Third-person imperative voice. Under 1024 chars. Would trigger reliably on relevant prompts and not trigger on adjacent-but-different tasks. |
| **4** | Good coverage of what and when. Minor gap in trigger keywords or slightly broad scope. |
| **3** | Describes what but not when (or vice versa). Or uses first/second person. Or too generic to distinguish from similar skills. |
| **2** | Vague ("helps with files"), too short to be useful, or would false-trigger on unrelated tasks. |
| **1** | Empty, single word, or actively misleading. |

**Key rules:**
- Third person imperative: "Extracts text from PDFs" not "I can help you extract text"
- Include both what it does and when to use it
- Include trigger keywords the user might say
- Be specific enough to distinguish from similar skills
- Stay under 1024 characters

---

## D3: Conciseness (Token Efficiency)

Does every token justify its context window cost?

| Score | Criteria |
|-------|----------|
| **5** | No unnecessary explanations. Only includes what the agent wouldn't know without the skill. Every paragraph passes the "does the agent really need this?" test. |
| **4** | Mostly concise. One or two sections could be trimmed without losing value. |
| **3** | Some bloat. Explains concepts the agent already knows (what a PDF is, how HTTP works, what a database migration does). |
| **2** | Significant bloat. Multiple paragraphs of unnecessary background or obvious explanations. |
| **1** | Mostly filler. More explanation than instruction. |

**Red flags:**
- Defining common terms (PDF, API, CSV, JSON)
- Explaining how well-known libraries work
- Repeating the same instruction in different words
- Long introductory paragraphs before useful content
- "In this section, we will..." preamble text

---

## D4: Structure (Progressive Disclosure)

Is the skill organized for efficient context loading?

| Score | Criteria |
|-------|----------|
| **5** | SKILL.md under 500 lines / 5000 tokens. Reference material in separate files. File references one level deep. Clear table of contents for files over 100 lines. Descriptive file names. |
| **4** | Good structure. One issue (e.g., SKILL.md slightly long, one deeply nested reference). |
| **3** | SKILL.md is 500-800 lines, or reference material mixed into SKILL.md that could be split out. |
| **2** | SKILL.md over 800 lines, or deeply nested references (A links to B links to C). |
| **1** | Everything in one massive SKILL.md with no structure. |

**Rules:**
- SKILL.md body under 500 lines, ideally under 5000 tokens
- Split large content into references/, scripts/, assets/
- File references should be one level deep from SKILL.md
- Reference files over 100 lines should have a table of contents
- Use descriptive file names: `form_validation_rules.md` not `doc2.md`
- Use forward slashes in all paths (no backslashes)

---

## D5: Instruction Clarity

Can the agent follow the instructions without ambiguity?

| Score | Criteria |
|-------|----------|
| **5** | Steps are clear, sequential, and unambiguous. Input/output examples provided. Edge cases addressed. Consistent terminology throughout. |
| **4** | Clear instructions with minor ambiguity in one area. |
| **3** | Generally understandable but requires interpretation in places. Inconsistent terminology or missing examples. |
| **2** | Ambiguous instructions that could be followed multiple ways. Key steps missing. |
| **1** | Instructions are contradictory, incomplete, or incomprehensible. |

**Checks:**
- One term per concept, used consistently (not "API endpoint" + "URL" + "API route")
- Concrete examples, not abstract descriptions
- No time-sensitive information (dates, "before August 2025")
- Templates for output format where format matters
- Checklists for multi-step workflows

---

## D6: Freedom Calibration

Is each part of the skill appropriately prescriptive for its fragility?

| Score | Criteria |
|-------|----------|
| **5** | Fragile operations (database migrations, file deletions) have exact commands. Flexible tasks (code review, analysis) give direction without over-constraining. Defaults provided, alternatives mentioned briefly. |
| **4** | Generally well-calibrated. One area slightly over/under-constrained. |
| **3** | Presents multiple equal options where a default would be better. Or over-constrains flexible tasks. |
| **2** | Fragile operations lack guardrails, or flexible tasks are rigidly scripted. |
| **1** | No awareness of task fragility. Everything treated the same. |

**Key rules:**
- Pick defaults, don't present menus of equal options
- Fragile/destructive operations: exact commands, no flexibility
- Analysis/creative tasks: direction and criteria, not rigid scripts
- Explain "why" for rigid rules so the agent can adapt in edge cases

---

## D7: Error Handling

Does the skill handle failure gracefully?

| Score | Criteria |
|-------|----------|
| **5** | Scripts handle errors explicitly with helpful messages. Validation loops (do work, validate, fix, repeat). Error table or section covering common failures. |
| **4** | Good error handling in most paths. One gap in error coverage. |
| **3** | Some error handling but gaps. Scripts may fail silently or with unhelpful messages. |
| **2** | Minimal error handling. Scripts punt errors to the agent without guidance. |
| **1** | No error handling. Scripts crash on edge cases. |

**For skills with scripts:**
- Scripts should handle errors explicitly, not punt to the agent
- Error messages should say what went wrong, what was expected, and what to try
- Include a validation step before destructive operations
- Constants should be documented (no magic numbers)

**For skills without scripts:**
- Include an error handling section or table
- Address common failure modes
- Provide fallback approaches

---

## D8: Progressive Disclosure

Does the skill load context efficiently?

| Score | Criteria |
|-------|----------|
| **5** | SKILL.md is a concise overview. Detailed material in separate files loaded only when needed. Clear signals telling the agent when to load each file ("Read references/api-errors.md if the API returns non-200"). |
| **4** | Good separation. One file could benefit from being split or loaded conditionally. |
| **3** | Some material in SKILL.md that should be in references. Or references exist but SKILL.md doesn't guide when to load them. |
| **2** | Most content in SKILL.md. References exist but are poorly signaled. |
| **1** | Everything in SKILL.md. No separate files despite the skill being complex. |

**Rules:**
- SKILL.md = overview + navigation
- references/ = detailed material loaded on demand
- Tell the agent WHEN to load each file, not just that it exists
- "Read references/api-errors.md if the API returns a non-200 status" > "See references/ for details"

---

## D9: Scripts Quality

Are bundled scripts well-designed for agentic use?

Score N/A if the skill has no scripts.

| Score | Criteria |
|-------|----------|
| **5** | Scripts are self-contained with inline dependencies. No interactive prompts. Clear --help output. Structured output (JSON/CSV). Meaningful exit codes. Idempotent where possible. Error messages include what went wrong and what to try. |
| **4** | Good scripts. One minor issue (missing --help, one script not idempotent). |
| **3** | Scripts work but have design issues (interactive prompts, unstructured output, poor error messages). |
| **2** | Scripts have significant issues (crash on edge cases, require undocumented setup, output is unparseable). |
| **1** | Scripts are broken, dangerous, or require extensive agent workarounds. |

**Checks:**
- No interactive prompts (agents can't respond to TTY input)
- --help documents usage, flags, and examples
- Structured output (JSON preferred) on stdout, diagnostics on stderr
- Meaningful exit codes for different failure types
- Dependencies declared inline (PEP 723 for Python, npm: for Deno, etc.)
- Idempotent operations (create-if-not-exists, not create-and-fail-on-duplicate)
- --dry-run for destructive operations

---

## D10: Completeness

Does the skill cover its stated scope?

| Score | Criteria |
|-------|----------|
| **5** | All features mentioned in the description are covered. Gotchas section captures non-obvious issues. Edge cases addressed. The skill is a coherent unit (not too narrow, not too broad). |
| **4** | Covers the stated scope with one minor gap. |
| **3** | Missing coverage for part of the described scope. Or scope is too broad/narrow for the content. |
| **2** | Significant gaps between description and content. Or skill tries to do too much. |
| **1** | Description promises features the skill doesn't deliver. |

**Checks:**
- Every capability in the description has corresponding instructions
- Gotchas section for non-obvious issues (environment-specific facts, naming inconsistencies, etc.)
- Scope is a coherent unit of work (not too broad, not too narrow)
- Procedures generalize rather than solving one specific instance
```

## File: README.md
upstream: https://github.com/agentskill-sh/ags/blob/main/README.md

````text
<p align="center">
  <img src="https://raw.githubusercontent.com/agentskill-sh/ags/main/assets/ags-banner.jpg" alt="ags = Agent Skills" width="100%">
</p>

<p align="center">
  <a href="https://github.com/agentskill-sh/ags/stargazers"><img src="https://img.shields.io/github/stars/agentskill-sh/ags" alt="GitHub stars"></a>
  <a href="https://www.npmjs.com/package/@agentskill.sh/cli"><img src="https://img.shields.io/npm/v/@agentskill.sh/cli" alt="npm version"></a>
  <img src="https://img.shields.io/badge/skills-100%2C000%2B-orange" alt="100,000+ skills">
  <img src="https://img.shields.io/badge/platforms-15+-blue" alt="15+ platforms">
  <a href="https://github.com/agentskill-sh/ags/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
</p>

<br />

## Quick Start

Copy-paste this into your AI agent (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, etc.):

```
Run: npx @agentskill.sh/cli@latest setup
Then search for skills relevant to this project using /learn
```

That's it. Your agent will install `/learn`, analyze your project, and suggest relevant skills from a directory of 100,000+.

<details>
<summary>Other install methods</summary>

**Install globally (then use `ags` directly)**

```bash
npm install -g @agentskill.sh/cli
ags setup
```

**Plugin marketplace (Claude Code only)**

```bash
/plugin marketplace add https://agentskill.sh/marketplace.json
/plugin install learn@agentskill-sh
```

Note: the plugin marketplace only installs the `/learn` skill. Use `npx @agentskill.sh/cli setup` to get all skills.

</details>

---

<p align="center">
  <img src="https://raw.githubusercontent.com/agentskill-sh/ags/main/assets/banner.jpg" alt="/learn Kung Fu" width="100%">
</p>

## Why /learn and agentskill.sh?

1. **Two-layer security.** After incidents like [OpenClaw](https://www.koi.ai/blog/openclaw-when-ai-skills-attack) showed how malicious skill files can compromise agents, vetting matters. agentskill.sh runs server-side static analysis on every skill across 12 threat categories:

> Command injection, data exfiltration, credential harvesting, prompt injection, obfuscation, sensitive file access, persistence mechanisms, external calls, reverse shells, destructive commands, social engineering, supply chain attacks

Each skill gets a security score (0-100). 110,000+ skills scanned, 100% coverage. Skills scoring below 30 require explicit confirmation before installation. Then `/learn` performs a second client-side scan before writing any files, so you get both centralized scanning and local verification. [See the live security dashboard.](https://agentskill.sh/security)

2. **Feedback loop.** Agents auto-rate skills after use (1-5 scale with comments), so the best ones surface and broken ones get flagged by the community. Your agent contributes to, and benefits from, collective quality signals.

3. **Version tracking.** Every installed skill is tagged with a content SHA, so you always know exactly what version you're running. When a newer version is available, `/learn update` shows what changed. Nothing breaks silently.

4. **Search broadly.** Instead of hunting for skills manually, search 100,000+ skills mid-conversation. Find what you need, install it, keep working.

---

## What is this?

This repo contains the official CLI and skills for [agentskill.sh](https://agentskill.sh).

| What | Description |
|------|-------------|
| **`ags` CLI** | Terminal tool to search, install, list, update, remove, and rate skills. Published to npm as [`@agentskill.sh/cli`](https://www.npmjs.com/package/@agentskill.sh/cli). |
| **`/learn` skill** | Agent skill that gives your AI the same capabilities mid-conversation. Uses the CLI under the hood. |
| **`review-skill` skill** | Reviews SKILL.md files against best practices and scores them on 10 quality dimensions. |

---

## CLI Commands

```bash
ags search <query>              # Search 100,000+ skills
ags install <slug>              # Install a skill
ags install @owner/skill-name   # Install from specific author
ags list                        # Show installed skills
ags update                      # Check for and apply updates
ags remove <slug>               # Uninstall a skill
ags feedback <slug> <1-5> [msg] # Rate a skill
```

All commands support `--json` for structured output.

---

## /learn Commands

When using the skill inside your agent:

| Command | What it does |
|---------|--------------|
| `/learn <query>` | Search for skills, interactive install |
| `/learn @owner/slug` | Install a specific skill |
| `/learn skillset:<slug>` | Install a curated bundle |
| `/learn` | Context-aware recommendations based on your project |
| `/learn trending` | Show trending skills |
| `/learn list` | Show installed skills |
| `/learn update` | Check for updates |
| `/learn remove <slug>` | Uninstall a skill |
| `/learn feedback <slug> <1-5>` | Rate a skill |

---

## Examples

```bash
# Find SEO skills
ags search "programmatic seo"

# Install a specific skill from an author
ags install @anthropics/react-best-practices

# Install for Cursor instead of Claude Code
ags install seo-optimizer --platform cursor

# Rate a skill you used
ags feedback seo-optimizer 5 "Excellent keyword clustering"

# Update all installed skills
ags update

# List installed skills as JSON
ags list --json
```

---

## How It Works

1. **Search** queries the agentskill.sh API
2. **Install** writes the skill to your platform's skill directory (e.g., `.claude/skills/`)
3. **Metadata header** is injected for version tracking and auto-review
4. **Auto-review**: after using a skill, your agent rates it automatically (1-5 scale)
5. **Update** compares local content hashes against the registry and re-installs outdated skills

---

## Supported Platforms

The CLI auto-detects your platform. Override with `--platform <name>`.

| Platform | Skill directory | Flag |
|----------|----------------|------|
| Claude Code | `.claude/skills/` | `claude-code` |
| Cursor | `.cursor/skills/` | `cursor` |
| GitHub Copilot | `.github/copilot/skills/` | `copilot` |
| Codex | `.codex/skills/` | `codex` |
| Windsurf | `.windsurf/skills/` | `windsurf` |
| Gemini CLI | `.gemini/skills/` | `gemini-cli` |
| Amp | `.amp/skills/` | `amp` |
| Goose | `.goose/skills/` | `goose` |
| Aider | `.aider/skills/` | `aider` |
| Cline | `.cline/skills/` | `cline` |
| Roo Code | `.roo-code/skills/` | `roo-code` |
| Trae | `.trae/skills/` | `trae` |
| Hermes | `~/.hermes/skills/` | `hermes` |
| OpenCode | `.opencode/skills/` | `opencode` |
| ChatGPT | `.chatgpt/skills/` | `chatgpt` |

---

## Security

Every skill on agentskill.sh has a security score (0-100). Skills below 30 trigger a warning before installation.

The `/learn` skill includes a [security pattern library](skills/learn/references/SECURITY.md) for detecting prompt injection, data exfiltration, obfuscated code, and other threats.

---

## Repo Structure

```
.
├── README.md
├── package.json              # npm: @agentskill.sh/cli
├── src/                      # CLI source
│   ├── index.ts
│   ├── api.ts
│   ├── platform.ts
│   └── commands/
│       ├── search.ts
│       ├── install.ts
│       ├── list.ts
│       ├── remove.ts
│       ├── update.ts
│       └── feedback.ts
├── skills/
│   ├── learn/                # /learn skill
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── SECURITY.md
│   └── review-skill/       # Skill quality reviewer
│       ├── SKILL.md
│       └── references/
│           └── rubric.md
├── assets/
│   └── banner.jpg
├── .claude-plugin/           # Claude plugin marketplace
└── LICENSE
```

---

## Contributing

Found a bug? Want to add a platform or a new skill? PRs welcome.

For creating and publishing your own skills, see the [skill creation guide](https://agentskill.sh/readme#how-to-create-a-skill).

---

## Sponsors

ags is maintained in the open thanks to its sponsors. [Become a sponsor](https://github.com/sponsors/romainsimon).

### Founding Sponso
````
