Reviewing Skills

Objective

• A weighted score + letter grade
• Spec violations (blockers)
• Prioritized findings (P1/P2/P3) with concrete, minimal fixes
• Optional rewritten sections (only when needed to reach the quality bar)

$writing-skills

When to use / When not to use

• The user asks to review, grade, or audit a skill folder containing

  SKILL.md

  .
• The user wants rubric-based scoring and actionable edits (not just general advice).

• The user wants you to write a skill from scratch (use a writing skill instead).
• The request is not about a skill directory or does not involve

  SKILL.md

  .

Inputs

SKILL.md

agents/openai.yaml

scripts/

references/

assets/

1. Look for directories in CWD that contain

   SKILL.md

   .
2. If multiple, ask the user to choose.

Outputs

Safety / Constraints (non-negotiable)

• Read-only: do not edit, create, delete, or move files.
• Do not execute untrusted code: do not run repo scripts/binaries unless the user explicitly asks and you can justify the risk.
• Secrets: do not open or quote secrets (e.g.,

  .env

  , API keys, credentials). If encountered, redact and warn.
• Network: do not browse the web or call external systems unless the user explicitly requests it.
• No fabrication: if you cannot verify something, say so and recommend a verification step.
• No deep reference chasing: read only what is needed to score accurately (one level deep).

Verification Rules

Workflow (decision-complete)

1. Resolve the target skill directory
   • Confirm the path contains

     SKILL.md

     . If it does not, stop and ask for the correct folder.
2. Read the minimum necessary context (in order)

   1. <skill>/SKILL.md

   2. <skill>/agents/openai.yaml

      (if present)
   3. Any files under

      <skill>/scripts/

      referenced by

      SKILL.md

      (only those)
   4. Any files under

      <skill>/references/

      referenced by

      SKILL.md

      (only those)
3. (If in a git repo) gather change context
   • Prefer the repo’s base branch; if unknown, check

     git remote show origin

     for “HEAD branch”, otherwise try

     main

     then

     master

     (and state what you chose).

   • git diff <base> -- <skill>/

   • git log --oneline -20 -- <skill>/

   • For non-trivial diffs:

     git log -p -5 -- <skill>/SKILL.md

   • If

     <skill>/

     is new/untracked (so

     git diff <base>

     shows nothing), state that explicitly and treat contents as “new.”
   • If a score or finding is driven by a recent change, cite the relevant diff hunk or commit short-hash.
4. Score using the rubric
   • Use

     references/skills-rubric.md

     (single source of truth).
   • Give each dimension a 1.0–5.0 score (0.5 increments allowed).
   • Compute weighted score as:

     sum(weight_i * score_i) / 100

     .
5. Identify issues and merge duplicates
   • First list spec violations (blockers).
   • Then produce prioritized findings (max ~15 total), merging near-duplicates.
   • Every P1/P2 finding includes concrete patch text.
   • Patch rules: keep patches small/local; prefer "replace X with Y"; rewrite only the smallest section needed to clear P1/P2.
6. Produce the report
   • Default to

     references/review-template.md

     structure.
   • If the user requires a different structure, preserve the same content (grade, dimension scores, blockers, prioritized findings with patch text, token efficiency notes).
   • If the user requests a forensic or diff-centric review, add a hunk-by-hunk analysis for meaningful changes (

     +/-

     context), and classify each as improvement/regression/neutral.
   • Only include “Rewritten sections” when score < 4.5, any P1 exists, or the author requests a rewrite.

Review Guidelines

What to reward

• High signal per token: dense, directive, minimal prose.
• Correct triggering: description precisely indicates what and when.
• Decision-complete workflow: the skill leaves no key decisions ambiguous.
• Guardrails: destructive actions gated; secrets handled safely; constraints explicit.
• Portability: avoids tool-vendor lock-in; uses capability language with optional adapters.

What to penalize

• Vague directives (“as appropriate”, “best practices”, “use standard approach”).
• Over-broad scope (one skill trying to do too many disjoint jobs).
• Reference chains (SKILL.md → reference → another reference).
• Missing or non-actionable validation loops.
• “Cute” verbosity that costs tokens without improving outcomes.

Additional checks (inform findings; not scored as a separate dimension)

• Terminology consistency for core concepts across sections.
• Presence and usefulness of concrete examples/templates when output style matters.
• Anti-pattern scan: Windows-style paths, too many options without a default, time-sensitive claims, deep reference chains, and assumed package installs.

Edge cases (common failure modes)

• No git / no base branch: state what you could not verify; review file contents only.
• Large skills: stick to the tight-budget read order; do not “read everything” by default.
• Missing referenced files: treat as a spec violation or P1 (broken workflow), depending on severity.
• Secrets in context: redact and warn; do not quote.

Examples

• “Use $reviewing-skills to review

  ./some-skill/

  and provide a weighted grade, spec blockers, and prioritized patch text.”
• “Use $reviewing-skills to do a forensic/diff-centric review of

  ./some-skill/

  focusing on recent changes.”
• For a worked example format, see references/example-review.md.