1.2YAML Frontmatter: The Selection Signal

Required Fields

name (string, max 64 chars)

• Lowercase letters, numbers, hyphens only
• This becomes the invocation command: /my-skill or skill: "my-skill"
• Must be unique across all installed skills

name: browser-tests  # Good
name: Browser Tests  # Bad — no spaces or uppercase
name: browser_tests  # Bad — no underscores

description (string)

• THE critical field. Claude reads all skill descriptions to decide which skill matches user intent
• Must be specific enough to differentiate from other skills
• Should describe the capability, not the implementation

# Good — tells Claude when to use this skill
description: |
  Browser automation via CLI. Navigate pages, click elements,
  fill forms, take screenshots, extract text from web pages.

# Bad — too vague, overlaps with other skills
description: "Helps with web stuff"

# Bad — describes implementation, not capability
description: "Runs playwright-cli commands using the Bash tool"

Optional Fields

allowed-tools (comma-separated string)

• Tools the skill may use, temporarily granted during execution
• Without this, the skill inherits the session's current permissions
• Supports wildcards: Bash(git:*) allows only git commands

allowed-tools: Bash           # Can run any shell command
allowed-tools: Read,Write     # Can read and write files only
allowed-tools: Bash,Read,Write,Glob,Grep  # Full access

model (string)

• Override which Claude model executes the skill
• Useful for cost optimization (use Haiku for simple skills)

model: claude-haiku-4-5   # Cheaper, faster
model: claude-sonnet-5    # Balanced

version (string)

version: "1.0.0"

disable-model-invocation (boolean)

• When true, the skill can only be invoked explicitly (via /skill-name), never automatically

disable-model-invocation: true