# YAML Frontmatter Format for Superpowers Skills: Complete Specification

> Learn the exact YAML frontmatter format for Superpowers skills. Discover the required name and description fields and their specifications for SKILL.md files.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: api-reference
- Published: 2026-02-16

---

**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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/SKILL.md) file must declare exactly two fields within its YAML frontmatter block. According to the specification in [`skills/writing-skills/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/SKILL.md) file. The block uses standard YAML delimiters: three hyphens (`---`) to open and close the metadata section.

The structure follows this exact pattern:

```yaml
---
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`](https://github.com/obra/superpowers/blob/main/skills/using-superpowers/SKILL.md) (lines 1-8):

```yaml
---
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:

```yaml
---
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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md) and [`skills/using-superpowers/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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.