YAML Frontmatter Reference

YAML Frontmatter Reference

Complete field-by-field reference for Claude Code SKILL.md frontmatter.

Overview

YAML frontmatter is metadata at the start of SKILL.md files, delimited by ---:

---
name: skill-name
description: What this skill does
version: 1.0.0
# ... more fields ...
---

# Skill content starts here

Required Fields

name

Type: string Format: kebab-case Required: Yes

Description: Unique identifier for the skill. Used to reference and invoke the skill.

Rules:

• Must be unique across all installed skills
• Lowercase letters, numbers, hyphens only
• Must start with a letter
• No spaces, underscores, or special characters

Valid:

name: code-analyzer
name: api-doc-generator
name: git-commit-helper
name: hello-world
name: python3-test-generator

Invalid:

name: CodeAnalyzer       # Not lowercase
name: code_analyzer      # Underscores not allowed
name: code analyzer      # Spaces not allowed
name: codeAnalyzer       # camelCase not allowed
name: 123-analyzer       # Can't start with number

description

Type: string Format: One sentence, no trailing period Required: Yes

Description: Concise summary of what the skill does. Shows in skill listings and helps Claude decide when to use the skill.

Rules:

• One sentence only
• Focus on WHAT the skill does, not HOW
• Be specific, avoid generic terms
• No period at end (convention)
• Keep under 100 characters
• Start with a verb when possible

Good:

description: Analyzes Python code for common anti-patterns and security vulnerabilities
description: Generates comprehensive API documentation from source code comments
description: Creates conventional commit messages based on staged git changes
description: Refactors JavaScript code to use modern ES6+ syntax

Bad:

description: Helps with code.                    # Too vague
description: Analyzes code. Also helps test it.  # Multiple sentences
description: A tool for analyzing Python code for anti-patterns, security issues, and more.  # Too long
description: Code analyzer                       # Too brief, not descriptive

version

Type: string Format: Semantic versioning (MAJOR.MINOR.PATCH) Required: Yes

Description: Version number following semver conventions. Used to track changes and compatibility.

Rules:

• Must be three numbers separated by dots
• Format: MAJOR.MINOR.PATCH
• No 'v' prefix
• No pre-release tags (yet)
• Start new skills at 1.0.0

Versioning Guidelines:

• Major (X.0.0): Breaking changes to skill behavior or interface
• Minor (1.X.0): New features, backward compatible
• Patch (1.0.X): Bug fixes, documentation updates, no new features

Valid:

version: 1.0.0
version: 2.1.3
version: 0.1.0
version: 10.0.5

Invalid:

version: 1.0           # Missing patch number
version: v1.0.0        # 'v' prefix not allowed
version: 1.0.0-beta    # Pre-release tags not supported
version: 1.0.0.1       # Too many numbers
version: "1.0.0"       # Quotes unnecessary (but not wrong)

Optional Fields

author

Type: string Format: Free-form text Required: No

Description: Person, team, or organization that created the skill. Used for attribution and contact.

Examples:

author: Jane Developer
author: Platform Team
author: Jane Developer <jane@example.com>
author: Acme Corporation
author: @janedeveloper

Tips:

• Include email for contact
• Use consistent format across your skills
• Optional but recommended for shared skills

tags

Type: array of strings Format: Lowercase keywords Required: No

Description: Keywords for categorization, search, and discovery. Helps users find relevant skills.

Format Options:

# Inline array
tags: [python, testing, automation]

# Multiline array
tags:
  - python
  - testing
  - automation

Category Patterns:

By Type:

tags: [code-analysis, documentation, testing, refactoring, generation, validation]

By Domain:

tags: [web-dev, data-science, devops, mobile, backend, frontend]

By Technology:

tags: [python, javascript, react, typescript, go, rust, java]

By Purpose:

tags: [automation, security, performance, quality, productivity]

Combined:

tags: [python, testing, automation, backend]

Tips:

• Use 3-7 tags
• Be specific: react not just javascript
• Include both type and domain tags
• Consistent lowercase
• No spaces in individual tags

allowed-tools

Type: array of strings Format: Exact tool names (case-sensitive) Required: No (but highly recommended)

Description: Tools this skill is permitted to use. Claude Code enforces these permissions for security.

Valid Tool Names:

File Operations:

• Read - Reading file contents
• Write - Creating new files
• Edit - Modifying existing files
• Glob - Finding files by pattern
• Grep - Searching file contents with regex

System:

• Bash - Executing shell commands
• BashOutput - Reading background shell output
• KillShell - Terminating background shells

Interactive:

• AskUserQuestion - Prompting user for input
• TodoWrite - Managing task lists

Advanced:

• WebFetch - Fetching web content
• SlashCommand - Executing slash commands
• Skill - Invoking other skills

Format Options:

# Inline (for 1-2 tools)
allowed-tools: [Read, Write]

# Multiline (preferred for 3+ tools)
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep

Examples by Use Case:

Code Analysis (read-only):

allowed-tools:
  - Read
  - Glob
  - Grep

Documentation Generation:

allowed-tools:
  - Read
  - Write
  - Glob

Code Refactoring:

allowed-tools:
  - Read
  - Edit
  - Glob

Interactive Workflow:

allowed-tools:
  - AskUserQuestion
  - Read
  - Write

System Automation:

allowed-tools:
  - Bash
  - Read

Meta-Skill (skill that creates things):

allowed-tools:
  - AskUserQuestion
  - Write
  - Bash

Common Mistakes:

# ❌ Wrong case
allowed-tools:
  - bash        # Should be "Bash"
  - read        # Should be "Read"

# ❌ Invalid tool names
allowed-tools:
  - FileRead    # Should be "Read"
  - Execute     # Should be "Bash"

# ❌ Too many tools
allowed-tools:  # Only request what you'll use
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - WebFetch
  - AskUserQuestion
  - TodoWrite

Guidelines:

• Only request tools you'll actually use
• Fewer tools = better security
• Case-sensitive: must match exactly
• Alphabetical order (optional but nice)

dependencies

Type: array of strings Format: Skill names (kebab-case) Required: No

Description: Other skills that this skill requires or invokes. Declares dependencies for documentation and validation.

Format:

# Single dependency
dependencies: [code-analyzer]

# Multiple dependencies
dependencies:
  - code-analyzer
  - test-generator
  - doc-writer

Use Cases:

• Skill invokes other skills using Skill tool
• Skill extends another skill's functionality
• Skill relies on output from another skill

Example:

name: comprehensive-code-review
description: Performs analysis, generates tests, and creates documentation
version: 1.0.0
allowed-tools:
  - Skill
  - Write
dependencies:
  - code-analyzer      # For code analysis
  - test-generator     # For test creation
  - doc-writer         # For documentation

Notes:

• Dependencies must be installed
• Avoid circular dependencies
• List only direct dependencies

examples

Type: array of strings Format: Example invocation prompts Required: No

Description: Example prompts showing how to invoke the skill. Helpful for documentation and discoverability.

Format:

examples:
  - "Analyze the authentication module for security issues"
  - "Check all API endpoints for consistency"
  - "Review the database models for optimization opportunities"

Guidelines:

• Write as natural language prompts
• Show diverse use cases
• Include 2-5 examples
• Be specific, not generic
• Start with verbs

Good:

examples:
  - "Generate API documentation for the user service"
  - "Create JSDoc comments for all public functions in utils.js"
  - "Document the REST endpoints in the api/ directory"

Bad:

examples:
  - "Use this skill"               # Too vague
  - "api-doc-generator"            # Not a natural prompt
  - "This skill generates docs"    # Describes, doesn't demonstrate

Complete Example

---
name: python-security-analyzer
description: Analyzes Python code for security vulnerabilities and common anti-patterns
version: 1.2.0
author: Security Team <security@example.com>
tags: [python, security, code-analysis, automation]
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
dependencies:
  - code-analyzer
examples:
  - "Analyze the auth module for security vulnerabilities"
  - "Check all Python files for SQL injection risks"
  - "Review the API handlers for XSS vulnerabilities"
---

Validation

All frontmatter fields are validated when skills are created using skill-builder.

Validation Checks:

Required Fields:

• ✓ name is present and kebab-case
• ✓ description is present and concise
• ✓ version is present and valid semver

Optional Fields:

• ✓ allowed-tools contains only valid tool names (case-sensitive)
• ✓ dependencies reference existing skills
• ✓ tags are lowercase and reasonable

Syntax:

• ✓ YAML parses without errors
• ✓ Frontmatter delimited by ---
• ✓ No typos in field names

Validation Tool:

python3 ~/.claude/skills/skill-builder/scripts/validate_yaml.py /path/to/SKILL.md

Common Mistakes

1. Field Name Typos

---
name: my-skill
descripton: Wrong field name!     # ❌ "descripton"
version: 1.0.0
---

2. Wrong Case in Tools

---
allowed-tools:
  - bash      # ❌ Should be "Bash"
  - Read      # ✓ Correct
---

3. Invalid Version Format

---
version: 1.0       # ❌ Missing patch number
version: v1.0.0    # ❌ 'v' prefix
version: 1.0.0     # ✓ Correct
---

4. Non-kebab-case Name

---
name: mySkill       # ❌ camelCase
name: my_skill      # ❌ underscores
name: my-skill      # ✓ Correct
---

5. Description Too Long or Multiple Sentences

---
description: This skill analyzes code. It also generates tests.  # ❌ Multiple sentences
description: Analyzes code and generates tests                   # ✓ One sentence
---

Tips

1. Start Simple: Begin with minimal frontmatter, add fields as needed
2. Validate Early: Use validation tool to catch errors
3. Be Consistent: Use same format across all your skills
4. Document Well: Include author, tags, examples for shared skills
5. Minimal Tools: Only request tools you'll actually use
6. Version Properly: Follow semver conventions for versioning

Next Steps

• Read skill-structure.md for complete skill anatomy
• Review best-practices.md for design patterns
• Use skill-builder to create validated skills
• Examine examples/simple-skill/ for working example