skill-reviewer-and-enhancer

What this skill does

# Skill Reviewer and Enhancer

Review, audit, and enhance existing Claude Code skills to ensure they follow Anthropic best practices and current domain-specific patterns.

## Overview

To improve skill quality and ensure adherence to official standards, this skill performs comprehensive analysis of existing skills, identifies structural issues, verifies domain-specific best practices, and automatically applies improvements.

## When to Use This Skill

Apply this skill when:
- Reviewing an existing skill for quality and compliance
- Auditing skills before deployment to production
- Updating skills to follow latest Anthropic guidelines
- Ensuring skills use current framework/library patterns
- Identifying missing resources or incomplete implementations
- Enhancing skill descriptions for better discoverability
- Fixing structural or formatting issues
- Modernizing outdated skill instructions

## Step 1: Locate and Read the Skill

To begin the review process:

1. Ask user for the skill path or name if not provided
2. Verify the skill directory exists
3. Read the SKILL.md file completely
4. Note the skill's category and purpose

```bash
# Find skill
ls skills/[category]/[skill-name]/SKILL.md

# Read skill
Read: skills/[category]/[skill-name]/SKILL.md
```

## Step 2: Analyze Skill Structure

To verify proper skill structure, check for:

### Frontmatter Validation

**Required Fields:**
- `name`: Must be present, hyphen-case, no angle brackets
- `description`: Must be present, third-person voice, includes trigger terms, under 1024 characters

**Optional Fields:**
- `allowed-tools`: Present for read-only/analysis skills

**Validation Script:**
```bash
python scripts/analyze_skill_structure.py --skill skills/[category]/[skill-name]
```

### Name Convention Check

Verify name follows hyphen-case:
- [OK] Correct: `skill-reviewer-and-enhancer`, `nextjs-fullstack-scaffold`
- [WRONG] Incorrect: `SkillReviewer`, `skill_reviewer`, `skillReviewer`

Check for invalid patterns:
- Starts or ends with hyphen
- Contains consecutive hyphens (`--`)
- Contains uppercase letters
- Contains underscores or other special characters

### Description Quality Check

Verify description:
- **Voice**: Uses third-person ("This skill should be used when...")
- **Content**: Explains WHAT it does and WHEN to use it
- **Trigger Terms**: Includes specific keywords users would search for
- **Length**: Under 1024 characters
- **Format**: No angle brackets, proper grammar

## Step 3: Review Instruction Style

To verify proper instruction format, scan the SKILL.md body for:

### Imperative Form Check

Instructions should use imperative/infinitive form:
- [OK] Correct: "To create a form, use the generator script"
- [OK] Correct: "Generate schemas using the Zod validator"
- [WRONG] Incorrect: "You should create forms using the generator"
- [WRONG] Incorrect: "You can generate schemas with Zod"

Use Grep to find second-person usage:
```bash
Grep: pattern="\\b[Yy]ou\\b" path="skills/[category]/[skill-name]/SKILL.md" output_mode="content"
```

Flag any instances for correction.

### Section Structure Check

Verify logical organization:
- Overview/Introduction
- When to Use (optional but recommended)
- Prerequisites (if applicable)
- Step-by-step implementation
- Resource references (scripts, references, assets)
- Best practices
- Troubleshooting (optional)

## Step 4: Verify Domain-Specific Best Practices

To ensure the skill follows current best practices for its domain, consult the appropriate reference:

### Development Skills
For Next.js, React, TypeScript, database skills, check:
- Uses latest framework versions (Next.js 15/16, React 19)
- Follows Server Components patterns
- Uses App Router (not Pages Router)
- Implements proper TypeScript types
- Uses modern tooling (Vite, Vitest, ESM)

Consult `references/nextjs-best-practices.md` for detailed checks.

### Testing Skills
For testing-related skills, check:
- Uses modern test runners (Vitest, not Jest)
- Uses Testing Library patterns
- Implements accessibility testing
- Follows AAA pattern (Arrange, Act, Assert)
- Uses proper mocking strategies

Consult `references/testing-best-practices.md` for detailed checks.

### UI Component Skills
For UI and component skills, check:
- Uses shadcn/ui patterns correctly
- Implements accessibility (ARIA, semantic HTML)
- Follows Tailwind CSS conventions
- Uses proper composition patterns
- Implements dark mode support

Consult `references/ui-best-practices.md` for detailed checks.

### Database Skills
For database and ORM skills, check:
- Uses Prisma 5+ patterns
- Implements proper connection pooling
- Uses prepared statements/parameterized queries
- Implements RLS for Supabase
- Uses proper migration patterns

Consult `references/database-best-practices.md` for detailed checks.

### Security Skills
For security-related skills, check:
- Follows OWASP guidelines
- Implements proper authentication patterns
- Uses secure session management
- Implements CSRF protection
- Uses Content Security Policy
- Validates and sanitizes inputs

Consult `references/security-best-practices.md` for detailed checks.

## Step 5: Check Resource References

To verify bundled resources are properly referenced:

### Scripts Directory
Check if skill references scripts and whether they exist:
```bash
Grep: pattern="scripts/" path="skills/[category]/[skill-name]/SKILL.md" output_mode="content"
Glob: pattern="skills/[category]/[skill-name]/scripts/*"
```

Verify:
- Scripts mentioned in SKILL.md exist in scripts/ directory
- Scripts have proper documentation
- Scripts are executable (Python/Bash)
- Usage examples are provided

### References Directory
Check if skill references documentation:
```bash
Grep: pattern="references/" path="skills/[category]/[skill-name]/SKILL.md" output_mode="content"
Glob: pattern="skills/[category]/[skill-name]/references/*"
```

Verify:
- References mentioned exist
- Large documents (>5k words) use grep patterns for selective loading
- References are up-to-date with current practices

### Assets Directory
Check if skill references templates or output files:
```bash
Grep: pattern="assets/" path="skills/[category]/[skill-name]/SKILL.md" output_mode="content"
Glob: pattern="skills/[category]/[skill-name]/assets/*"
```

Verify:
- Assets mentioned exist
- Templates are properly formatted
- File names are descriptive

## Step 6: Generate Improvement Report

To create a comprehensive review report, use the template from `assets/review-report-template.md`:

```markdown
# Skill Review Report: [Skill Name]

**Skill Path:** skills/[category]/[skill-name]
**Review Date:** [Date]
**Reviewer:** Claude Code (skill-reviewer-and-enhancer)

## Overall Assessment

**Grade:** [A/B/C/D/F]
**Status:** [Production Ready / Needs Minor Fixes / Needs Major Revision]

## Structural Compliance

### Frontmatter
- [x] Name present and valid
- [x] Description present and well-formatted
- [ ] allowed-tools specified (if applicable)

### Naming Convention
- [x] Uses hyphen-case
- [ ] Issue: Contains uppercase/invalid characters

### Description Quality
- [x] Third-person voice
- [x] Includes trigger terms
- [x] Under 1024 characters
- [ ] Issue: Missing WHEN to use explanation

## Instruction Style

### Imperative Form
- [x] Uses verb-first instructions
- [ ] Issue: Found 5 instances of "you should" (lines: 45, 67, 89, 102, 134)

**Recommended Changes:**
```
Line 45: "You should use the script" → "Use the script"
Line 67: "You can generate forms" → "Generate forms" or "To generate forms"
```

## Domain-Specific Best Practices

### [Domain] Patterns
- [x] Uses current framework version
- [x] Follows recommended patterns
- [ ] Issue: References deprecated API (NextAuth v3, should use v5)
- [ ] Issue: Uses Pages Router patterns (should use App Router)

**Recommended Updates:**
[Specific suggestions for domain improvements]

## Resource Completeness

### Scripts
- [ ] Script `generate_form.py` mentioned but not found
- [x] Script `validate_s