main

ValidateSkill Workflow

Validate a skill’s structure, naming, and compliance with conventions.

Steps

1. Read the Skill File

Read ~/.config/claude/skills/[skill-name]/SKILL.md

2. Check Directory Naming

  • ✓ Directory name is lowercase-with-hyphens (e.g., golang, not Golang)
  • ✓ Directory name matches YAML name field

3. Validate YAML Frontmatter

Required fields:

---
name: skill-name          # Must be lowercase-with-hyphens, matching directory
description: [What it does]. USE WHEN [intent triggers using OR]. [Additional capabilities].
---

Check:

  • ✓ name field exists and is lowercase-with-hyphens
  • ✓ description field exists and is single line
  • ✓ Description includes “USE WHEN” or clear triggers
  • ✓ No syntax errors in YAML

4. Validate Markdown Body

Required structure:

  1. ✓ H1 heading matching the skill name
  2. ✓ Brief overview paragraph
  3. ✓ “Workflow Routing” section (if workflows exist)
  4. ✓ “Examples” section with at least one example

5. Check Workflow Files

For each file in workflows/:

  • ✓ Uses TitleCase.md naming (e.g., Create.md)
  • ✓ Listed in Workflow Routing table
  • ✓ Has clear structure

6. Check Tool Files

For each file in tools/:

  • ✓ Uses kebab-case naming (e.g., generate-tool.sh)
  • ✓ Is executable (if shell script)

7. Generate Compliance Report

Output Format

Validating skill: [SkillName]

✓ Directory Structure
  ✓ Name is lowercase-with-hyphens: [skill-name]
  ✓ workflows/ directory exists
  ✓ tools/ directory exists

✓ SKILL.md Frontmatter
  ✓ name: [skill-name] (lowercase-with-hyphens)
  ✓ description: Single line with triggers

✓ SKILL.md Body
  ✓ H1 heading matches name
  ✓ Has overview section
  ✓ Has Workflow Routing table
  ✓ Has Examples section

✓ Workflows
  ✓ All workflow files use TitleCase.md
  ✓ All listed in routing table

Compliance: PASSED

[If issues found:]
❌ Issues Found:
  - [Issue 1 description]
  - [Issue 2 description]

Recommendations:
  - [How to fix issue 1]
  - [How to fix issue 2]

Failure Handling

If validation fails, suggest fixes:

  • Naming issues: Provide correct lowercase-with-hyphens names
  • Structure issues: Show required structure
  • Missing sections: Provide templates