Skill Reviewer

Reviews skill files against Claude Code best practices.

Target: $ARGUMENTS (path to skill file or directory)

When to Use

Use when:

• Creating new skills to validate best practices
• Reviewing existing skills for improvements
• Auditing before publication
• Debugging unexpected skill behavior
• Ensuring context efficiency

Review Checklist

Metadata

Required frontmatter:

• name (kebab-case, descriptive)
• description (when to use, not just what)
• disable-model-invocation: true for workflows with side effects
• aliases for common alternative names

Quality:

• Description: 1-2 sentences
• Name: specific yet broadly applicable

Structure

Organization:

• Clear sections with descriptive headers
• Consistent markdown formatting
• Examples where applicable
• “When to Use” section for context

Context efficiency:

• Concise – only essential information
• No redundant explanations
• Bullet points for scannability
• Links to docs vs duplicating them
• No filler content

Workflow Skills (Invokable)

For skills invoked with /skill-name:

• Uses disable-model-invocation: true
• Numbered steps or phases
• Actionable, specific steps
• Verification/validation steps
• Uses $ARGUMENTS if accepts parameters
• Logical step ordering
• Error handling or fallback guidance
• Clear when to ask user vs proceed autonomously
• Clear success criteria

Knowledge Skills (Auto-Applied)

For skills Claude applies automatically:

• Domain knowledge Claude can’t infer
• Patterns, conventions, architectural guidance
• Code examples with language tags
• Organized by topic/use case
• Focused scope (narrow > kitchen-sink)
• Not duplicating CLAUDE.md content
• Provides guidance, not rigid instructions

Tool Usage

• Recommends right tool (Read vs bash cat)
• Suggests parallel calls when appropriate
• Uses subagents for context-heavy exploration
• Avoids unnecessary tool use

Context-saving patterns:

• Focused searches over broad exploration
• Filter/scope before reading large files
• Subagents for investigation
• Suggests /clear when context cluttered

Verification

• Steps for Claude to verify work
• Defines success criteria
• Recommends tests, linters, validation
• Addresses root causes, not symptoms
• Prompts for confirmation on destructive actions
• Asks clarifying questions when ambiguous
• Progress updates for long tasks

Code Examples

If included:

• Correct syntax highlighting
• Shows BAD and GOOD patterns when relevant
• Comments for non-obvious code
• Complete and runnable (not pseudocode)
• Realistic examples (not toy examples)

Anti-Patterns to Avoid

Content:

• ❌ Too long (>500 lines)
• ❌ Too vague (generic advice)
• ❌ Too rigid (constrains creativity)
• ❌ Duplicates CLAUDE.md
• ❌ Over-engineered

Workflow:

• ❌ No verification steps
• ❌ Assumes context
• ❌ Unclear scope
• ❌ Missing error handling
• ❌ No user interaction on destructive actions

Language & Tone

Principles:

• Imperative voice (“Run tests” not “You should run tests”)
• Concise and direct
• Precise terminology
• Active voice preferred
• One idea per sentence
• No unnecessary adjectives/superlatives
• Professional, objective tone
• No emojis (unless domain-specific)

Eliminate verbosity:

• “In order to” → “To”
• “It is important to note that” → (delete)
• “You should” / “You need to” → imperative
• “Please note that” → (delete)
• “Going forward” / “Moving forward” → (delete)
• “At this point in time” → “Now” or (delete)
• “For the purpose of” → “To” or “For”
• “With regard to” → “About” or “Regarding”

Maintenance

• Version-agnostic (no specific tool versions)
• Links to official docs for evolving refs
• Dates for time-sensitive information
• Can update incrementally

Technical Writing Principles

Precision Over Description

BAD: “Make sure your code is well-organized and follows good practices”
GOOD: “Use dependency injection. Limit functions to 50 lines.”

Eliminate Filler

Common filler: “basically”, “essentially”, “generally”, “typically”, “very”, “really”, “quite”, “actually”, “kind of”, “sort of”, “simply”, “just”

BAD: “You should basically just run the tests to make sure everything is actually working correctly”
GOOD: “Run tests to verify functionality”

Use Concrete Numbers

BAD: “Keep functions small and avoid deeply nested code”
GOOD: “Limit functions to 50 lines. Limit nesting to 3 levels.”

Active Voice

BAD: “The configuration should be validated before the application is started”
GOOD: “Validate configuration before starting the application”

Front-Load Important Info

BAD: “When you’re working with user input, which could potentially contain malicious data, it’s important to remember that you should always validate and sanitize it”
GOOD: “Always validate and sanitize user input”

Parallel Structure

BAD:

• Check that the file exists
• Making sure permissions are correct
• You should verify the contents

GOOD:

• Check file exists
• Verify permissions
• Validate contents

Delete Hedge Words

BAD: “This might help improve performance somewhat”
GOOD: “This improves performance by 30%” or “This may improve performance. Benchmark to verify.”

Review Process

1. Read skill at $ARGUMENTS
2. Check frontmatter for required fields
3. Evaluate context efficiency
4. Apply technical writing check
5. Verify structure and flow
6. Test code examples
7. Check for anti-patterns
8. Assess scope
9. Validate verification steps

Output Format

## Skill Review: [skill-name]

### Summary
[1-2 sentence overview]

### Strengths
- [What works well]
- [Effective patterns]

### Issues Found

#### Critical (Must Fix)
- [ ] [Issue] - Location: [section/line]

#### Recommendations (Should Fix)
- [ ] [Recommendation] - Location: [section/line]

#### Suggestions (Nice to Have)
- [ ] [Suggestion] - Location: [section/line]

### Context Efficiency Score
[1-5]: [Brief explanation]
- 5: Extremely concise, every word necessary
- 4: Mostly efficient, minor verbosity
- 3: Acceptable, some trimming needed
- 2: Verbose, significant trimming needed
- 1: Bloated, major revision required

### Technical Writing Quality
[1-5]: [Brief explanation]
- 5: Precise, concise, active voice, no filler
- 4: Mostly clear, minor improvements
- 3: Acceptable, some verbosity/vagueness
- 2: Significant clarity issues, passive voice, filler
- 1: Unclear, verbose, imprecise

### Overall Assessment
[Pass/Pass with Recommendations/Needs Revision]

### Specific Improvements
```diff
[Show diffs for suggested changes]

## Common Skill Smells

### The Encyclopedia
**Symptom:** Exhaustive domain coverage  
**Fix:** Break into focused skills or link to docs

### The CLAUDE.md Duplicate
**Symptom:** Project-specific conventions  
**Fix:** Move to CLAUDE.md, keep domain knowledge in skill

### The Vague Guide
**Symptom:** Generic advice ("write clean code")  
**Fix:** Provide specific, actionable guidance

### The Context Hog
**Symptom:** 1000+ lines, auto-loaded  
**Fix:** Compress, split, or make invokable-only

### The Rigid Workflow
**Symptom:** Overly prescriptive steps  
**Fix:** Provide guidance and checkpoints, allow adaptation

### The Missing Verification
**Symptom:** Implementation without validation  
**Fix:** Add verification steps, success criteria, tests

### The Assumption Maker
**Symptom:** "Update the config" (which file? where?)  
**Fix:** Explicit paths, patterns, or discovery method

### The Verbose Writer
**Symptom:** Filler words, passive voice, redundancy  
**Fix:** Apply technical writing principles

## Examples

### Good Knowledge Skill

```markdown
---
name: api-conventions
description: REST API design conventions for our microservices
---

# API Conventions

## URL Structure
- Use kebab-case: `/api/v1/user-profiles`
- Version in path: `/v1/`, `/v2/`
- Collection naming: plural (`/users`, not `/user`)

## Request/Response
- camelCase for JSON properties
- ISO 8601 timestamps: `2024-01-15T10:30:00Z`
- Wrap lists: `{ "data": [...], "meta": { "total": 100 } }`

## Pagination
- Cursor-based for large datasets
- Include `next`, `prev` in meta
- Max 100 items per page

## Error Handling
- Use RFC 7807 Problem Details
- Include `type`, `title`, `status`, `detail`

Why it passes: Concise, focused, provides patterns Claude can’t infer, scannable, no prose.

Good Workflow Skill

---
name: fix-security-issue
description: Fix security vulnerability following our security workflow
disable-model-invocation: true
---

# Fix Security Issue

Fix security issue $ARGUMENTS following our security review process.

## Steps

1. **Analyze vulnerability**
   - `gh issue view $ARGUMENTS` to read security issue
   - Identify CWE category and severity
   - Understand attack vector

2. **Find affected code**
   - Search for vulnerable patterns using Grep
   - Check for similar instances elsewhere
   - Review history: `git log -p --grep="$PATTERN"`

3. **Implement fix**
   - Address root cause, not symptoms
   - Follow secure patterns from `.claude/skills/security-patterns/`
   - Update all affected locations

4. **Write security tests**
   - Test reproduces vulnerability
   - Verify test fails on old code
   - Verify test passes on fixed code
   - Add edge case tests

5. **Validate fix**
   - `npm test`
   - `npm run security-scan`
   - `npm run lint`

6. **Document and commit**
   - Add security comment explaining fix
   - `security: fix [CWE-XXX] in [component]`
   - Reference issue: `Fixes #$ARGUMENTS`

7. **Create PR**
   - `gh pr create --template security`
   - Request @security-team review
   - Add `security` label

## Verification

- [ ] Security test added and passing
- [ ] All tests passing
- [ ] Security scanner clean
- [ ] Similar patterns checked
- [ ] Security team assigned

Why it passes: Clear workflow, disable-model-invocation: true, verification checklist, exact commands, success criteria, uses $ARGUMENTS.

Problematic Skill

---
name: make-code-better
description: Improves code quality
---

# Code Improvement Guide

This skill helps you write better, cleaner, more maintainable code.

## General Principles

Always write clean code that is easy to read. Make sure your code 
follows best practices. Remember that code is read more often than 
it's written.

## Things to Consider

- Make your code modular
- Add appropriate comments
- Follow DRY principle
- Use meaningful names
- Keep functions small
- Write tests
- Handle errors
- Optimize performance
- Make it scalable
- Consider security

Why it fails:

• Too vague (generic advice)
• No actionable steps
• Missing disable-model-invocation flag
• Bloated prose
• No verification
• No examples
• Unclear when to use

Fix: Split into focused skills (security-patterns, testing-patterns), provide examples, add verification, make context-efficient.

Technical Writing Improvement

BEFORE (verbose):

## Error Handling

When working with API calls, it's important to handle errors properly. 
You should catch exceptions and log them so you can debug issues later. 
It's also a good idea to provide meaningful error messages.

AFTER (concise):

## Error Handling

- Catch all exceptions
- Log to monitoring (Sentry, Datadog)
- Return user-friendly messages (hide stack traces)

```javascript
try {
  await api.call()
} catch (error) {
  logger.error('API failed', { error, context })
  throw new UserError('Unable to process request')
}

**Improvements:** Eliminated filler, active voice, specific tools, added code, 60% shorter with more info.

## References

Based on Claude Code best practices:
- https://code.claude.com/docs/en/best-practices
- https://code.claude.com/docs/en/skills
- https://code.claude.com/docs/en/how-claude-code-works

## Usage

/skill-reviewer path/to/SKILL.md