skill-reviewer

Skill Reviewer

Review and improve Claude Code skills against official best practices.

Quick Start

Run the bundled reviewer with PyYAML declared explicitly through uv:

uv run --with PyYAML python <this-skill-path>/scripts/review_skill.py <target-skill-path>
uv

The reviewer delegates YAML, schema, and internal-path validation to the canonical skill-creator validator bundled in the same suite. It then checks frontmatter quality, directory structure, SKILL.md size, hardcoded paths and secrets, script hygiene, subagent_type validity, and instruction-style heuristics.

Interpret exit codes as follows: 0 = clean, 1 = warnings only, 2 = review errors, 3 = invocation or runtime failure. Codes 1 and 2 describe the target skill; code 3 means the reviewer could not complete a trustworthy review.

Use the sibling skill-creator scripts for the deeper security scan and packaging checks.

Three Modes

Mode 1: Self-Review

Check your own skill before publishing.

Automated review:

Extended security validation:

Manual evaluation: See references/evaluation_checklist.md.

Mode 2: External Review

Evaluate someone else's skill repository.

Mode 3: Auto-PR

Fork, improve, and submit PR to external skill repository.

Evaluation Checklist (Quick)

Full checklist: references/evaluation_checklist.md

Core Principle: Additive Only

When improving external skills, NEVER:

• Delete existing files
• Remove functionality
• Change primary language
• Rename components

ALWAYS:

• Add new capabilities
• Preserve original content
• Explain every change

Common Issues & Fixes

Issue: Description Not Third-Person

Issue: Missing Trigger Conditions

Issue: No Workflow Pattern

Add checklist for complex tasks:

Issue: Missing Marketplace Support

Adding or validating marketplace.json (plugin boundaries, source/skills layout, whether skills are independently toggleable) is the marketplace-dev skill's domain — don't author it from a template here. Invoke daymade-claude-code:marketplace-dev, then follow its workflow and its cache and source patterns reference.

PR Guidelines

When submitting PRs to external repos:

Tone

Required Sections

1. Summary - What this PR does
2. What's NOT Changed - Show respect for original
3. Rationale - Why each change helps
4. Test Plan - How to verify

Template: references/pr_template.md

Self-Review Checklist

Before submitting any PR:

References

• scripts/review_skill.py - Automated reviewer backed by skill-creator validation
• references/evaluation_checklist.md - Full evaluation checklist
• references/pr_template.md - PR description template
• Best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices