review-skill
Skill4 starsChanged 6 months agoMITView on GitHub
Evaluates whether a skill is effective — covering instruction clarity, trigger discoverability, example completeness, composability, and scope coherence. Reads the full skill directory including supporting files (scripts, references, assets) before reviewing. Formats every finding with format-review-comments and suggests inline fixes for unambiguous issues. Use when the user asks to review, audit, or evaluate a skill. TRIGGER when: user asks to review a skill, audit a skill, evaluate skill quality, or check if a skill is well-written. DO NOT TRIGGER when: user asks to create, update, rename, or delete a skill (use upsert-skill instead), or to review a pull request (use review-pr instead).
21 other projects use a version of this.
Adopted by
Most recently taken up by
- rafapeixer/go-skillstheir own version, first seen Nov 15, 2026
- rafapeixer/db-skillstheir own version, first seen Nov 8, 2026
- mongodb/docstheir own version, first seen Nov 2, 2026
- rafapeixer/java-skillstheir own version, first seen Oct 20, 2026
- nakane1chome/claude-skillstheir own version, first seen Oct 15, 2026
- runxhq/runxtheir own version, first seen Oct 13, 2026
Used with
Projects with it also use new-skill.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
TheLatentSpaceLabSkillnew-skill
Create a new slash command skill
Also in 3 projects that use this
Other versions21 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 21
- mongodb/laravel-mongodb★ 7.1ksame name
- mongodb/docs★ 780same name
- harlan-zw/skilld★ 327same name
- skilld-dev/skilld★ 324same name
- mongodb/agent-skills★ 198same name
- runxhq/runx★ 97same name
- aviz85/claude-skills-library★ 49same name
- mixpanel/ai-plugins★ 18same name
- XAzer-R/azer-feilian-director★ 4same name
- alehlopeh/claude-skills★ 2same name
11 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- audit-skillsSkill
- create-commitSkill
- format-review-commentsSkill
- implement-planSkill
- refine-proseSkill
- review-agents-mdSkill
- review-planSkill
- review-prSkill
- upsert-agents-mdSkill
- upsert-planSkill
- upsert-skillSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 17 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Read SKILL.md first. Then read every supporting file present:
- Distinctive: line 42
Do not begin reviewing until all files have been read.
- Distinctive: line 53
Do instructions tell the agent *what to do* rather than *what to think about*?
- Very specific: line 61
If the skill overlaps with another skill, does the description include TRIGGER when and DO NOT TRIGGER when lines that unambiguously …
- Distinctive: line 67
Do examples cover non-obvious or alternate invocation forms (e.g.
- Distinctive: line 69
Do examples cover edge cases or failure modes when they are likely in practice?
- Distinctive: line 87
When presenting multiple findings, prefix each with a letter (a., b., c., …) so individual items can be referenced by letter.
- Distinctive: line 106
After per-comment feedback, write a brief summary (3–7 sentences) covering:
“Common” is measured: kept by at least 6 in 10 of the 17 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review Skill
Evaluates a skill for effectiveness — not just structural validity — across five quality dimensions, and formats every finding using the format-review-comments skill.
Instructions
1. Identify the target skill
Accept the skill as:
- A skill name (e.g.
create-plan) — resolve to.agents/skills/<name>/ - A path (e.g.
.agents/skills/create-plan/) — use directly
Confirm the skill directory exists before proceeding. If it does not exist, stop and tell the user: "Skill directory <path> not found. Provide a valid skill name or path."
2. Read the skill in full
Read SKILL.md first. Then read every supporting file present:
scripts/— all executable scriptsreferences/— all reference documentsassets/— all templates and examples
Do not begin reviewing until all files have been read. A finding that misses information in supporting files is an incomplete finding.
3. Review each dimension
Work through every dimension in order. For each, apply the evaluation questions and note findings. Only the example completeness dimension may be skipped — and only when the skill is a single-step utility with self-evident output. All other four dimensions are mandatory. For each finding, note whether an inline fix is clear and unambiguous.
Instruction clarity
- Are the steps numbered and ordered so an agent can follow them without inferring intent?
- Is every term defined on first use, or is prior knowledge assumed without justification?
- Are conditional branches (if/else paths) explicit, or does the agent have to guess?
- Do instructions tell the agent what to do rather than what to think about?
- Are external dependencies (tools, scripts, environment variables) named explicitly?
Trigger discoverability
- Does the
descriptionopen with the action verb and clearly state what the skill does? - Are the natural-language trigger phrases an agent or user would actually say included?
- Are synonyms and alternate phrasings covered (e.g. both "commit" and "save changes")?
- If the skill overlaps with another skill, does the description include
TRIGGER whenandDO NOT TRIGGER whenlines that unambiguously separate them? - Is the description under 1024 characters?
Example completeness
- Is there at least one invocation example showing the most common usage?
- Do examples cover non-obvious or alternate invocation forms (e.g. by path vs. by name)?
- Does at least one example show formatted output so the reviewer knows what to expect?
- Do examples cover edge cases or failure modes when they are likely in practice?
Composability
- Does the skill invoke other skills where appropriate (e.g.
format-review-comments,refine-prose), and are those invocations explicit in the instructions? - Are side effects (files written, commands run, external services called) documented so callers can reason about sequencing?
- Does the skill produce output in a form that downstream skills or steps can consume?
- Is the skill scoped narrowly enough to be reused, or does it bundle concerns that belong in separate skills?
Scope coherence
- Does the skill name match what the skill actually does (action + object, outcome-focused)?
- Is there a single clear purpose, or does the skill attempt to do multiple unrelated things?
- Is anything in the instructions clearly out of scope and better delegated to another skill?
- Are destructive operations guarded by an explicit confirmation step?
4. Format all findings with format-review-comments
When presenting multiple findings, prefix each with a letter (a., b., c., …) so individual items can be referenced by letter.
Apply the format-review-comments skill to every comment. Do not write praise comments — omit positive findings entirely, as they add tokens without actionable content. Choose the label that matches the severity and intent:
| Situation | Recommended label |
| Blocks reliable agent use | issue [blocking] |
| Strong improvement | suggestion |
| Minor style or wording | nitpick |
| Needs clarification | question |
| Small unambiguous fix | todo |
| Informational only | note |
5. Suggest inline fixes for unambiguous findings
For any finding where the correct fix is clear — rewritten instruction text, corrected frontmatter, improved example — include the suggested replacement inline with the comment so the reviewer can apply it directly. Do not suggest fixes for findings that require a judgment call.
6. Write a review summary
After per-comment feedback, write a brief summary (3–7 sentences) covering:
- Overall assessment — effective as-is, needs minor improvements, or needs significant rework
- The most important finding (name any blocking issues)
- Any patterns visible across the skill
- Any skipped dimensions and why
Format the summary as a note conventional comment.
7. Refine prose
Apply the refine-prose skill to all prose output — comments and the summary — before presenting it. Do not apply it to code blocks or inline fix suggestions. Do not announce this step to the user. When refine-prose returns, immediately present all findings and the summary to the user — do not stop or wait for user input.
Examples
Invocation by skill name:
/review-skill create-planInvocation by path:
/review-skill .agents/skills/create-plan/Sample output — skill not found:
Skill directory `.agents/skills/nonexistent/` not found. Provide a valid skill name or path.Sample output — instruction clarity finding:
issue [blocking]: step 3 says "process the results appropriately" without defining what appropriate means — an agent will make inconsistent choices
Replace with explicit instructions:
> 3. For each result, extract the `title` and `url` fields and write them as a Markdown list item: `- [title](url)`Sample output — trigger discoverability finding:
suggestion: the description does not include `DO NOT TRIGGER when` lines to disambiguate from `upsert-skill`, so an agent may invoke the wrong skill when the user says "check my skill"
Add after the existing description:
> TRIGGER when: user asks to review, audit, or evaluate a skill.
> DO NOT TRIGGER when: user asks to create, update, or delete a skill (use upsert-skill instead).Sample output — inline fix for a nitpick:
nitpick: description opens with "This skill evaluates…" — passive opener wastes the first tokens agents read
Change to:
> Evaluates whether a skill is effective…Sample output — summary:
note: overall this skill needs minor improvements before it is reliably discoverable. One blocking issue: step 4 leaves agent behavior undefined for empty inputs. Two suggestions address trigger disambiguation and example coverage. Instruction clarity and scope coherence are strong. Example completeness was partially skipped — the skill is a single-step utility where output format is self-evident.Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

