skill-review
Skill0 starsChanged 4 months agoMITView on GitHub
Audits a candidate skill (.github/skills/<name>/SKILL.md) against five gates (spec compliance, content quality, scope fit, safety, currency & coherence). Use when reviewing a new skill draft before commit, evaluating a Mall unit or store skill for adoption, or re-auditing existing skills on a periodic cadence. For instructions, prompts, agents — use the matching per-type review skill.
25 other projects use a version of this.
Adopted by
Most recently taken up by
- snuffish/dotfilestheir own version, first seen Nov 8, 2026
- IT-HUSET/andthentheir own version, first seen Nov 8, 2026
- peterpme/skillstheir own version, first seen Nov 8, 2026
- patrykmurzyn/skillstheir own version, first seen Nov 8, 2026
- pillumina/ascend-sleuththeir own version, first seen Nov 2, 2026
- AbdouMoumen/claude-skills-plugintheir own version, first seen Nov 1, 2026
Used with
Projects with it also use sigma, skill-forge and 1 more.
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.
sanyuan0704Skillsigma
Personalized 1-on-1 AI tutor using Bloom's 2-Sigma mastery learning. Guides users through any topic with Socratic questioning, adaptive pacing, and rich visual output (HTML dashboards, Excalidraw concept maps, generated images). Use when user wants to learn something, study a topic, understand a concept, requests tutoring, says 'teach me', 'I want to learn', 'explain X to me step by step', 'help me understand', or invokes /sigma. Triggers on: learn, study, teach, tutor, understand, master, explain step by step.
Also in 3 projects that use this
WilliamSaysXSkillskill-forge
Automated skill creation workshop with intelligent source detection, smart path management, and end-to-end workflow automation. This skill should be used when users want to create a new skill or convert external resources (GitHub repositories, online documentation, or local directories) into a skill. Automatically fetches, organizes, and packages skills with proactive cleanup management.
Also in 3 projects that use this
GoogleSkillgrill-me
A relentless interview to sharpen a plan or design.
Also in 3 projects that use this
Other versions25 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 25
- sanyuan0704/code-review-expert★ 3.9ksame name
- sanyuan0704/sanyuan-skills★ 3.9ksame name
- QoderAI/better-harness★ 2.4ksame name
- fagemx/gstack-game★ 68same name
- joelhooks/joelclaw★ 65same name
- coupler-io/skills★ 39same name
- nimadorostkar/Claude-Skills-collection★ 33same name
- peterpme/skills★ 28same name
- pillumina/ascend-sleuth★ 5same name
- IT-HUSET/andthen★ 4same name
15 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 repository38 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- agent-creatorSkill
- agent-reviewSkill
- ai-memory-setupSkill
- alex-banner-generationSkill
- anti-hallucinationSkill
- brain-auditSkill
- browser-toolsSkill
- code-reviewSkill
- creative-writingSkill
- critical-thinkingSkill
- deep-reviewSkill
- doc-hygieneSkill
- docx-to-mdSkill
- git-workflowSkill
- greeting-checkinSkill
- html-to-mdSkill
- humanizerSkill
- instruction-creatorSkill
- instruction-reviewSkill
- lint-clean-markdownSkill
- markdown-mermaidSkill
- markdown-sanitization-chainSkill
- md-to-emlSkill
- md-to-htmlSkill
- md-to-txtSkill
- md-to-wordSkill
- meditationSkill
- planSkill
- problem-framing-auditSkill
- prompt-creatorSkill
- prompt-reviewSkill
- security-and-hardeningSkill
- skill-creatorSkill
- spikeSkill
- status-reportingSkill
- systematic-debuggingSkill
- test-driven-developmentSkill
The file
Files
<!-- intentional divergence from Supervisor: Edition strips Supervisor-only refs (ADR-007, `scripts/brain-qa.cjs` per-script citations, instruction-specific Gate 1 rows since heirs review skills only, and retired-entity examples Supervisor uses in Gate 5 illustrations). Same five gates, same criteria. Audited 2026-05-31. -->Skill Review
Audit a candidate skill against five gates. This brain accepts only what passes all five.
For other artifact types: instruction-review, prompt-review, agent-review. All four pairs share the same five-gate contract; per-type criteria differ.
When to Use
Three fire contexts:
- Author self-audit — dogfood your own draft before committing. Invoked from skill-creator Phase 7.
- External candidate adoption — gate before pulling a Mall unit, store skill, or any external artifact into this brain. Decide whether the artifact is fit before adopting.
- Periodic re-audit — re-check existing skills during currency-audit or quarterly retraining. Skills that no longer pass the gates revise or retire.
This skill carries the judgment checks a brain-qa validator cannot do (mechanical regex/date validation vs. content-quality judgment). Gate 1 partially overlaps with brain-qa where present; Gates 2–4 are judgment-only.
The Five Gates
A candidate must pass all five to ship. Failure on any gate = decline or revise.
These gates are the canonical source of truth. skill-creator inverts them into authoring phases — if the two ever disagree, this file wins and skill-creator must follow.
Gate 1 — Spec Compliance
| Check | Pass criterion |
| Frontmatter present AND minimal | YAML block carries exactly the canonical fields. Skills: name + description + lastReviewed. Reject any legacy extras (type, application, applyTo, inheritance, tier, currency, lifecycle, user-invokable, evidence). |
name valid | kebab-case, ≤64 chars, matches folder name |
description valid | Third-person, ≤1024 chars, names what the skill does AND when to use it (avoid slogans like "Clear documentation through visual excellence") |
| File location matches type | SKILL.md in skills/<name>/ |
| Markdown lints clean | No broken links, no missing code-fence languages |
This gate overlaps with a brain-qa validator where present. If brain-qa passes, Gate 1 is presumptively met; spot-check the judgment items (description third-person/trigger phrases).
Gate 2 — Content Quality
| Check | Pass criterion |
| Single responsibility | The artifact does one thing; if title contains "and" or "+", split it |
| Behavioral, not encyclopedic | Tells the agent what to do, not what a topic is |
| Has falsifiability or visible markers | The reader can tell whether the artifact fired correctly |
| ≤ 500 lines | Anthropic skill-spec ceiling; longer = signal of overload, split or trim |
| No duplicated content from existing artifacts | Grep for overlapping descriptions across .github/instructions/ and .github/skills/ |
| No graveyard prose | No "removed/dropped/used-to-have" sections; the file describes the live shape only |
Gate 3 — Scope Fit
| Check | Pass criterion |
| Target brain matches scope | Generic across ≥2 projects → this brain. Project-specific → that project's local skills, not here. External-surface delivery → Plugin Mall, not here. |
| Not framework-level | Does not modify ACT manifesto, tenets, or claims registry — framework changes go through an ADR, not a skill |
| Doesn't duplicate Plugin Mall content | If the value is a marketplace listing, it goes in the Mall, not the brain baseline |
Gate 4 — Safety
| Check | Pass criterion |
| No destructive defaults | Anything that deletes, force-pushes, or overwrites must require explicit user approval |
| No hardcoded credentials or PII | Run pii-memory-filter mentally over the diff |
| No prompt-injection vectors | If the artifact reads external content (URLs, files), it sanitizes or quotes it |
| Reversible | A user can disable or remove the artifact without breaking the brain |
Gate 5 — Currency & Coherence
The semantic layer of currency-and-coherence judgment. A mechanical validator (brain-qa script) typically catches the obvious cases (broken links, missing allow markers, stale dates, H1/name divergence); this gate covers the subtler ones that require deep reading.
| Check | Pass criterion |
| Frontmatter matches body | Description's "what + when" claims survive a deep read of the body. No drift between advertised scope and actual content. |
| No stale entity references (semantic) | References to retired entities carry a per-file <!-- brain-qa: allow <Entity> --> marker AND the marker is justified — the reference adds historical or operational value, isn't fossil. |
| Cross-references resolve and add value | Every markdown link (the \[label\]\(target\) form) points to a live artifact AND the target adds something the reader needs. Dead links and decorative xrefs both fail. |
lastReviewed is honest | The date reflects when the file was actually re-verified, not a rubber-stamp. Body content must be consistent with what was true at that date. |
| H1 matches advertised scope | The H1 reflects the skill's actual scope per name + description. "MCP Server Development Guide" vs name "mcp-builder" fails this gate. |
| Description has "what" AND "when" | Third-person; names the operation AND the trigger phrases. No slogans, no missing trigger clauses. |
| Body free of slogans / marketing prose | Plain operational language. No "powerful", "comprehensive", "seamless", "unleash". No graveyard prose ("removed/dropped/used-to-have" sections). |
Related section is live | Linked-to artifacts exist AND each adds material value beyond cross-linking for the sake of it. |
Decision Matrix
| Gates passed | Action |
| All 5 | Accept — land the change |
| 4 of 5 | Revise — name the failing gate and patch the candidate |
| 3 of 5 or fewer | Decline — name the rationale; if the decline sets precedent, record it where your heir tracks framework-level decisions |
Recording the Verdict
For self-audits and routine re-audits: the verdict lives in the commit message or the conversation. No separate file.
For external adoption (Mall unit, store skill) or any decline that sets precedent: write a verdict capturing gate results, rationale, required changes (if Revise), and the act-pass trail. This is the audit trail for adoption decisions, not a ceremonial form for every audit.
Anti-Patterns
| Anti-pattern | Correction |
| Accepting because the author is confident | Confidence ≠ quality. Run all five gates regardless of authorship |
| Declining without naming the gate | Always cite the specific gate; vague declines waste cycles |
| Accepting "trivial" candidates without audit | Trivial-looking changes are where regressions hide |
| Skipping the act-pass trail on non-trivial audits | Medium-stakes audits (new artifact, external adoption) require the trimmed pass; routine re-audits of unchanged artifacts do not |
| Gates drifting from skill-creator | If a gate here disagrees with a skill-creator phase, update skill-creator — this file is the source of truth |
Falsifiability
This skill's five-gate model has failed if any of the following occur within 90 days:
- An accepted candidate (all 5 gates passed) is reported broken by 2+ heirs
- Declines cluster on one gate and are later reversed during re-audit (gate too strict or unclear)
- Repeated audits of equivalent candidates produce contradictory gate outcomes
- Gate 5 produces a false-positive rate >20% over a quarter (the semantic layer is too aggressive)
- A defect that Gate 5 was supposed to catch ships through an accepted review
Track these as you would any falsified discipline (commit log, retraining notes, or curation ledger if your repo ships one) tagged [GATE-FAILURE].
Related
- skill-creator — inverts these gates to author candidates that pass by construction
- instruction-review — sibling for instructions
- prompt-review — sibling for prompts
- agent-review — sibling for agents
- act-pass — required for medium-stakes audits
/review-skillprompt — slash-command entry point
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.