name: skill-reviewer
description: Reviews and validates Claude Code skill definitions for best practices, non-overlapping domains, and correct configuration. Use when creating new skills, reviewing existing skills, checking for conflicts, or validating skill quality.
allowed-tools: Read, Glob, Grep

Skill Reviewer

Validates Claude Code skills for the Kubernetes Cell Platform project.

Validation Checklist

1. Frontmatter Validation

• [ ] name is kebab-case
• [ ] name is ≤64 characters
• [ ] description is ≤1024 characters
• [ ] description includes trigger keywords
• [ ] description describes WHAT and WHEN to use
• [ ] allowed-tools matches execution mode

2. Content Validation

• [ ] SKILL.md is <500 lines
• [ ] Clear step-by-step instructions
• [ ] Memory file paths are correct
• [ ] Reference docs exist if linked
• [ ] Scripts exist and are executable

3. Non-Overlap Verification

Each skill must have a clear, non-overlapping domain:

4. Execution Mode Check

Review Process

Step 1: Parse Frontmatter

# Extract frontmatter from SKILL.md
head -20 .claude/skills/<skill-name>/SKILL.md

Step 2: Check for Overlaps

Compare trigger keywords across all skills:

# List all skill descriptions
for skill in .claude/skills/*/SKILL.md; do
  echo "=== $skill ==="
  grep "^description:" "$skill"
done

Step 3: Validate References

# Check if referenced files exist
grep -E "reference/|scripts/" .claude/skills/<skill-name>/SKILL.md | while read ref; do
  # Verify file exists
done

Step 4: Line Count

wc -l .claude/skills/*/SKILL.md

Best Practices

Description Writing

Good:

description: Manages Talos Linux and Terraform infrastructure layer (L0). Use for terraform operations, talos cluster management, node provisioning, or cluster bootstrap.

Bad:

description: Helps with infrastructure  # Too vague

Tool Restrictions

# Read-only skill
allowed-tools: Read, Glob, Grep, Bash(kubectl:get,describe,logs)

# Tiered skill (some ops need approval)
allowed-tools: Read, Glob, Grep, Bash(kubectl:*, terraform:*)

Progressive Disclosure

SKILL.md           # Quick reference (<500 lines)
├── reference/     # Detailed docs (loaded on demand)
└── scripts/       # Utilities (executed, not read)

Reference Documentation

• reference/skill-checklist.md - Detailed validation steps
• reference/best-practices.md - Skill authoring guide

Common Issues