013 Consistency Rules B401e77c

# Consistency Rules Reference

Detailed validation rules for ensuring skill quality and consistency.

## Frontmatter Validation

### Required Fields
- **name**: Must be present and non-empty
  - Format: lowercase with hyphens (e.g., `skill-name`)
  - No spaces or underscores
  - Example: `pdf-editor` ✅, `PDF Editor` ❌, `pdf_editor` ❌

- **description**: Must be present and non-empty
  - Minimum length: 50 characters (warning if shorter)
  - Maximum length: 500 characters (info if longer)
  - Must start with capital letter
  - Should include trigger phrases (`when`, `use`)

### Optional But Recommended
- **license**: Legal terms reference
- **version**: Semantic versioning

## Description Quality

### Content Requirements
1. **Specificity**: Avoid vague terms
   - ❌ "various tasks"
   - ✅ "spreadsheet formulas and data visualization"

2. **Trigger Clarity**: Include when/how to use
   - ❌ "Helps with documents"
   - ✅ "When Claude needs to create, edit, or review .docx files"

3. **Completeness**: Cover key capabilities
   - What does it do?
   - When should it be used?
   - What are the main features?

### Length Guidelines
- **Too short** (<50 chars): Missing essential details
- **Ideal** (50-200 chars): Concise and complete
- **Good** (200-500 chars): Comprehensive
- **Too long** (>500 chars): May need editing for clarity

## Structure Validation

### Body Length
- **Minimum**: 100 characters (warning if less)
- **Maximum**: 500 lines (warning if more - suggests need for references/)

### Expected Sections
While not strictly required, skills typically benefit from:
- **Overview/About**: Introduction to the skill
- **Workflow/Usage**: How to use it
- **Examples**: Concrete demonstrations

### Resource Organization
- Scripts in `scripts/`
- Documentation in `references/`
- Templates/assets in `assets/`
- All resources should be referenced in SKILL.md

## Terminology Standards

### Writing Style
- Use imperative/infinitive form
  - ✅ "Use this script to rotate PDFs"
  - ❌ "You should use this script to rotate PDFs"

- Be direct and action-oriented
  - ✅ "Run analyze.py to extract metadata"
  - ❌ "You can run analyze.py if you want to extract metadata"

### Consistency
- **Claude**: Always capitalize (it's a proper noun)
- **SKILL.md**: All caps for the filename
- **skill**: Lowercase when referring to the concept

### Avoid Second Person
- ❌ "You should", "You can", "You must"
- ✅ "Use", "Run", "Create", "Execute"

## Resource Validation

### Referenced Resources
All bundled resources should be mentioned in SKILL.md:
- Scripts should be referenced by name or path
- Reference files should be linked in context
- Assets should be mentioned where applicable

### Unreferenced Resources (Warning)
If a resource exists but isn't mentioned, it may be:
- Dead code/docs that should be removed
- Important but forgotten in documentation

## Code Examples

### Best Practices
- Always include language tags: ` ```python` not ` ``` `
- Keep examples concise and focused
- Ensure examples are complete and runnable
- Provide context for what the example demonstrates

### Quantity
- No examples: INFO (consider adding if helpful)
- 1-5 examples: Ideal range
- 5+ examples: Consider moving to references/

## Error Severity Levels

### ERROR
Violations that prevent skill from working correctly:
- Missing required frontmatter fields
- Empty required fields
- Critical structural issues

### WARNING
Issues that affect quality but don't break functionality:
- Naming convention violations
- Short descriptions
- Unreferenced resources
- Excessive length (>500 lines)

### INFO
Suggestions for improvement:
- Stylistic recommendations
- Missing optional sections
- Terminology suggestions
- Code example language tags

## Validation Checklist

When validating a skill, check:

- [ ] Frontmatter has required fields
- [ ] Name follows naming conventions
- [ ] Description is comprehensive and clear
- [ ] Body has reasonable length
- [ ] Key sections are present
- [ ] Resources are properly referenced
- [ ] Code examples have language tags
- [ ] Terminology is consistent
- [ ] Style is imperative/infinitive