SKILL.md Format and Structure

Relevant source files

• .opencode/INSTALL.md
• docs/README.opencode.md
• lib/skills-core.js
• skills/writing-skills/SKILL.md
• skills/writing-skills/render-graphs.js

Purpose and Scope

This document specifies the technical format and structure requirements for SKILL.md files in the Superpowers skills repository. It defines the YAML frontmatter schema, required document sections, embedded diagram formats, and file organization patterns.

For the test-driven development process of creating skills, see Test-Driven Development for Skills. For optimization techniques to improve skill discoverability, see Claude Search Optimization. For the complete creation workflow and deployment checklist, see Skill Creation Checklist.

File Format Overview

Every skill consists of a SKILL.md file with mandatory YAML frontmatter followed by markdown content. The file structure follows a strict schema to enable platform parsing and skill discovery mechanisms.

SKILL.md Components

Diagram: SKILL.md file structure and parsing functions in lib/skills-core.js

Sources: skills/writing-skills/SKILL.md93-137 lib/skills-core.js16-52 lib/skills-core.js178-200

YAML Frontmatter Specification

The frontmatter contains exactly two fields and must not exceed 1024 characters total length. This limit is enforced by platform parsing logic.

Field Requirements

Field	Type	Constraints	Purpose
name	string	Letters, numbers, hyphens only. No parentheses, underscores, or special characters.	Unique skill identifier for skill resolution
description	string	Third-person. Starts with "Use when...". Max 500 characters recommended.	Triggers skill discovery via semantic search

Frontmatter Validation Flow

Valid Frontmatter Examples

Sources: skills/writing-skills/SKILL.md95-103 skills/writing-skills/SKILL.md160-172

Description Field: Triggering Conditions Only

The description field must describe when to invoke the skill, not what the skill does or how it works. This constraint prevents agents from following description summaries instead of reading the full skill content.

Why Workflow Summaries Break Discovery

Testing revealed that when descriptions summarize workflow steps, agents treat the description as a shortcut and skip reading the skill body. For example:

With this description, agents performed only one code review despite the skill's flowchart showing a two-stage review process (spec compliance + code quality). When the description was changed to triggering conditions only:

Agents then correctly read the full skill and followed the two-stage review process.

Description Content Rules

Include	Exclude
Problem symptoms (race conditions, flaky tests)	Process steps (write test, then code, then refactor)
Triggering situations (before implementation, when debugging)	Workflow summaries (dispatches subagent with review)
Error messages (ENOTEMPTY, timeout)	Tool invocations (uses TodoWrite, then Task)
Context clues (using React Router, async code)	Implementation details (creates worktree, then commits)

Sources: skills/writing-skills/SKILL.md140-181

Required Document Sections

Every skill must include specific sections in a defined order. Optional sections may be added based on skill type.

Mandatory Section Structure

Section Content Guidelines

## Overview

• First 1-2 sentences define what the skill is
• State core principle or rule
• Establish foundational concept before details

## When to Use

• Bullet list of specific symptoms that trigger skill invocation
• Include concrete error messages or behavior patterns
• Add "When NOT to use" subsection to prevent misapplication
• May include small inline flowchart if decision is non-obvious (see Flowchart Usage)

## Quick Reference

• Table format for scannable lookup
• Common operations, commands, or patterns
• No narrative explanation - pure reference data

## Implementation

• Inline code blocks for simple patterns (< 50 lines)
• Link to separate file for heavy reference (100+ lines)
• One excellent example in most relevant language
• Comments explain WHY, not WHAT

Sources: skills/writing-skills/SKILL.md105-137

Embedded Flowchart Format

Skills may include Graphviz DOT diagrams embedded in \``dot` code blocks. These diagrams must follow specific usage constraints and style conventions.

When to Use Flowcharts

Valid use cases:

• Non-obvious decision points where agents might choose incorrectly
• Process loops where agents might exit too early
• "When to use A vs B" decisions with multiple conditions

Invalid use cases:

• Reference material (use tables or bullet lists instead)
• Code examples (use markdown code blocks)
• Linear step-by-step instructions (use numbered lists)
• Any diagram with labels lacking semantic meaning (step1, helper2)

DOT Diagram Structure

Style conventions:

• Node names must have semantic meaning (not step1, helper2)
• Use shape=diamond for decision points
• Use shape=box for actions
• Keep labels concise and action-oriented
• Reference skills/writing-skills/graphviz-conventions.dot for full style guide

Sources: skills/writing-skills/SKILL.md290-316

Rendering Flowcharts with render-graphs.js

The render-graphs.js tool extracts and renders DOT diagrams from SKILL.md files to SVG format for visualization.

render-graphs.js Usage

Command Syntax

Key Functions

Function	Purpose	Location
extractDotBlocks(markdown)	Parse all \``dot` blocks from markdown	skills/writing-skills/render-graphs.js20-36
extractGraphBody(dotContent)	Extract node/edge definitions without wrapper	skills/writing-skills/render-graphs.js38-49
combineGraphs(blocks, skillName)	Merge multiple digraphs into subgraph clusters	skills/writing-skills/render-graphs.js51-68
renderToSvg(dotContent)	Execute dot -Tsvg via child process	skills/writing-skills/render-graphs.js70-82

Requirements: System must have graphviz installed (dot command available).

Sources: skills/writing-skills/render-graphs.js1-169

Code Examples in Skills

Skills may include code examples following specific quality and format guidelines.

Example Selection Criteria

One excellent example beats many mediocre ones. Choose the most relevant language for the skill's domain:

Skill Domain	Preferred Language
Testing techniques	TypeScript/JavaScript
System debugging	Shell/Python
Data processing	Python
API integration	Language matching API

Example Quality Requirements

• Complete and runnable: Not pseudocode or templates
• Well-commented: Explain WHY decisions were made, not WHAT code does
• Real scenario: From actual usage, not contrived demo
• Pattern clarity: Shows the core technique clearly
• Adaptation-ready: Concrete enough to port to other contexts

Anti-Pattern: Multi-Language Examples

# ❌ Avoid this pattern
condition-based-waiting/
  example-js.js
  example-py.py
  example-go.go
  example-rb.rb

Why: Results in mediocre quality across all languages, high maintenance burden, and cognitive overload. Agents can port from one excellent example.

Instead: Provide one production-quality example in the most relevant language.

Sources: skills/writing-skills/SKILL.md325-346 skills/writing-skills/SKILL.md563-571

File Organization Patterns

Skills may be self-contained or include supporting files based on content size and reusability.

Organization Decision Tree

Pattern Examples

Self-Contained Skill:

defense-in-depth/
  SKILL.md              # Everything inline

Use when: All principles, patterns, and code fit in < 500 words.

Skill with Reusable Tool:

condition-based-waiting/
  SKILL.md              # Overview + patterns
  example.ts            # Working helpers to adapt

Use when: Tool is reusable code (helpers, templates, utilities), not narrative.

Skill with Heavy Reference:

pptx/
  SKILL.md              # Overview + workflows
  pptxgenjs.md          # 600 lines API reference
  ooxml.md              # 500 lines XML structure
  scripts/              # Executable tools
    create-template.js
    validate-slides.js

Use when: Reference material too large for inline (100+ lines) or multiple executable tools needed.

Sources: skills/writing-skills/SKILL.md347-373

Cross-Referencing Other Skills

Skills may reference other skills using standardized syntax that avoids force-loading files into context.

Reference Syntax

Required skill reference:

Required background knowledge:

Syntax Comparison

Syntax	Effect	When to Use
superpowers:skill-name	Reference by name, agent loads on demand	Default for all references
**REQUIRED SUB-SKILL:** prefix	Emphasizes mandatory dependency	Skill cannot work without it
**REQUIRED BACKGROUND:** prefix	Emphasizes prerequisite knowledge	User must understand before using
@skills/path/SKILL.md	Force-loads file immediately	Never use - burns 200k+ context tokens

Why Avoid @ Links

The @ syntax in skill references triggers immediate file loading, consuming context tokens before the content is needed. Since skills average 200-500 words and may reference multiple dependencies, force-loading can consume 50k-200k tokens prematurely.

Instead, skill name references allow the agent to invoke skill discovery mechanisms (Skills Discovery and Resolution) only when needed.

Sources: skills/writing-skills/SKILL.md278-288

Directory Structure Requirements

All skills must follow a flat namespace structure within the skills repository.

Repository Layout

obra/superpowers-skills/
  skill-name/
    SKILL.md              # Required
    supporting-file.*     # Optional
  another-skill/
    SKILL.md
  third-skill/
    SKILL.md
    helper-script.sh
    reference-doc.md

Flat namespace properties:

• All skills at repository root level
• No nested skill directories
• No skill categories or grouping folders
• Single searchable namespace for skill discovery

Rationale: Platform skill discovery scans directory names at repository root. Nested structures would not be discovered by Skills Discovery and Resolution mechanisms.

Supported File Types

Within a skill directory:

• SKILL.md - Required, main skill document
• .md - Supporting documentation or reference material
• .js, .sh, .py - Executable tools or scripts
• .dot - Standalone Graphviz files (if extracted from SKILL.md)
• .ts, .go, etc. - Code examples or helper libraries

Sources: skills/writing-skills/SKILL.md72-92

Token Efficiency Considerations

Frequently-loaded skills (like using-superpowers injected at session start) must minimize token consumption as they load into every conversation.

Target Word Counts by Skill Type

Skill Type	Target	Rationale
Getting-started workflows	< 150 words each	Loaded in bootstrap context
Frequently-referenced skills	< 200 words total	High load frequency
Other skills	< 500 words	Still maintain conciseness

Token Reduction Techniques

Move details to tool --help:

Use cross-references:

Compress examples:

Verification command:

Sources: skills/writing-skills/SKILL.md213-267

Validation Checklist

Before committing a skill, verify format compliance:

Frontmatter:

• Only name and description fields present
• Total frontmatter ≤ 1024 characters
• Name uses only letters, numbers, hyphens
• Description starts with "Use when..."
• Description written in third person
• Description describes triggers, not workflow

Structure:

• ## Overview section present
• ## When to Use section present
• Flowcharts only for non-obvious decisions
• No generic labels in flowcharts (step1, helper2)
• Code examples are complete and runnable
• Cross-references use skill name syntax, not @ links

Organization:

• Skill in flat namespace (not nested)
• Supporting files only for tools or heavy reference
• Token count appropriate for skill type

Sources: skills/writing-skills/SKILL.md596-634