YAML Frontmatter Format for Superpowers Skills: Complete Specification

Superpowers skills require a strict YAML frontmatter block containing exactly two fields—name (alphanumeric with hyphens) and description (starting with "Use when...")—wrapped in triple-dash delimiters at the top of every SKILL.md file.

The obra/superpowers repository implements a rigid metadata schema to enable reliable skill discovery and invocation. Understanding the YAML frontmatter format for Superpowers skills is essential for authoring valid skill definitions that the engine can index and execute correctly.

Required Frontmatter Fields

Every SKILL.md file must declare exactly two fields within its YAML frontmatter block. According to the specification in skills/writing-skills/SKILL.md (lines 95-99), the engine strictly validates these fields during skill discovery.

The name Field

The name field serves as the unique identifier for the skill within the Superpowers engine.

• Required: Yes
• Allowed characters: Letters, numbers, and hyphens only
• Restrictions: No spaces, parentheses, or other punctuation marks
• Purpose: Used by the engine to locate and invoke the specific skill

A valid name follows the kebab-case convention, such as using-superpowers or condition-based-waiting.

The description Field

The description field defines the triggering conditions that signal when the skill should be activated.

• Required: Yes
• Format: Plain text, maximum 1024 characters
• Voice: Must be written in third-person
• Mandatory prefix: Must begin with the exact phrase Use when ...
• Content rules: Must list triggering conditions, symptoms, or contexts that make the skill applicable
• Prohibited content: Must not describe the skill's workflow, implementation steps, or execution logic

This description acts as a semantic trigger for the AI engine, helping it determine skill relevance based on conversation context.

File Structure and Placement

The YAML frontmatter block must occupy the first three lines of the SKILL.md file. The block uses standard YAML delimiters: three hyphens (---) to open and close the metadata section.

The structure follows this exact pattern:

---
name: skill-identifier
description: Use when specific conditions indicate this skill is required
---

Any content following the closing --- delimiter constitutes the skill's documentation body, which may include implementation details, examples, and workflow descriptions that were prohibited from the frontmatter description field.

Complete YAML Frontmatter Examples

Valid Skill Definition

The using-superpowers skill demonstrates the canonical format as implemented in skills/using-superpowers/SKILL.md (lines 1-8):

---
name: using-superpowers
description: Use when starting any conversation – establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
---

This example adheres to all constraints: the name uses only hyphens and letters, the description begins with "Use when", stays within the character limit, and describes triggering contexts rather than workflow steps.

Minimal Required Syntax

A minimal valid frontmatter for a hypothetical condition-waiting skill:

---
name: condition-based-waiting
description: Use when a process may hang or race, and you need to wait for a specific condition before proceeding
---

This satisfies the engine's requirements while remaining concise and focused strictly on activation triggers.

Common Mistakes to Avoid

When authoring SKILL.md files for the obra/superpowers repository, avoid these validation errors that prevent skill indexing:

• Invalid name characters: Using spaces, underscores, or parentheses in the name field (e.g., name: my_skill or name: mySkill(helper)) violates the alphanumeric-plus-hyphen rule.
• Missing "Use when" prefix: Descriptions that omit the mandatory opening phrase or use variations like "Use if..." or "When to use..." fail validation.
• Workflow details in description: Including implementation steps (e.g., "Use when... then execute X, then check Y") in the description field violates the rule that this field must contain only triggering conditions, not execution logic.

Source Code References

The YAML frontmatter specification is enforced by the engine's skill discovery mechanism. Key files in the obra/superpowers repository define and demonstrate this format:

File	Purpose
skills/writing-skills/SKILL.md	Contains the canonical specification for frontmatter fields (lines 95-99), including character restrictions and description requirements
skills/using-superpowers/SKILL.md	Provides a concrete implementation example (lines 1-8) showing valid syntax for the name and description fields
skills/*/SKILL.md	All skill files in the repository follow the identical frontmatter pattern, demonstrating consistent application of the format

Summary

• Superpowers skills require a strict two-field YAML frontmatter at the top of every SKILL.md file.
• The name field accepts only letters, numbers, and hyphens, serving as the unique skill identifier.
• The description field must start with "Use when...", stay under 1024 characters, and describe only triggering conditions—not workflow.
• The frontmatter block must occupy the first three lines of the file, delimited by ---.
• Reference implementations exist in skills/writing-skills/SKILL.md and skills/using-superpowers/SKILL.md.

Frequently Asked Questions

What characters are allowed in the skill name?

The name field accepts letters, numbers, and hyphens only. You cannot use spaces, underscores, parentheses, or other punctuation marks. This restriction ensures the engine can reliably parse skill identifiers across different filesystems and invocation contexts.

Why must the description start with "Use when..."?

The "Use when..." prefix serves as a semantic marker that helps the Superpowers engine recognize the description as a trigger condition rather than documentation. This standardized format enables the system to evaluate conversation context against skill applicability rules during the skill selection phase.

Can I include optional fields in the YAML frontmatter?

No, the engine strictly validates against exactly two fields: name and description. Adding additional metadata fields—such as author, version, or tags—will cause validation errors during skill discovery. All supplementary documentation should appear in the markdown body after the closing --- delimiter.

Where does the frontmatter block appear in the file?

The YAML frontmatter must occupy the first three lines of the SKILL.md file. It begins with --- on line 1, contains the name and description fields on lines 2-3, and closes with --- on line 4. Any content preceding the opening --- or following the closing --- constitutes the skill's documentation body, not frontmatter.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}