skill-quality

What this skill does

# Skill Quality Validation

Ensures Claude Code skills follow best practices for discoverability, structure, content quality, and effectiveness. This skill provides checklists, patterns, and validation criteria for creating high-quality skills.

## When to Use This Skill

Use this skill when you see these patterns:

### ✅ Yes, use this skill for:

- "Create a new skill for [topic]"
- "Review this skill for quality"
- "Why isn't my skill being invoked?"
- "Improve this skill's structure"
- "Prepare this skill for sharing"
- "Debug skill invocation issues"
- "Make this skill more effective"

### ❌ No, use different skills for:

- Writing skill content (use topic-specific skills)
- Testing specific functionality (use testing skills)
- Code review (use code-review skills)

## Quick Reference

### Core Principles

**Every skill must have:**

- ✅ Specific description with trigger keywords (< 100 chars)
- ✅ Under 500 lines (split into directory if longer)
- ✅ Concrete examples (not abstract)
- ✅ Consistent terminology
- ✅ Progressive disclosure (most important first)

**Red flags:**

- ❌ Vague description like "Help with Python"
- ❌ Single file over 500 lines
- ❌ Abstract guidance without examples
- ❌ Mixing terminology (e.g., "commit" and "change" without explanation)
- ❌ Time-sensitive info (e.g., "new tool just released")

### Quality Checklist Workflow

When creating or reviewing a skill, copy this checklist and follow the steps:

```
Skill Quality Review Progress:
- [ ] Step 1: Verify description and metadata
- [ ] Step 2: Check structure and organization
- [ ] Step 3: Validate content quality
- [ ] Step 4: Review code and scripts (if applicable)
- [ ] Step 5: Test across models
- [ ] Step 6: Perform real usage testing
```

#### Step 1: Verify Description and Metadata

Check the YAML frontmatter:

- [ ] Description includes specific trigger keywords (what users will say)
- [ ] Description explains WHAT the skill does and WHEN to use it
- [ ] Description is in third person ("Validates...", not "Apply...")
- [ ] Description under 1024 characters
- [ ] Priority is set appropriately (5-7 for most skills)
- [ ] Name uses lowercase, hyphens, no reserved words

**If checks fail:** Update frontmatter before proceeding.

#### Step 2: Check Structure and Organization

Review file organization:

- [ ] SKILL.md is under 500 lines
- [ ] Uses directory structure if over 500 lines
- [ ] "When to Use This Skill" section exists and is clear
- [ ] Progressive disclosure: most important content first
- [ ] Headers are descriptive and scannable
- [ ] File references are one level deep maximum

**If checks fail:** Reorganize content or split into supporting files.

#### Step 3: Validate Content Quality

Review the skill content:

- [ ] Examples are concrete and copy-pasteable
- [ ] All code examples are runnable
- [ ] Terminology is consistent throughout
- [ ] No time-sensitive information (or properly isolated)
- [ ] Workflows have clear numbered steps
- [ ] Decision trees for complex choices
- [ ] All placeholders are explained or replaced

**If checks fail:** Add missing examples or clarify instructions.

#### Step 4: Review Code and Scripts

If skill includes executable code:

- [ ] Scripts solve problems (don't punt to Claude)
- [ ] Error handling is explicit with helpful messages
- [ ] All constants are justified (no "voodoo constants")
- [ ] Dependencies are listed with install instructions
- [ ] Paths use forward slashes (not backslashes)
- [ ] Validation/feedback loops for critical operations

**If checks fail:** Improve error handling and documentation.

#### Step 5: Test Across Models

Test with all Claude models:

- [ ] Tested with Haiku (simple case works)
- [ ] Tested with Sonnet (moderate complexity works)
- [ ] Tested with Opus (complex case works)
- [ ] Skill invoked correctly in all cases
- [ ] Responses follow skill guidance consistently

**If checks fail:** Adjust description or add more explicit guidance.

#### Step 6: Perform Real Usage Testing

Test in actual workflows:

- [ ] Fresh start test (new project, no external docs)
- [ ] Colleague test (someone else uses it)
- [ ] Different project test (verify it's project-agnostic)
- [ ] Error path test (intentionally trigger failures)

**If checks fail:** Update skill based on observed issues.

## File Structure

**For skills under 500 lines:**

```
my-skill.md                # Single file
```

**For skills over 500 lines:**

```
my-skill/
├── SKILL.md              # Main instructions (< 500 lines)
├── examples.md           # Detailed examples
├── reference.md          # API/command reference (optional)
└── scripts/              # Helper scripts (optional)
    └── validate.py
```

**Key principles:**

- SKILL.md always under 500 lines
- Related files use UPPERCASE for visibility (FORMS.md, EXAMPLES.md)
- Scripts in subdirectory, executed not loaded as context
- Each file has single, clear purpose

**Example from real skill:**

```
pdf/
├── SKILL.md              # Core PDF guidance
├── FORMS.md              # Form-filling specific guidance
├── examples.md           # Extended examples
└── scripts/
    ├── analyze_form.py   # Utility script
    └── fill_form.py      # Form processor
```

## Core Quality Standards

### 1. Description Quality

**Format:** Frontmatter YAML at top of SKILL.md

```yaml
---
description: "Specific action + key terms + when to use"
priority: 5
---
```

**Requirements:**

- Include key terms that trigger the skill
- Explain both WHAT and WHEN
- Keep under 100 characters
- Use terms users naturally say

📖 See [EXAMPLES.md](./EXAMPLES.md#description-quality) for good/bad examples

### 2. Content Structure

**SKILL.md must be:**

- Under 500 lines total
- Well-organized with clear sections
- Using progressive disclosure
- Focused on one coherent topic

**If exceeding 500 lines:**

1. Split into directory structure
2. Keep core guidance in SKILL.md
3. Move detailed examples to examples.md
4. Move reference material to reference.md
5. Move scripts to scripts/ subdirectory

**Progressive disclosure pattern:**

```markdown
# Skill Name

Brief intro (1-2 sentences)

## When to Use

Quick bullet list

## Quick Reference

Most common cases with examples

## Detailed Guidance

(Or link to examples.md)

## Advanced Patterns

(Or link to patterns.md)
```

### 3. Terminology Consistency

**Rules:**

- Use consistent terms throughout all files
- Establish vocabulary early
- Explain synonyms when first used
- Don't mix related terms without explanation

📖 See [EXAMPLES.md](./EXAMPLES.md#terminology-consistency) for patterns

### 4. Concrete Examples

**Every pattern needs a real, runnable example.**

Examples must:

- Be copy-pasteable
- Show actual code/commands
- Include expected output
- Demonstrate the principle

📖 See [EXAMPLES.md](./EXAMPLES.md#concrete-examples) for good/bad examples

### 5. File Reference Depth

**Keep references one level deep:**

```markdown
See examples.md for detailed patterns # ✅ Good
```

```markdown
See examples.md which references patterns.md
which has code in scripts/ # ❌ Bad - too deep
```

### 6. Time-Sensitive Information

**Isolate or avoid time-sensitive content:**

```markdown
## Current Best Practice (as of 2024)

Use ast-grep for syntax-aware searches

## Legacy Patterns

Previously, ripgrep was used...
```

📖 See [EXAMPLES.md](./EXAMPLES.md#time-sensitive-information) for deprecation patterns

## Code and Script Quality

### Scripts Should Solve Problems

**Don't punt to Claude - solve the problem in the script:**

- ✅ Validate and return specific errors
- ✅ Handle edge cases explicitly
- ✅ Provide actionable error messages
- ❌ Leave TODOs for Claude to figure out
- ❌ Generic "check this" functions

### Error Handling

**Every error path needs helpful messages:**

```python
except FileNotFoundError:
    print("Error: jj not found. Install with: brew install jj")
    sys.exit(1)
```

### No Voodoo Constants

**Justify all magic numbers:**

```python