Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/skills/llms.txt

Use this file to discover all available pages before exploring further.

SKILL.md is the only required file in any skill. It serves as both the trigger mechanism and the instruction set: the YAML frontmatter tells Codex when to activate the skill, and the Markdown body tells it what to do once activated. Getting these two parts right is the most important design decision in skill authoring.

​
Frontmatter

The frontmatter block is YAML enclosed in --- delimiters at the top of the file. Only two fields matter to Codex: 
---
name: my-skill-name
description: What this skill does and when to use it. Codex reads this to decide
  whether the skill is relevant to a given request.
---

​
name (required)

The skill name. Must match the skill’s directory name exactly. Rules: lowercase letters, digits, and hyphens only; maximum 64 characters; no leading or trailing hyphens. 
name: vercel-deploy

​
description (required)

The primary triggering mechanism. Codex reads the description of every installed skill on every turn to decide which skills are relevant. A weak description means the skill activates at the wrong time — or never. Write the description to answer two questions:
  1. What does this skill do?
  2. When should Codex use it?
Include specific trigger phrases, file types, task contexts, and user request patterns. All “when to use” guidance must live in the description — not in the body. The body is only loaded after triggering, so a “When to Use This Skill” section in the body is useless for triggering decisions. Good description: 
description: Deploy applications and websites to Vercel. Use when the user
  requests deployment actions like "deploy my app", "deploy and give me the
  link", "push this live", or "create a preview deployment".
Poor description: 
description: Vercel deployment skill.
The poor version tells Codex what the skill is but not when to use it. A user asking to “push this live” would likely not trigger it. Description constraints:
  • Maximum 1024 characters
  • No angle brackets (< or >)
  • Should mention specific user request patterns, file types, or contexts

​
Body

The body is the Markdown content below the closing --- of the frontmatter. It is loaded into context only after the skill triggers. Write it for another instance of Codex, not for a human reader — concise, imperative, and focused on what the agent needs to know.

​
Writing Guidelines

  • Use imperative/infinitive form: “Check whether the Vercel CLI is installed” not “You should check…”
  • Keep under 500 lines: Approaching this limit is a sign that content should be split into reference files.
  • Prefer examples over explanations: Codex is already very smart. Show a concrete command or code snippet rather than explaining what the command does in general terms.
  • Reference bundled resources explicitly: For every scripts/, references/, and assets/ file, state clearly when Codex should use it.

​
The Four Structural Patterns

Choose the structure that best fits the skill’s purpose. These patterns can be mixed. Pattern 1: Workflow-Based — Best for sequential processes with clear decision points. 
# Vercel Deploy

## Prerequisites
...

## Quick Start
1. Check for Vercel CLI
2. Run `vercel deploy`

## Fallback (No Auth)
...

## Production Deploys
...
Pattern 2: Task-Based — Best for skills that offer multiple distinct operations. 
# PDF Editor

## Quick Start
...

## Merge PDFs
...

## Split PDFs
...

## Extract Text
...
Pattern 3: Reference/Guidelines — Best for brand standards, coding policies, or specifications. 
# Brand Guidelines

## Colors
...

## Typography
...

## Logo Usage
...
Pattern 4: Capabilities-Based — Best for integrated systems that provide multiple interrelated features. 
# Product Management

## Core Capabilities
1. Context gathering
2. Status updates
3. Roadmap planning
...

​
Progressive Disclosure

Skills use a three-level loading system to manage context efficiently:
  1. Metadata (name + description) — Always in context (~100 words). Codex reads every installed skill’s metadata on every turn to decide which skills are relevant.
  2. SKILL.md body — Loaded when the skill triggers. Target under 5,000 words and 500 lines. Content beyond this limit should live in reference files.
  3. Bundled resources — Loaded on demand as Codex determines they are needed. Scripts can also be executed directly without being loaded into the context window at all.
This layered approach keeps the default context footprint small. Only metadata is always present; everything else is loaded only when it is actually needed.
Keep the SKILL.md body under 500 lines. If you are approaching that limit, split content into references/ files and add explicit pointers in SKILL.md describing when to read them.

​
What Goes in SKILL.md vs. Reference Files

Put in SKILL.mdPut in references/
Core workflow stepsDetailed API documentation
Decision treesDatabase schemas
Essential commandsComprehensive guides
Navigation pointers to reference filesExamples and patterns
Triggering context (in description)Long reference material
Avoid duplicating content between SKILL.md and reference files. If a database schema lives in references/schema.md, do not also summarize it in SKILL.md. Instead, add a pointer: “For table schemas, read references/schema.md.” Information should live in exactly one place.

​
Complete Example: vercel-deploy

The following is the real vercel-deploy skill — a well-structured, minimal SKILL.md that demonstrates the workflow-based pattern: 
---
name: vercel-deploy
description: Deploy applications and websites to Vercel. Use when the user
  requests deployment actions like "deploy my app", "deploy and give me the
  link", "push this live", or "create a preview deployment".
---

# Vercel Deploy

Deploy any project to Vercel instantly. **Always deploy as preview** (not
production) unless the user explicitly asks for production.

## Prerequisites

- Check whether the Vercel CLI is installed **without** escalated permissions
  (for example, `command -v vercel`).
- Only escalate the actual deploy command if sandboxing blocks the deployment
  network calls (`sandbox_permissions=require_escalated`).
- The deployment might take a few minutes. Use appropriate timeout values.

## Quick Start

1. Check whether the Vercel CLI is installed:

\`\`\`bash
command -v vercel
\`\`\`

2. If `vercel` is installed, run this (with a 10 minute timeout):

\`\`\`bash
vercel deploy [path] -y
\`\`\`

**Important:** Use a 10 minute (600000ms) timeout for the deploy command
since builds can take a while.

3. If `vercel` is not installed, or if the CLI fails with "No existing
   credentials found", use the fallback method below.

## Fallback (No Auth)

If CLI fails with auth error, use the deploy script:

\`\`\`bash
skill_dir="<path-to-skill>"
bash "$skill_dir/scripts/deploy.sh"
\`\`\`

The script handles framework detection, packaging, and deployment.

## Production Deploys

Only if user explicitly asks:

\`\`\`bash
vercel deploy [path] --prod -y
\`\`\`
Notice what this SKILL.md does well:
  • The description includes verbatim user request examples ("deploy my app", "push this live")
  • The body uses imperative form throughout
  • Steps are numbered and concrete — no abstract advice
  • The fallback section references the bundled scripts/deploy.sh explicitly
  • No redundant “when to use” section in the body (that belongs in the description)

Build docs developers (and LLMs) love

Get started for freeTalk to us