Skill Reviewer

Skill Reviewer

Review and improve Claude Code skills against official best practices.

Setup (Auto-Install Dependencies)

Before using this skill, ensure skill-creator is installed for automated validation.

Auto-install sequence:

# 1. Check if skill-creator exists
SKILL_CREATOR=$(find ~/.claude/plugins/cache -name "skill-creator" -type d 2>/dev/null | head -1)

# 2. If not found, install it
if [ -z "$SKILL_CREATOR" ]; then
  claude plugin marketplace add https://github.com/daymade/claude-code-skills
  claude plugin install skill-creator@daymade-skills
  SKILL_CREATOR=$(find ~/.claude/plugins/cache -name "skill-creator" -type d 2>/dev/null | head -1)
fi

echo "skill-creator location: $SKILL_CREATOR"

Three Modes

Mode 1: Self-Review

Check your own skill before publishing.

Automated validation (run after setup):

# Quick validation
python3 "$SKILL_CREATOR"/*/quick_validate.py <target-skill>

# Security scan
python3 "$SKILL_CREATOR"/*/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)

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. Ensure marketplace-dev is available (auto-install it if missing), then follow its workflow and references/cache_and_source_patterns.md.

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

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:

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

• 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

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

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

## 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 |
|------|-------------|-------------|
| SKILL.md | Modified | Improved description and workflow |
| README.md | Modified | Added installation instructions |
| README.en.md | Added | English documentation |
| .claude-plugin/marketplace.json | Added | Plugin marketplace support |

## Test Plan

- [ ] Test 1
- [ ] Test 2
- [ ] Test 3

## References

- [Claude Code Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [Skills Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Key Sections Explained

Summary

• Brief overview (2-3 sentences)
• Link to best practices

What This PR Does NOT Change

CRITICAL - Always include this section to show respect for original work.

Rationale

• Explain WHY each change helps
• Quote official documentation
• Don't be judgmental

Test Plan

• Provide actionable verification steps
• Help maintainers review quickly

Tone Guidelines

Do

• Be helpful and constructive
• Explain benefits to users
• Acknowledge good aspects of original

Don't

• Be critical or judgmental
• Imply the original is "wrong"
• Use words like "fix", "correct", "proper" negatively

Examples

❌ "Fixed the incorrect description format"
✅ "Improved description for better skill discovery"

❌ "The skill had several issues..."
✅ "This PR adds improvements for..."

❌ "Corrected the non-standard structure"
✅ "Added marketplace support for easier installation"