Review Skill

Target Skill

The target skill to review is: $ARGUMENTS

If $ARGUMENTS is empty, ask the user which skill to review.

Mode Selection

When no mode keyword is present, default to Review + Auto-Fix. The deep review always runs in every mode. Auto-fix always follows the deep review unless the user explicitly requests report-only output.

Setup (Optional)

Install create-skill for automated validation: see references/setup.md

All modes work without it using manual evaluation.

Mode 1: Review + Auto-Fix (Default)

Run a full deep review across every evaluation dimension, then automatically fix all findings.

Step 1: Run automated validation (if create-skill installed):

python3 "$CREATE_SKILL"/scripts/quick_validate.py <target-skill>
python3 "$CREATE_SKILL"/scripts/security_scan.py <target-skill> --verbose

Step 2: Structural evaluation -- Read references/evaluation_checklist.md and check every item against the target skill. Record pass/fail for each item with the file path and line number of the finding.

Step 3: Content quality evaluation -- Read references/content-quality-checklist.md and evaluate all 8 dimensions (degrees of freedom, conciseness, actionability, options overload, script quality, feedback loops, consistency, time-sensitive content). Record findings per dimension.

Step 4: Deep review -- Read references/research-backed-criteria.md and check all 6 criteria. Record a pass/fail verdict for each:

1. •XML tag usage
2. •Example quality (3-5 diverse examples)
3. •Defect taxonomy (specification, input, structure, context, performance, maintainability)
4. •Anti-patterns (OWASP, vendor docs, academic)
5. •Formatting effectiveness
6. •HELM-inspired metrics (clarity, actionability, robustness, maintainability, safety)

Step 5: Generate report as markdown with:

• •Executive summary table (aspect, grade, notes)
• •Section-by-section findings with file paths and line numbers
• •Deep review results table (criterion, verdict, evidence)
• •Combined grade using the unified rubric from references/evaluation_checklist.md
• •Recommended fixes ranked by severity (major first, then minor)

Step 6: Verify report before presenting:

• • Every finding has a file path and line number
• • Grade matches rubric criteria
• • Fixes are actionable (no "consider" or "ensure")
• • Deep review covers all 6 criteria from references/research-backed-criteria.md

Step 7: Present report, then proceed to auto-fix. After showing the full review report, automatically apply all recommended fixes using the Auto-Fix procedure (Mode 2). Do not wait for user confirmation. The review informs the fix -- every finding from Steps 2-4 becomes a fix target.

Skill Review: pdf

Executive Summary

Deep Review Results

Findings

1. Line count approaching limit (Minor)

File: SKILL.md (487 lines) Fix: Move the "Advanced Extraction" section (lines 320-410) to references/advanced-extraction.md.

2. Missing default for output format (Minor)

File: SKILL.md, line 145 Finding: Lists JSON, CSV, and Markdown output without recommending a default. Fix: Add "Default to Markdown. Use JSON when the user needs machine-readable output."

Recommended Fixes (by severity)

1. •Extract advanced section to references (structural)
2. •Add default output format recommendation (content)

Auto-Fix Applied

Proceeding to fix all findings above...

Changes summary: 2 issues fixed, 1 file reorganised, line count reduced from 487 to 395. </example>

Mode 2: Auto-Fix

Automatically refactor a skill to meet best practices. When triggered by Mode 1 (Review + Auto-Fix), use the review findings as the fix list. When triggered standalone, run Steps 1-2 below to identify issues first.

Auto-Fix Progress:
- [ ] Step 1: Read SKILL.md and all loose files
- [ ] Step 2: Run evaluation, identify issues
- [ ] Step 3: Fix frontmatter (description, context: fork)
- [ ] Step 4: Create references/ folder if needed
- [ ] Step 5: Move content over 500 lines to references/
- [ ] Step 6: Move loose files to references/ with clear names
- [ ] Step 7: Update SKILL.md references section
- [ ] Step 8: Verify final line count under 500
- [ ] Step 9: Generate summary of changes (files modified, issues fixed, before/after line counts)

Auto-Fix Actions:

Content Quality Fixes:

Before (SKILL.md, 580 lines):

---
name: data-export
description: "Export data from databases"
license: MIT
---

• •No trigger conditions in description
• •No context: fork despite script usage
• •580 lines with inline SQL reference (lines 310-520)
• •Vague step: "Ensure the export format is correct"
• •3 loose files in root: formats.md, sql-ref.md, tips.md

After (SKILL.md, 340 lines):

---
name: data-export
description: "Exports data from SQL and NoSQL databases to CSV, JSON, or Parquet. Use when extracting datasets, scheduling recurring exports, or migrating between storage systems."
license: MIT
context: fork
agent: general-purpose
---

• •Description rewritten: third-person verb + three trigger conditions
• •context: fork added (scripts and <instructions> tags present)
• •SQL reference extracted to references/sql-syntax.md (210 lines saved)
• •Vague step rewritten: "Run python3 scripts/validate_schema.py against the output file"
• •Loose files moved: formats.md → references/export-formats.md, sql-ref.md merged into references/sql-syntax.md, tips.md → references/troubleshooting.md

Changes summary: 6 issues fixed, 3 files reorganised, line count reduced from 580 to 340. </example>

Mode 3: External Review

Read references/mode-external-review.md for the full procedure. Clone the target to /tmp/review-target, run the same three evaluation checks as Mode 1 Steps 2-4, generate a read-only improvement report, then clean up.

Mode 4: Auto-PR

Read references/mode-auto-pr.md for the full procedure. Fork the repository, run a full deep review, apply auto-fix, pass the self-review respect check, then submit a PR using references/pr_template.md.

References

Official Best Practices