Skill Reviewer
Audit a custom SKILL.md against Claude Code conventions—frontmatter, triggers, imperative steps, and progressive disclosure—before publishing or sharing the skill.
Overview
Skill Reviewer is an agent skill most often used in Build agent-tooling (also Ship review) that scores SKILL.md files against frontmatter, trigger, and instruction best practices.
Install
npx skills add https://github.com/daymade/claude-code-skills --skill skill-reviewerWhat is this skill?
- Full evaluation checklist for YAML frontmatter name and description constraints
- Third-person description and explicit “Use when…” trigger validation with worked bad/good examples
- Instruction quality checks for imperative workflow steps and checklist patterns
- Progressive disclosure review so agents load the right depth of guidance
- Documented gitleaks-style security scan metadata in the upstream skill readme
Adoption & trust: 561 installs on skills.sh; 1.2k GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
You wrote a custom skill but are unsure whether the description triggers correctly, violates naming rules, or reads like marketing instead of agent instructions.
Who is it for?
Solo builders publishing or maintaining multiple Claude Code skills who want a repeatable editorial review without manually rereading Anthropic-style conventions.
Skip if: Runtime security auditing of arbitrary npm packages or reviewing non-SKILL.md application codebases.
When should I use this skill?
After drafting or updating a SKILL.md, or when the user asks to evaluate skill quality, frontmatter, or trigger wording.
What do I get? / Deliverables
You get a structured pass/fail style review across frontmatter, triggers, imperative steps, and disclosure—ready to fix before publishing or invoking the skill in production agents.
- Checklist-style review report with frontmatter and instruction findings
- Concrete rewrite suggestions for description triggers and imperative steps
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Primary shelf is Build → agent-tooling because the checklist targets authoring and hardening agent skills in your repo. Agent-tooling is where solo builders create, version, and quality-gate SKILL.md packages alongside other Claude Code assets.
Where it fits
You finish a workflow skill and run the reviewer to fix description voice and missing trigger phrases.
Before tagging a release of your dot-skills repo, you batch-review every SKILL.md for naming and imperative form.
Anthropic documentation shifts naming guidance and you re-audit existing skills for reserved-word violations.
How it compares
Use as a editorial checker on SKILL.md artifacts, not as a substitute for Prism’s third-party security audit panel on ingested skills.
Common Questions / FAQ
Who is skill-reviewer for?
It is for developers building agent skills who need a consistent checklist aligned with Claude Code skill authoring norms.
When should I use skill-reviewer?
Use it in Build after drafting a new skill, in Ship before sharing a skill repo, and in Operate when updating descriptions after platform rule changes.
Is skill-reviewer safe to install?
The upstream readme notes a gitleaks-style scan; still verify current results in the Security Audits panel on this Prism page before trusting it in your environment.
SKILL.md
READMESKILL.md - Skill Reviewer
Security scan passed Scanned at: 2026-01-15T23:00:17.123502 Tool: gitleaks + pattern-based validation Content hash: 0c696633f662b65e56b69a2c88a8fadd5fa5a501d1832a47d81201fc4a1fa097 # Skill Evaluation Checklist Complete checklist for evaluating Claude Code skills against best practices. ## YAML Frontmatter - [ ] `name` field present and valid - Max 64 characters - Lowercase letters, numbers, hyphens only - No reserved words (anthropic, claude) - [ ] `description` field present and valid - Non-empty - Max 1024 characters - Third-person voice - Includes trigger conditions ("Use when...") ## Description Quality ### Third-Person Voice Check ``` ❌ "Browse YouTube videos..." ❌ "You can use this to..." ❌ "I can help you..." ✅ "Browses YouTube videos..." ✅ "This skill processes..." ``` ### Trigger Conditions Check Description should include: - What the skill does - When to use it - Specific triggers (file types, keywords, scenarios) ``` ❌ "Processes PDFs" ✅ "Extracts text and tables from PDF files. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction." ``` ## Instruction Quality - [ ] Imperative/infinitive form used (verb-first) - [ ] Concise (avoid obvious explanations) - [ ] Clear workflow steps - [ ] Checklist pattern for complex tasks ### Imperative Form Check ``` ❌ "You should run the script..." ❌ "The user can configure..." ✅ "Run the script..." ✅ "Configure by editing..." ``` ## Progressive Disclosure - [ ] SKILL.md body under 500 lines - [ ] Detailed content in `references/` - [ ] Large files include grep patterns - [ ] No duplication between SKILL.md and references ## Bundled Resources ### Scripts (`scripts/`) - [ ] Executable with proper shebang - [ ] Explicit error handling (no bare except) - [ ] Clear documentation - [ ] No hardcoded secrets ### References (`references/`) - [ ] Self-explanatory filenames - [ ] Loaded as needed, not always - [ ] No duplication with SKILL.md ### Assets (`assets/`) - [ ] Used in output, not loaded into context - [ ] Templates, images, boilerplate ## Privacy and Paths - [ ] No absolute user paths (`/Users/username/`) - [ ] No personal/company names - [ ] No hardcoded secrets - [ ] Relative paths only ## Workflow Pattern - [ ] Clear sequential steps - [ ] Copy-paste checklist provided - [ ] Validation/verification steps included ## Error Handling - [ ] Scripts have specific exception types - [ ] Error messages are helpful - [ ] Recovery paths documented ## Summary Table | Category | Status | Notes | |----------|--------|-------| | Frontmatter | | | | Description | | | | Instructions | | | | Progressive Disclosure | | | | Resources | | | | Privacy | | | | Workflow | | | | Error Handling | | | # PR Template for Skill Contributions Use this template when creating PRs for Claude Code skill repositories. ## PR Title Format ``` refactor: Align skill with Claude Code best practices ``` Or for specific improvements: ``` feat: Add marketplace support for plugin installation docs: Add bilingual documentation (English/Chinese) fix: Improve error handling in scripts ``` ## PR Body Template ```markdown ## Summary This PR improves the [skill-name] skill by aligning it with [Claude Code Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). ### What This PR Does - [Improvement 1] - [Improvement 2] - [Improvement 3] ### What This PR Does NOT Change - [Preserved item 1] - [Preserved item 2] ## Detailed Changes ### 1. [Change Category] **Before:** [Description of current state] **After:** [Description of improvement] **Rationale:** [Why this change helps users] ### 2. [Change Category] ... ## Why These Changes? According to Claude Code best practices: > "[Quote from documentation]" This PR addresses: - [Issue 1 and how it's fixed] - [Issue 2 and how it's fixed] ## Files Changed | File | Change Type | Description | |------|-------------|-------------| | SKI