Claude Code Skills

Appearance

Frontmatter Configuration ​

The YAML Frontmatter in SKILL.md defines a Skill's metadata and behavior.

Complete Reference ​

yaml
---
name: python-docstring              # Required: kebab-case name
description: |                      # Required: used for trigger matching
  Generate Google-style Python docstrings for functions and classes.
  Triggered when user asks to add documentation to Python code.
metadata:
  type: workflow                    # Skill category
  version: "1.2.0"                  # Semantic version
  author: team-backend              # Author identifier
triggers:                           # Additional trigger keywords
  - "add docstring"
  - "document this function"
  - "generate docs"
allowed-tools:                      # Tool allowlist
  - Read
  - Write
  - Edit
---

Field Reference ​

name (Required) ​

  • Format: kebab-case, all lowercase, hyphen-separated
  • Globally unique identifier
  • Examples: python-docstring, security-audit, db-migration-helper
yaml
# Good
name: user-auth-helper

# Bad
name: UserAuthHelper    # Not kebab-case
name: auth              # Too generic, likely conflicts

description (Required) ​

The most important field — directly affects trigger accuracy.

  • Length: 1-3 sentences
  • Content: What the Skill does and when to trigger
  • Include natural language trigger words
  • Avoid similarity with other Skill descriptions
yaml
# Good — specific and clear
description: |
  Generate Google-style docstrings for Python functions.
  Triggers on "add docstring", "document this function".

# Bad — too vague
description: |
  Helps with documentation.

triggers (Optional) ​

Additional trigger phrases. Skills can also be triggered directly via /name.

yaml
triggers:
  - "add docstring"
  - "document this"
  - "generate docs for"
  - "add python docs"

Trigger design principles:

  • 2-5 natural language phrases
  • Include common variants
  • Avoid overly generic words (e.g., "help me")
  • Test for conflicts with other Skills

allowed-tools (Optional) ​

Limit which tools the Skill can use. Security best practice.

yaml
# Read-only Skill
allowed-tools:
  - Read

# Code generation Skill
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash

# No restrictions (default)
# Omit the allowed-tools field

metadata (Optional) ​

yaml
metadata:
  type: workflow           # workflow | tool | reference
  version: "1.0.0"
  author: your-team
  tags:
    - python
    - documentation

Common Configurations ​

Read-Only Analysis Skill ​

yaml
name: code-metrics
description: Analyze code complexity and generate metrics report
allowed-tools: [Read, Bash]

Write Skill ​

yaml
name: db-migration
description: Create and validate database migration files
allowed-tools: [Read, Write, Edit, Bash]

Interactive Skill ​

yaml
name: onboarding-wizard
description: Interactive onboarding guide for new team members
# No tool restrictions

Next Steps ​