# Skill Validation Checklist

Based on official Claude Code documentation: https://code.claude.com/docs/en/skills

## Required

- [ ] `SKILL.md` exists in skill directory
- [ ] Frontmatter contains `name` (lowercase, max 64 chars)
- [ ] Frontmatter contains `description` (non-empty, describes when to use)

## Recommended

- [ ] `description` uses natural language keywords for auto-detection
- [ ] `argument-hint` present if skill accepts arguments
- [ ] `disable-model-invocation: true` set for side-effect operations (deploy, commit, publish)
- [ ] `user-invocable` explicitly set (true for /commands, false for background knowledge)
- [ ] `allowed-tools` specified if skill needs tool access without permission prompts
- [ ] `model` specified if skill needs a specific model (haiku for speed, opus for quality)

## Structure

- [ ] SKILL.md is under 500 lines
- [ ] Supporting files in appropriate directories:
  - `templates/` for code templates
  - `references/` for documentation
  - `scripts/` for executable scripts
  - `examples/` for example outputs
  - `steps/` for progressive step loading

## Progressive Step Loading (if applicable)

- [ ] `<entry_point>` section in SKILL.md points to first step
- [ ] `<step_files>` section lists all steps with purpose
- [ ] Each step file has YAML frontmatter with `name` and `description`
- [ ] Each step (except last) has `next_step` in frontmatter
- [ ] All `next_step` paths resolve to existing files
- [ ] Steps follow sequential naming: step-00-*, step-01-*, ...
- [ ] Each step has sections: YOUR TASK, EXECUTION SEQUENCE, SUCCESS METRICS, NEXT STEP
- [ ] State variables documented in `<state_variables>` section

## Forked Context (if applicable)

- [ ] `context: fork` set in frontmatter
- [ ] `agent` field specifies valid agent (Explore, Plan, general-purpose, or custom)
- [ ] `allowed-tools` lists tools the forked context can use
- [ ] Custom agent exists if referenced

## Content Quality

- [ ] Has `<objective>` section explaining what the skill does
- [ ] Has `<quick_start>` with usage examples
- [ ] Has `<workflow>` describing high-level flow
- [ ] Has `<execution_rules>` with key constraints
- [ ] Has `<success_criteria>` defining completion
- [ ] All file references in content point to existing files

## Frontmatter Fields Reference

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | YES | - | Lowercase identifier, max 64 chars |
| `description` | string | YES | - | When/why Claude should use this skill |
| `disable-model-invocation` | bool | no | false | true = manual /command only |
| `user-invocable` | bool | no | true | false = hidden from /menu |
| `allowed-tools` | string | no | - | CSV of tools without permission prompts |
| `model` | string | no | inherit | inherit/sonnet/opus/haiku |
| `context` | string | no | - | "fork" for isolated subagent |
| `agent` | string | no | - | Subagent type if context: fork |
| `argument-hint` | string | no | - | Autocomplete hint text |
| `hooks` | object | no | - | Lifecycle hooks (PreToolUse, etc.) |
