skills-validate

name	skills:validate
description	Validate skill files meet the standard format and naming conventions

Validate Skill

When to Use

• After creating or editing a skill
• Before committing skill changes
• When auditing all skills for consistency

Validation Checks

Required

• Frontmatter: Has name: and description: fields
• Colon naming: name: uses colon notation (e.g., tdd:ci not tdd-ci)
• Directory match: Directory name matches frontmatter name: field
• Title: Has # Skill Name as first heading
• When to Use: Has "When to Use" or "Overview" section
• Related Skills: Has "Related Skills" section at the end
• Mermaid diagram: Workflow/router skills have an embedded mermaid diagram
• Diagram colors: classDef colors match README color legend

Command Format (Required)

• Sandbox classification: Skill is classified as sandbox or management (see below)
• Single commands: Sandbox skills use one command per code block (no && chaining)
• Auto-approve coverage: All commands in sandbox skills match a pattern in .claude/settings.json
• No multiline bash: Sandbox skills avoid heredocs, multiline pipes, or for loops in commands

Recommended

• TOC: Table of Contents present if skill > 50 lines
• Placeholders: All commands are copy-pasteable (no unexplained placeholders)
• Task tracking: TDD/RCA skills have "Task Tracking" section
• Parent ref: Parent category SKILL.md references this skill
• Imperative voice: Uses "Run X" not "You should run X"
• Length: Leaf skills are 80-200 lines (300 max)
• Diagram-text match: Diagram nodes correspond to textual flow steps

Sandbox vs Management Classification

Skills operate on either sandbox (safe) or management (requires approval) targets:

Type	Target	Auto-approve?	Command format
Sandbox	Local Kind cluster, custom HyperShift hosted cluster	YES	Single commands, one per step
Management	Management cluster, AWS resources, git push, destructive ops	NO	Can chain commands (user approves anyway)

Sandbox skills (auto-approved)

Commands target local Kind clusters or test environments.

IMPORTANT: Run each command separately — not chained with &&. Chained or multiline commands break Claude Code's auto-approve pattern matching.

## GOOD (each command runs separately, matches auto-approve patterns)

Check pod status:
```bash
kubectl get pods -n rossoctl-system

Check logs:

kubectl logs -n rossoctl-system deployment/rossoctl-operator-controller-manager

BAD (chained commands won't match auto-approve patterns)

kubectl get pods -n rossoctl-system && kubectl logs -n rossoctl-system deployment/rossoctl-operator-controller-manager

### Management skills (require approval)
Commands target management clusters, AWS APIs, or perform destructive operations. These can use any command format since the user must approve each one.

## How to Validate

### Single Skill

```bash
# Check frontmatter
head -5 .claude/skills/<skill>/SKILL.md

# Check name matches directory
DIR_NAME=$(basename $(dirname .claude/skills/<skill>/SKILL.md))
SKILL_NAME=$(grep '^name:' .claude/skills/<skill>/SKILL.md | sed 's/name: //')
[ "$DIR_NAME" = "$SKILL_NAME" ] && echo "OK" || echo "MISMATCH: dir=$DIR_NAME name=$SKILL_NAME"

All Skills

# Check all frontmatter name-vs-directory
for f in .claude/skills/*/SKILL.md; do
  dir=$(basename $(dirname "$f"))
  name=$(grep '^name:' "$f" | sed 's/name: //' | tr -d ' ')
  [ "$dir" = "$name" ] || echo "MISMATCH: $dir != $name"
done

Check Command Format (sandbox skills)

# Find chained commands in sandbox skills (potential auto-approve issues)
grep -rn ' && ' .claude/skills/*/SKILL.md

Check Mermaid Diagram Presence

for f in .claude/skills/*/SKILL.md; do
  dir=$(basename $(dirname "$f"))
  case "$dir" in git|k8s|skills) continue ;; esac
  if ! grep -q '```mermaid' "$f"; then
    echo "MISSING DIAGRAM: $dir"
  fi
done

Verify settings.json Coverage

For each command in a sandbox skill, verify it matches a pattern in .claude/settings.json:

Command prefix	settings.json pattern
kubectl get	Bash(kubectl get:*)
kubectl describe	Bash(kubectl describe:*)
kubectl logs	Bash(kubectl logs:*)
helm list	Bash(helm list:*)
go test	Bash(go test:*)
make test	Bash(make test:*)

If a command is NOT covered, add the pattern to .claude/settings.json in the allow array.

Task Tracking

When validating multiple skills:

TaskCreate: "main | skills | <category> | Verify | Validate <skill-name>"

Related Skills

• skills:write - Create new skills following the standard