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

> Learn the required SKILL.md format for the openai skills repository. Master mandatory YAML front-matter and Markdown sections for your skills.

- Repository: [OpenAI/skills](https://github.com/openai/skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**The openai/skills repository requires every skill to include a [`SKILL.md`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/SKILL.md) file at its root. For example, the `yeet` skill documentation resides at [`skills/.curated/yeet/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md), while the system installer documentation is located at [`skills/.system/skill-installer/SKILL.md`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/SKILL.md) must begin with YAML front-matter enclosed by triple dashes:

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

```markdown

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

```markdown

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

```markdown

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