Skill Documentation Format in the OpenAI Skills Repository: A Complete Guide

The openai/skills repository requires every skill to include a SKILL.md file using a standardized format with mandatory YAML front-matter containing name and description fields, followed by GitHub-flavored Markdown sections for prerequisites, workflow, and resources.

The openai/skills repository organizes automation capabilities as self-contained directories, each requiring strict adherence to a specific skill documentation format. This standardized structure ensures that skills are discoverable, installable, and correctly rendered within the Codex ecosystem. Understanding the required SKILL.md format is essential for contributors building new skills or modifying existing ones.

Where Skill Documentation Lives in the Repository

Skills are organized into three distinct directories under skills/:

• skills/.curated/ – Production-ready skills with full documentation
• skills/.experimental/ – Work-in-progress skills
• skills/.system/ – Core infrastructure skills like skill-installer

Each skill directory must contain a SKILL.md file at its root. For example, the yeet skill documentation resides at skills/.curated/yeet/SKILL.md, while the system installer documentation is located at skills/.system/skill-installer/SKILL.md.

Required SKILL.md Structure

The skill documentation format follows a consistent pattern across all directories, combining mandatory YAML front-matter with optional Markdown sections.

Mandatory YAML Front-Matter

Every SKILL.md must begin with YAML front-matter enclosed by triple dashes:

---
name: "my-skill"
description: "Brief one-sentence description of what the skill does."
metadata:
  short-description: "One-line UI blurb"
---

The name and description fields are required. The metadata.short-description field is strongly recommended for proper rendering in UI list views.

Documentation Sections

Following the front-matter, the file uses standard GitHub-flavored Markdown with these common sections:

Prerequisites (## Prerequisites): Lists external tools, CLI utilities, or authentication requirements:

## Prerequisites

- `git` must be installed and available on `$PATH`.
- Valid API token in `$CODEX_HOME/.env` for external services.

Naming Conventions (## Naming conventions): Documents recommended patterns for branches, commits, or PR titles.

Workflow (## Workflow or ## Quick start): A numbered, step-by-step guide that the skill follows when invoked:

## Workflow

1. Validate the input parameters.
2. Call the external API endpoint.
3. Write the response to `output.json`.
4. Prompt the user to confirm changes.

Scripts and Resources (## Scripts or ## Bundled Resources): References helper scripts in the skill's scripts/ folder:

## Scripts

```sh

# List available sub-commands

python scripts/list-options.py --skill my-skill

# Run the main action

python scripts/run-my-skill.py --input "some data"

## Real-World Examples from the Repository

The skill documentation format varies by complexity. The `skill-installer` at [`skills/.system/skill-installer/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/SKILL.md) demonstrates basic metadata with a descriptive overview. The `yeet` skill at [`skills/.curated/yeet/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md) includes front-matter, prerequisites, naming conventions, and a detailed workflow. The `gh-fix-ci` skill at [`skills/.curated/gh-fix-ci/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/gh-fix-ci/SKILL.md) provides front-matter, detailed workflow, quick-start commands, and bundled resources.

## Best Practices for Skill Documentation Format

To ensure compatibility with the Codex skill manager:

- **Maintain consistent section ordering**: Place YAML front-matter first, followed by prerequisites, naming conventions, workflow, and resources.
- **Use executable examples**: Provide concrete CLI commands in fenced code blocks so users can run them verbatim.
- **Reference assets correctly**: When including icons or images, use paths relative to the skill folder (e.g., `./assets/yeet.png`).
- **Validate front-matter**: Ensure `name` and `description` fields are present, as the skill installer parses these for UI display.

## Summary

The openai/skills repository enforces a strict skill documentation format to ensure consistency across all automation capabilities. Key requirements include:

- Every skill must contain a [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file at the directory root.
- The file must begin with YAML front-matter specifying `name` and `description`.
- Documentation uses GitHub-flavored Markdown with standard sections for prerequisites, workflow, and resources.
- Helper scripts should be referenced from the `scripts/` folder within the skill directory.

## Frequently Asked Questions

### What happens if I omit the YAML front-matter in SKILL.md?

The skill installer and Codex UI rely on the front-matter to extract the skill name and description. Without it, the skill may not appear in the skill list or may fail validation during installation.

### Can I include images or icons in my skill documentation?

Yes. Place assets in an `assets/` folder within your skill directory and reference them using relative paths such as `./assets/icon.png`. The Codex UI renders these alongside the skill description.

### Is there a specific order required for the Markdown sections?

While the repository parser is flexible, maintaining a consistent order—YAML front-matter, prerequisites, naming conventions, workflow, then resources—improves readability and aligns with the structure used by the skill manager for automated parsing.

### Where can I find a template for creating new skill documentation?

The `skill-creator` system skill at `skills/.system/skill-creator/` includes reference files and templates. Specifically, [`skills/.system/skill-creator/references/openai_yaml.md`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/references/openai_yaml.md) defines the schema used for the YAML front-matter and documentation structure.

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