# How to Define Metadata for a Skill in Superpowers: A Complete Guide

> Learn to define metadata for a skill in Superpowers by adding a YAML front-matter block with name and description fields to your SKILL.md file. Get started now.

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

---

**Define metadata for a skill in Superpowers by adding a YAML front-matter block to the top of the skill's [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) file, containing exactly two fields: `name` (a unique identifier with only letters, numbers, and hyphens) and `description` (a trigger sentence starting with "Use when...").**

When you create a reusable skill for the [obra/superpowers](https://github.com/obra/superpowers) framework, you must define metadata that tells the runtime how to identify and trigger your skill. This metadata lives in a specific YAML block at the top of your skill's documentation file and follows strict formatting rules to ensure the Superpowers runtime can parse it correctly.

## Where Skill Metadata Lives in Superpowers

### The SKILL.md File Structure

Every skill in the Superpowers ecosystem resides in its own directory under `skills/`, and each skill directory contains a [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) file. This file serves dual purposes: it documents the skill for human readers and carries machine-readable metadata for the Superpowers runtime.

The metadata must appear at the very top of [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) inside a **YAML front-matter block** delimited by triple dashes (`---`):

```markdown
---
name: your-skill-name
description: Use when you encounter a specific situation that requires this skill's guidance
---

```

### Supported Metadata Fields

Superpowers recognizes only two fields in the front-matter block. Adding extra fields will not cause errors, but the runtime ignores them during skill discovery.

| Field | Purpose | Constraints |
|-------|---------|-------------|
| `name` | Unique identifier used to invoke the skill via `superpowers:<name>` | Lowercase letters, numbers, and hyphens only. No spaces or special characters. |
| `description` | Trigger sentence that tells Claude **when** to load the skill | Must start with **"Use when..."**, describe symptoms or contexts (not workflows), and be ≤ 1024 characters. |

## How to Write a Valid Skill Name

The `name` field serves as the skill's command identifier. When users invoke your skill, they use the syntax `superpowers:<name>`, so the name must be URL-friendly and easy to type.

Valid names follow these rules:
- Contain only **lowercase letters**, **numbers**, and **hyphens** (`-`)
- Contain **no spaces**, underscores, or special characters
- Be descriptive but concise (e.g., `refactor-python`, `debug-docker`, `write-tests`)

**Example of a valid name:**

```yaml
name: creating-skills

```

**Invalid examples to avoid:**

```yaml
name: Creating Skills  # Contains uppercase and spaces

name: creating_skills  # Contains underscore

name: creating.skills  # Contains period

```

## How to Write an Effective Description

The `description` field is arguably the most critical piece of metadata because it determines whether Claude loads your skill for a given task. This field must act as a **trigger**, not a summary.

### The "Use When..." Rule

Every description must begin with the exact phrase **"Use when..."** followed by a third-person description of the symptoms, contexts, or conditions that warrant the skill's activation.

**Correct format:**

```yaml
description: Use when you need to author a new reusable skill or update an existing one, and you have identified the triggering conditions for the skill

```

**Incorrect format (summarizing workflow):**

```yaml
description: This skill helps you create new skills by outlining the steps to write metadata and documentation  # Wrong: summarizes what it does, not when to use it

```

### Content Constraints

- **Length**: Maximum 1024 characters
- **Focus**: Describe the *problem state* or *context clues* that indicate the skill is needed
- **Avoid**: Workflow steps, implementation details, or feature lists

**Example of a good description:**

```yaml
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment

```

## How the Superpowers Runtime Parses Metadata

When the Superpowers system initializes, it scans the `skills/` directory and extracts metadata from each [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) file using the `extractFrontmatter` function in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js).

This function performs a line-by-line scan to locate the YAML block between the opening and closing `---` delimiters:

```javascript
// lib/skills-core.js
function extractFrontmatter(filePath) {
    const content = fs.readFileSync(filePath, 'utf8');
    const lines = content.split('\n');
    let inFrontmatter = false;
    let name = '';
    let description = '';

    for (const line of lines) {
        if (line.trim() === '---') {
            if (inFrontmatter) break;
            inFrontmatter = true;
            continue;
        }
        if (inFrontmatter) {
            const match = line.match(/^(\w+):\s*(.*)$/);
            if (match) {
                const [, key, value] = match;
                if (key === 'name') name = value.trim();
                if (key === 'description') description = value.trim();
            }
        }
    }
    return { name, description };
}

```

The runtime caches these values at startup. When processing a user request, Claude evaluates the `description` field to determine if the skill's context matches the current task before loading the full skill content.

## Complete Examples of Skill Metadata

### Minimal Template

Use this template when creating a new skill:

```markdown
---
name: your-skill-name
description: Use when you encounter <specific symptom or situation>, and you need the skill's guidance to resolve it
---

# Your Skill Title

Your skill content begins here...

```

### Real-World Example: writing-skills

The `writing-skills` skill in the repository demonstrates proper metadata formatting:

```markdown
---
name: writing-skills
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
---

```

You can view the complete file at [`skills/writing-skills/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md) in the [obra/superpowers](https://github.com/obra/superpowers) repository.

### Real-World Example: using-superpowers

Another valid example from the `using-superpowers` skill:

```markdown
---
name: using-superpowers
description: Use when you need to understand how to invoke or manage Superpowers skills during a conversation
---

```

This example is located at [`skills/using-superpowers/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/using-superpowers/SKILL.md).

## Summary

- **Define metadata for a skill in Superpowers** by adding a YAML front-matter block to the top of the skill's [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) file, enclosed in triple dashes (`---`).
- Include exactly two fields: `name` (lowercase letters, numbers, and hyphens only) and `description` (must start with "Use when...").
- The `description` acts as a trigger sentence describing when to load the skill, not what the skill does.
- The Superpowers runtime extracts this metadata using `extractFrontmatter` in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) at startup to determine skill applicability.

## Frequently Asked Questions

### What happens if I don't include the "Use when..." prefix in the description?

Claude may fail to recognize the appropriate contexts for loading your skill. The Superpowers system relies on the "Use when..." format to distinguish trigger conditions from workflow instructions. Without this prefix, the runtime might misinterpret your description as content rather than a triggering condition, causing the skill to load at inappropriate times or not at all.

### Can I add custom fields to the YAML front-matter?

While the YAML parser will not reject additional fields, the `extractFrontmatter` function in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) specifically looks for only `name` and `description`. Any extra fields you add will be ignored by the runtime and will not affect how Claude loads or uses the skill. For token efficiency and clarity, stick to the two required fields only.

### How long should the description be?

Keep your description under **1024 characters** to comply with system constraints. More importantly, make it concise enough to serve as a quick trigger check—typically one or two sentences describing the specific symptoms or contexts that warrant the skill. Avoid lengthy explanations; the full [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) content below the front-matter should contain the detailed workflow instructions.

### Where does the skill name appear when invoked?

Users invoke your skill using the syntax `superpowers:<skill-name>` during conversations. The `name` field you define in the front-matter becomes the identifier in this command. For example, if your metadata specifies `name: debug-docker`, users activate it by typing `superpowers:debug-docker`. This is why the name must contain only lowercase letters, numbers, and hyphens—special characters would break the command parsing.