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:

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:

1. Mode: Review existing skill / Generate new skill template / Both
   (review then patch).
2. Target path (review only): absolute path or workspace-relative path.
   Accept either a skill directory or a SKILL.md file.
3. 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:

1. Load only that one rubric file from references/.
2. Re-read the relevant slice of the target skill in light of that rubric.
3. 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:

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:

1. Verdict line (GOOD | OK_WITH_NOTES | NEEDS_WORK | BLOCKED).
2. Counts table.
3. Findings, grouped by severity, each with [rule-id] message → evidence → suggested fix.
4. 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/.