skill-reviewer

A Skill that reviews other Agent Skills against a 10-rule rubric, distilled from the article "高质量 Skill 的十个套路". It can also scaffold a new Skill that respects the rubric from day one.

Two operating modes:

| Mode | Trigger | Output | | ---- | ------- | ------ | | Review | path is supplied, no --template | P0–P3 report (and optional fix plan) | | Template | --template <name> | New skill folder under .cursor/skills/<name>/ |

The rubric files live in references/. Do not load them all up front. Load each one only when you reach the step that needs it — that is rule #1 of the rubric, and this skill must walk the talk.

Argument parsing

Parse $ARGUMENTS (if provided by a slash command) or the user's free-text request into:

target — absolute or workspace path to a skill directory or to a SKILL.md file. Required in review mode.
--quick — skip soft rubric review, run only the lint script.
--rules <ids> — comma-separated rubric IDs to focus on (R1 … R10, see Rubric index below).
--template <name> — switch to template mode and create .cursor/skills/<name>/.
--json — emit machine-readable report instead of prose.

If the user invoked you without a clear path, ask them first (see Step 0).

Workflow checklist (copy and tick as you go)

Review mode:
- [ ] Step 0  Confirm mode & target           ⚠️ REQUIRED
- [ ] Step 1  Run lint-skill.mjs              (hard facts)
- [ ] Step 2  Soft review per rubric          (per-step reference load)
- [ ] Step 3  Aggregate findings by P0–P3
- [ ] Step 4  Ask user how to proceed         ⚠️ REQUIRED
- [ ] Step 5  Deliver report / apply fixes
- [ ] Step 6  Pre-delivery self-check

Template mode:
- [ ] Step T0 Gather skill intent             ⚠️ REQUIRED
- [ ] Step T1 Generate scaffold from template-skeleton.md
- [ ] Step T2 Run lint on the new scaffold    (self-verify)
- [ ] Step T3 Report scaffold + lint result

Step 0 — Confirm mode & target ⚠️ REQUIRED

Before running anything, confirm with the user using AskQuestion:

Mode: Review existing skill / Generate new skill template / Both (review then patch).
Target path (review only): absolute path or workspace-relative path. Accept either a skill directory or a SKILL.md file.
Scope (review only): full rubric or only specific rule IDs.

Skip this step only if --quick is set and target was supplied explicitly — in that case proceed directly to Step 1.

Step 1 — Run the hard-fact lint

Use the Shell tool to run the bundled linter. It is zero-dependency Node:

node .cursor/skills/skill-reviewer/scripts/lint-skill.mjs <target> --json

The script returns JSON with:

summary.counts — P0/P1/P2/P3 counts.
summary.verdict — BLOCKED | NEEDS_WORK | OK_WITH_NOTES | GOOD.
facts — line count, frontmatter, references files, orphan refs, etc.
findings — every hard-rule violation with id, severity, rule, message, optional evidence.

Treat every finding from the script as authoritative — do not soften or re-rank them. The script is the deterministic floor; the rubric review on top only adds findings.

If --quick is set, skip Step 2 and jump to Step 3.

Step 2 — Soft review per rubric (load on demand)

For each rule the user did not exclude via --rules, perform this loop:

Load only that one rubric file from references/.
Re-read the relevant slice of the target skill in light of that rubric.
Append findings to the running list. Use the same {severity, rule, message, evidence} shape as the lint script.

Rubric index — load only when you reach the corresponding step:

| ID | File | Focus | | --- | --------------------------------------- | ---------------------------------------- | | R1 | references/rubric-progressive-loading.md | Progressive Disclosure / file size | | R2 | references/rubric-description.md | description keyword density & triggers | | R3 | references/rubric-workflow-checklist.md | Workflow checklist quality | | R4 | references/rubric-scripts-pattern.md | Determinism via scripts/ | | R5 | references/rubric-good-questions.md | Concrete questions vs vague directives | | R6 | references/rubric-confirmation.md | Confirmation / BLOCKING nodes | | R7 | references/rubric-pre-delivery.md | Pre-delivery quality gate | | R8 | references/rubric-arguments.md | Parameter system & composability | | R9 | references/rubric-references-org.md | references/ organisation | | R10 | references/rubric-cli-pattern.md | CLI + Skill replacing MCP |

Stay disciplined: never read a rubric you are not currently evaluating.

Step 3 — Aggregate findings

Merge findings[] from the lint script with the soft-review findings. Sort by severity then by rule id. Compute totals per severity.

Severity definitions live in references/severity-levels.md — load that file once here.

Step 4 — Ask the user how to proceed ⚠️ REQUIRED

Use AskQuestion with options:

Fix everything (P0 + P1 + P2 + P3).
Fix only P0 and P1.
Fix specific findings (let the user paste IDs).
Report only — do not modify any file.

Never edit files in the target skill before getting this confirmation. This mirrors the article's principle: don't let the model take action you didn't sign off on.

Step 5 — Deliver report / apply fixes

Use the format from references/report-template.md (load it here). The report must contain, in order:

Verdict line (GOOD | OK_WITH_NOTES | NEEDS_WORK | BLOCKED).
Counts table.
Findings, grouped by severity, each with [rule-id] message → evidence → suggested fix.
If the user opted in to fixes: a list of files you modified plus a brief diff summary.

When applying fixes:

Use the StrReplace tool, not free-form rewrites.
Re-run the lint script after edits and include the new verdict in the report.
Never delete files the user wrote without confirmation.

Step 6 — Pre-delivery self-check

Before returning the report, verify each item below. Fail any of them → fix before responding.

[ ] Lint script was actually executed and its JSON output was consumed.
[ ] Every rubric ID the user asked for was loaded exactly once.
[ ] No rubric file was loaded that the user excluded with --rules.
[ ] All findings reference a real rule (matches a lint rule or a R1–R10 ID).
[ ] Verdict matches the highest severity present.
[ ] No file in the target skill was modified without the user's explicit consent in Step 4.

Template mode (Step T0 – T3)

Step T0 — Gather intent ⚠️ REQUIRED

Ask the user:

Skill name (kebab-case).
One-sentence purpose.
5–10 trigger phrases users would actually say.
Will it run scripts? generate output? need confirmation nodes?

Step T1 — Generate scaffold

Load references/template-skeleton.md. Create:

.cursor/skills/<name>/
├── SKILL.md
├── scripts/.gitkeep       # only if user said yes to scripts
└── references/
    └── .gitkeep

Apply each rubric while writing the scaffold:

R1: keep SKILL.md < 250 lines, push detail into references.
R2: pack the description with the user's trigger phrases.
R3: include a workflow checklist with at least one ⚠️ REQUIRED step.
R6: add a confirmation step before any irreversible action.
R7: include a pre-delivery checklist.
R8: parse $ARGUMENTS, document each flag, set argument-hint.

Step T2 — Self-verify

Run the lint script against the new scaffold. The verdict must be GOOD or OK_WITH_NOTES. If not, patch the scaffold until it is.

Step T3 — Report

Tell the user where the scaffold lives, what to fill in next, and what the linter said.

Anti-Slop reminders (do not skip)

This skill must respect every rule it enforces. If you change SKILL.md here, re-run the linter on this folder.
Prefer asking the user a concrete question over guessing the intent.
Never invent rubric IDs. The set is fixed: R1–R10 plus the hard rules emitted by lint-skill.mjs.
Cite findings with their rule field so the user can trace them back to either the script (scripts/lint-skill.mjs) or a rubric file under references/.