skill-reviewer
daymade/claude-code-skills
Review and improve Claude Code skills against official best practices.
What is skill-reviewer?
Validates Claude Code skills for quality, structure, and security using automated checks and manual evaluation checklists. Use when publishing your own skills, reviewing external skill repositories, or contributing improvements to open-source skill projects.
- Automated validation of YAML, schema, frontmatter, and directory structure
- Checks for hardcoded paths, secrets, and script hygiene issues
- Evaluates instruction style, workflow patterns, and documentation quality
- Supports three modes: self-review, external review, and auto-PR submission
- Delegates deeper security scanning to the bundled skill-creator validator
- Provides detailed exit codes (0=clean, 1=warnings, 2=errors, 3=runtime failure)
How to install skill-reviewer
npx skills add https://github.com/daymade/claude-code-skills --skill skill-reviewer- Python 3.x environment
- PyYAML library (installed via uv)
- Access to target skill directory or repository
How to use skill-reviewer
- 1.Run automated review: uv run --with PyYAML python <skill-path>/scripts/review_skill.py <target-skill>
- 2.Review output exit code: 0=clean, 1=warnings, 2=errors, 3=runtime failure
- 3.For JSON output, add --json flag to the review command
- 4.Use evaluation_checklist.md for manual review of external skills
- 5.For external improvements, follow the additive-only principle: add features, preserve originals
- 6.Submit PRs with detailed explanation of changes and rationale
Use cases
- Validate your skill before publishing to ensure it meets best practices
- Review a community skill repository to identify quality improvements
- Generate an improvement report for an external skill with detailed rationale
- Submit a PR to an open-source skill with additive enhancements
- Run security scans on skills before distribution
- Skill authors publishing to Claude Code marketplaces
- Code agents and developers reviewing skill quality
- Open-source contributors improving community skills
- Teams establishing skill quality standards
skill-reviewer FAQ
Self-review validates your own skill before publishing using automated checks. External review evaluates someone else's skill repository by reading documentation, identifying intent, and generating an improvement report following the evaluation checklist.
No. The core principle is additive-only: add new capabilities, preserve original content, and explain every change. Never delete files, remove functionality, or change the primary language.
Exit code 0 means clean, 1 means warnings only, 2 means review errors that should be fixed, and 3 means the reviewer itself failed to complete a trustworthy review.
Fork the repository, create a feature branch, apply additive improvements only, run self-review to confirm it passes, then create a PR with detailed explanation of what changed and why.
The full checklist is in references/evaluation_checklist.md within the skill. It covers frontmatter, instructions, resources, and other quality dimensions beyond the quick checklist.
Full instructions (SKILL.md)
Source of truth, from daymade/claude-code-skills.
name: skill-reviewer description: Reviews and improves Claude Code skills against official best practices. Supports three modes - self-review (validate your own skills), external review (evaluate others' skills), and auto-PR (fork, improve, submit). Use when checking skill quality, reviewing skill repositories, or contributing improvements to open-source skills.
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 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
Related skills
More from daymade/claude-code-skills and the wider catalog.
skills-search
Search, discover, and manage Claude Code skills from the CCPM registry.
statusline-generator
Install, configure, and troubleshoot the Claude Code statusline with automatic health checks and two layout options.
teams-channel-post-writer
Creates educational Teams channel posts for internal knowledge sharing about Claude Code features, tools, and best practices. Applies when writing posts, announcements, or documentation to teach colleagues effective Claude Code usage, announce new features, share productivity tips, or document lessons learned. Provides templates, writing guidelines, and structured approaches emphasizing concrete examples, underlying principles, and connections to best practices like context engineering. Activates for content involving Teams posts, channel announcements, feature documentation, or tip sharing.
transcript-fixer
Corrects speech-to-text transcription errors using dictionary rules and AI-powered analysis. Builds personalized correction databases that learn from each fix. Triggers when working with ASR/STT output containing recognition errors, homophones, garbled technical terms, or Chinese/English mixed content. Also triggers on requests to clean up meeting notes, lecture transcripts, interview recordings, or any text produced by speech recognition. Use this skill even when the user just says "fix this transcript" or "clean up these meeting notes" without mentioning ASR specifically.
twitter-reader
Fetch Twitter/X posts and articles with full media support, automatic image download, and Markdown generation.
ui-designer
Extract design systems from UI images and generate implementation-ready design prompts.