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

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)

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

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