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:

Sandbox skills (auto-approved)

Commands target localtest.me, KUBECONFIG=~/clusters/hcp/kagenti-hypershift-custom-*, or Kind clusters.

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 kagenti-system

Check logs:

kubectl logs -n kagenti-system deployment/mlflow

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

kubectl get pods -n kagenti-system && kubectl logs -n kagenti-system deployment/mlflow

### 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 -n ' && ' .claude/skills/k8s:*/SKILL.md .claude/skills/kagenti:*/SKILL.md .claude/skills/kind:*/SKILL.md .claude/skills/local:*/SKILL.md .claude/skills/tdd:*/SKILL.md .claude/skills/rca:*/SKILL.md

Check Mermaid Diagram Presence

for f in .claude/skills/*/SKILL.md; do
  dir=$(basename $(dirname "$f"))
  case "$dir" in git|k8s|auth|openshift|local|kind|helm|meta|genai|repo|testing) 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:

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

Task Tracking

When validating multiple skills:

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

Related Skills

• skills:write - Create new skills following the standard
• skills:retrospective - Review session to identify skill improvements