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

Define metadata for a skill in Superpowers by adding a YAML front-matter block to the top of the skill's 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 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 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 inside a YAML front-matter block delimited by triple dashes (---):

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

name: creating-skills

Invalid examples to avoid:

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:

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):

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:

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 file using the extractFrontmatter function in lib/skills-core.js.

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

// 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:

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

---
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 in the obra/superpowers repository.

Real-World Example: using-superpowers

Another valid example from the using-superpowers skill:

---
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.

Summary

• Define metadata for a skill in Superpowers by adding a YAML front-matter block to the top of the skill's 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 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 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 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.

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