agentleFS
geemusgeemus/hax-yax/.agents/skills/review-skill/SKILL.md

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

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.
  • TheLatentSpaceLabSkill

    new-skill

    Create a new slash command skill

    Also in 3 projects that use this

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
  1. Very specific:

    Read SKILL.md first. Then read every supporting file present:

    line 37
  2. Distinctive:

    Do not begin reviewing until all files have been read.

    line 42
  3. Distinctive:

    Do instructions tell the agent *what to do* rather than *what to think about*?

    line 53
  4. Very specific:

    If the skill overlaps with another skill, does the description include TRIGGER when and DO NOT TRIGGER when lines that unambiguously …

    line 61
  5. Distinctive:

    Do examples cover non-obvious or alternate invocation forms (e.g.

    line 67
  6. Distinctive:

    Do examples cover edge cases or failure modes when they are likely in practice?

    line 69
  7. Distinctive:

    When presenting multiple findings, prefix each with a letter (a., b., c., …) so individual items can be referenced by letter.

    line 87
  8. Distinctive:

    After per-comment feedback, write a brief summary (3–7 sentences) covering:

    line 106

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 scripts
  • references/ — all reference documents
  • assets/ — 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 description open 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 when and DO NOT TRIGGER when lines 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:

SituationRecommended label
Blocks reliable agent useissue [blocking]
Strong improvementsuggestion
Minor style or wordingnitpick
Needs clarificationquestion
Small unambiguous fixtodo
Informational onlynote

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-plan

Invocation 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.