Validate Skill

Validate a custom skill's SKILL.md file for correct structure and format.

Usage

/validate-skill <skill-name|path>

Parameters

• skill-name: Name of skill in skills/ directory
• path: Direct path to SKILL.md file

Validation Checks

1. YAML Frontmatter

• Has valid YAML frontmatter (between --- markers)
• Contains name field
• Contains description field
• Description uses WHEN/WHAT/WHEN NOT format

2. Required Sections

• Has # [Skill Name] Skill heading
• Has ## Purpose section
• Has ## When to Use section
• Has ## Workflow section

3. Description Format

• WHEN: Describes trigger conditions
• WHAT: Lists capabilities
• WHEN NOT: Specifies exclusions

4. Content Quality

• Has code examples
• Has detection rules table
• Has response template
• Has integration section

Output Format

Valid Skill:

## Skill Validation: my-custom-skill

**Status**: ✓ VALID

### Frontmatter
- [x] Valid YAML syntax
- [x] name: my-custom-skill
- [x] description: WHEN/WHAT/WHEN NOT format ✓

### Required Sections
- [x] Purpose
- [x] When to Use
- [x] Workflow
- [x] Detection Rules

### Content Quality
- [x] Code examples present
- [x] Response template defined
- [x] Integration references

**Result**: Skill is ready for use.

Invalid Skill:

## Skill Validation: my-custom-skill

**Status**: ✗ INVALID

### Errors (3)

1. **Missing WHEN NOT in description**
   Line 3: description field should include "WHEN NOT:" clause
   ```yaml
   description: |
     WHEN: ...
     WHAT: ...
     WHEN NOT: ...  # Missing!

2. Missing Workflow section Expected ## Workflow heading not found

3. No code examples Skill should include code examples in detection rules

Warnings (1)

1. No Response Template Consider adding a response template for consistent output

Result: Fix 3 errors before using this skill.

## Example Validations

### Validate by Name

/validate-skill fastapi-reviewer

### Validate by Path

/validate-skill ./my-skills/custom-reviewer/SKILL.md

### Validate All Skills

/validate-skill --all

## Creating Valid Skills

### Minimum Valid Structure
```markdown
---
name: my-skill
description: |
  WHEN: Trigger conditions
  WHAT: Capabilities
  WHEN NOT: Exclusions
---

# My Skill

## Purpose
Brief description of what this skill does.

## When to Use
- Condition 1
- Condition 2

## Workflow

### Step 1: Analyze
Description of first step.

## Detection Rules
| Check | Recommendation | Severity |
|-------|----------------|----------|
| Issue | Fix | HIGH |

## Response Template

Results

...

## Integration
- Related skill 1
- Related skill 2

Notes

• Run validation before deploying custom skills
• Fix all errors; warnings are optional
• Use --verbose for detailed syntax checking