Skill Reviewer
FreeEnhance Claude Code skills with best practices.
Free · Opens the source repo
What Skill Reviewer does
Skill Reviewer is a specialized tool designed for developers and contributors who want to ensure the quality of Claude Code skills. It provides a structured approach to reviewing and improving skills by validating them against established best practices. The tool operates in three distinct modes: self-review, external review, and auto-PR, allowing users to validate their own skills, evaluate others’ contributions, and automate the process of forking and improving repositories. This flexibility makes it suitable for both individual developers and teams working on collaborative projects.
The self-review mode enables developers to check their skills before publishing, ensuring that they meet quality standards. Users can run automated reviews using simple command-line instructions, which check for various aspects such as YAML validation, frontmatter quality, and script hygiene. For deeper analysis, the tool also integrates with the skill-creator validator, providing a comprehensive overview of potential issues.
In external review mode, users can evaluate skills created by others. The process involves cloning the repository, reading the documentation, and using an evaluation checklist to generate an improvement report. This is particularly useful for open-source projects where multiple contributors are involved, as it helps maintain a consistent quality across different skills.
The auto-PR mode streamlines the contribution process by allowing users to fork a repository, make improvements, and submit a pull request with a detailed explanation of the changes. This ensures that contributions are additive, preserving the original author's intent while enhancing the skill's functionality. Overall, Skill Reviewer is an essential tool for anyone involved in developing or maintaining Claude Code skills, promoting best practices and improving the overall quality of the ecosystem.
When to use it
Use Skill Reviewer when you want to validate the quality of your own skills or evaluate skills developed by others, particularly in collaborative environments.
When not to use it
This tool may not be suitable for users looking for a general-purpose code review tool, as it specifically focuses on Claude Code skills and their compliance with best practices.
What you can build with it
Self-Validation Before Publishing
Use Skill Reviewer to check your own Claude Code skills for compliance with best practices before making them public.
Collaborative Skill Evaluation
Evaluate skills developed by team members or contributors to maintain a consistent quality across your project.
Automating Contribution Improvements
Leverage the auto-PR feature to streamline the process of forking, improving, and submitting changes to external skill repositories.
How to install Skill Reviewer
View source1. Install with the skills CLI
npx skills add daymade/claude-code-skills/skill-reviewer --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by daymadeSkill 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 run --with PyYAML python <this-skill-path>/scripts/review_skill.py <target-skill-path> --json
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:
uv run --with PyYAML python <this-skill-path>/scripts/review_skill.py <target-skill>
Extended security validation:
# Security scan
uv run python <this-skill-path>/../skill-creator/scripts/security_scan.py <target-skill> --verbose
Manual evaluation: See references/evaluation_checklist.md.
Mode 2: External Review
Evaluate someone else's skill repository.
Review Workflow:
- [ ] Clone repository to /tmp/
- [ ] Read ALL documentation first
- [ ] Identify author's intent
- [ ] Run evaluation checklist
- [ ] Generate improvement report
Mode 3: Auto-PR
Fork, improve, and submit PR to external skill repository.
Auto-PR Workflow:
- [ ] Fork repository (gh repo fork)
- [ ] Create feature branch
- [ ] Apply additive improvements only
- [ ] Self-review: respect check passed?
- [ ] Create PR with detailed explanation
Evaluation Checklist (Quick)
| Category | Check | Status |
|---|---|---|
| Frontmatter | name present? | |
| description present? | ||
| description in third-person? | ||
| includes trigger conditions? | ||
| Instructions | imperative form? | |
| under 500 lines? | ||
| workflow pattern? | ||
| Resources | no hardcoded paths? | |
| scripts have error handling? |
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
❌ "Removed metadata.json (non-standard)"
✅ "Added marketplace.json (metadata.json preserved)"
❌ "Rewrote README in English"
✅ "Added README.en.md (Chinese preserved as default)"
Common Issues & Fixes
Issue: Description Not Third-Person
# Before
description: Browse YouTube videos and summarize them.
# After
description: Browses YouTube videos and generates summaries. Use when...
Issue: Missing Trigger Conditions
# Before
description: Processes PDF files.
# After
description: Extracts text from PDFs. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
Issue: No Workflow Pattern
Add checklist for complex tasks:
## Workflow
Copy this checklist:
\`\`\`
Task Progress:
- [ ] Step 1: ...
- [ ] Step 2: ...
\`\`\`
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
❌ "Your skill doesn't follow best practices"
✅ "This PR aligns with best practices for better discoverability"
❌ "Fixed the incorrect description"
✅ "Improved description with trigger conditions"
Required Sections
- Summary - What this PR does
- What's NOT Changed - Show respect for original
- Rationale - Why each change helps
- Test Plan - How to verify
Template: references/pr_template.md
Self-Review Checklist
Before submitting any PR:
Respect Check:
- [ ] No files deleted?
- [ ] No functionality removed?
- [ ] Original language preserved?
- [ ] Author's design decisions respected?
- [ ] All changes are additive?
- [ ] PR explains the "why"?
References
scripts/review_skill.py- Automated reviewer backed byskill-creatorvalidationreferences/evaluation_checklist.md- Full evaluation checklistreferences/pr_template.md- PR description template- Best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
Frequently asked questions about Skill Reviewer
Similar skills
Quality Playbook Generator
Run comprehensive quality audits on any codebase.
PR Draft Summary
Automate PR summary generation for openai-agents-python.
Final Release Review
Streamline your release candidate audits with ease.
Unit Test Vue Pinia
Efficiently write and review unit tests for Vue 3 applications.
Slang Shader Expert
Optimize and integrate Slang shaders with ease.
Telemetry Standards
Ensure consistent event tracking in Supabase Studio.