skill-structure

name	skill-structure
description	Skill file structure, naming conventions, directory layout, frontmatter requirements, and invocation control. Use when creating skill files or slash commands to ensure correct format and validation.

Skill Structure

Commands and Skills Are Merged

Custom slash commands and skills are the same thing. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review. Existing .claude/commands/ files keep working. Skills add: a directory for supporting files, frontmatter to control invocation, and automatic context loading.

If a skill and command share the same name, the skill takes precedence.

When to use which:

Type	When
Command file (commands/name.md)	Simple single-file workflow, no supporting files
Skill directory (skills/name/SKILL.md)	Needs references, background knowledge, or progressive disclosure

Naming Rules

Rule	Example
Format	kebab-case, lowercase, 1-64 chars
Pattern	^[a-z][a-z0-9]*(-[a-z0-9]+)*$
Must match	Directory name exactly

Good/Bad Examples:

Good	Bad	Why
stimulus-coder