Codex · Chapter 01

Teach Codex your workflow. One folder at a time.

A no-jargon, build-along guide to Agent Skills—written for Indian developers in English and Hindi.

Start the 20-minute trail Jump to the example

No API key required · Basic Markdown is enough

OPEN FORMAT

my-skill/ ready

M↓ SKILL.mdRequired · instructions + metadata

›_ scripts/Optional · repeatable code

¶ references/Optional · details on demand

◇ assets/Optional · templates and resources

A skill is a folder. SKILL.md is the only required file.

The 30-second answer

What is an Agent Skill?

A lightweight, portable folder that gives an AI agent specialised knowledge or a repeatable workflow. Codex discovers the skill from its name and description, loads its full instructions when relevant, and can then use its scripts or references as needed.

Think: README + playbook + toolbox —loaded only when useful.

Follow the trail

From idea to a working skill

Four short stops. Each one gives you something you can use immediately.

01

3 min · Mental model

How Codex decides

Skills use progressive disclosure, so the agent only loads the detail it needs.
02

5 min · Anatomy

Write the smallest useful file

Good metadata gets the skill selected. Clear instructions make it useful.
03

7 min · Build

Create it in the right place

Use a repository skill for a team workflow, or a user skill for yourself.
04

5 min · Test

Prove it helps

Check both triggering and output quality—including near-misses.

Mental model

Progressive disclosure: the idea that makes skills scale

Codex does not paste every skill into every conversation. It reveals the skill in stages.

A

Discover

At startup, the agent sees the skill's name and description—enough to judge relevance.

name + description
B

Activate

When the task matches, Codex reads the complete SKILL.md instructions.

SKILL.md
C

Execute

Only then does it load a referenced file or run a bundled script if the workflow needs it.

scripts/ · references/

Practical consequence

Your description is not marketing copy. It is routing logic. Say what the skill does, when it should run, and—when useful—where its boundary ends.

Anatomy

Start small. Add folders only when they earn their place.

DIRECTORY MAP v1

my-skill/
├── SKILL.md          # required
├── scripts/          # executable code
├── references/       # detailed docs
├── assets/           # templates/files
└── agents/
    └── openai.yaml   # Codex metadata

Must have

SKILL.md

YAML frontmatter with name and description, followed by Markdown instructions.

Add when

scripts/

A step needs deterministic behaviour or external tooling. Keep scripts non-interactive.

Add when

references/

Detailed material would make SKILL.md long. Keep references focused and one link deep.

Add when

assets/

The workflow reuses templates, schemas, lookup data, images, or other output resources.

64max name characters
1024max description characters
<500recommended SKILL.md lines
1 levelrecommended reference depth

Specification note: The name must use lowercase letters, numbers, and hyphens, match its parent folder, and contain no consecutive hyphens.

Build along

Create an incident handoff skill

This community example is deliberately small: it turns messy on-call notes into a crisp next-shift brief, with IST and UTC times kept explicit.

ORIGINAL EXAMPLE · NOT AN OFFICIAL OPENAI SKILL

Choose the scope

Put it in the repository when the whole team should use the same handoff. Put it in your home folder when it is personal.

.agents/skills/incident-handoff/ team

~/.agents/skills/incident-handoff/ personal

Create SKILL.md

For a first version, instructions alone are enough. Do not add a script just to make the folder look complete.

Invoke and observe

Mention the skill explicitly while developing. Then try natural prompts to test whether the description activates it implicitly.

$incident-handoff turn these notes into the next shift brief

---
name: incident-handoff
description: >
  Create concise engineering incident handoffs from logs,
  timelines, and notes. Use when the user asks for an
  on-call handoff, incident summary, status update, or
  next-shift brief. Do not use for root-cause diagnosis.
---

# Incident handoff

1. Read every provided note before drafting.
2. Preserve timestamps. Show IST and UTC for distributed teams.
3. Separate confirmed facts, hypotheses, and open questions.
4. List actions with an owner; use “unassigned” when unknown.
5. Never invent an owner, cause, metric, or resolution.

## Output

- Current status
- User impact
- Timeline
- Actions taken
- Next actions and owners
- Open questions

## Final check

Verify that every claim is supported by the input.

Description lab

A description has three jobs

WHATCreate incident handoffs
WHENHandoff, status, summary, next shift
BOUNDARYNot root-cause diagnosis

Test and improve

A skill is not done when it works once

TEST A

Does it trigger correctly?

Use realistic prompts that should trigger and close near-misses that should not. The boundary is where weak descriptions fail.

SHOULD Can you turn these PagerDuty notes into a handoff for the 8pm IST shift?

SHOULD NOT Find the root cause of this memory leak and patch it.

TEST B

Does it improve the result?

Run the same task with and without the skill. Define observable success before you fall in love with the output.

All timestamps from the input are preserved
Facts and hypotheses are separated
No owner or root cause is invented
Next actions are easy to scan

PRACTICAL RECIPE

A sensible first evaluation

2–3output test cases to begin
~20trigger queries when tuning descriptions
3×runs per query as a starting point
A/Bcompare with skill vs without

These are starting points from the Agent Skills creator guides, not hard protocol requirements.

Field notes

The advice people usually learn the hard way

Official constraints, plus practical implications made explicit.

01Treat descriptions like routing rules

Name the user's intent and likely vocabulary. Test close negatives, not silly unrelated prompts. A broad description can be as harmful as a narrow one.

SPEC + CREATOR GUIDE

02Keep instructions imperative and checkable

Write explicit inputs, steps, and outputs. End with checks the agent can actually perform. “Make it good” is not a verification step.

OPENAI BEST PRACTICE

03Use scripts for certainty, not decoration

A script should accept flags, environment variables, or stdin—never block on a prompt. Give it concise --help output and errors that explain the next move.

CREATOR GUIDE

04Separate stable instructions from deep reference

If SKILL.md keeps growing, move domain tables, schemas, and long examples into focused reference files. Link directly; avoid chains of files pointing to more files.

SPECIFICATION

05Duplicate names do not merge

Codex can show both skills when names collide. Give team skills distinctive names, especially when a user-level skill may cover similar work.

CODEX DOCS

06Keep sensitive Indian data local

Skills for bank statements, Aadhaar-linked records, customer exports, or production logs need a clear data-handling rule. Never bundle real secrets or customer data as examples.

EDITORIAL SAFETY NOTE

Before you ship

Your first-skill checklist

Tick each item as you go. Your progress stays in this browser.

READINESS0 / 7

One clear job and a defined boundary Folder name matches the lowercase skill name Description says what and when Steps name inputs, outputs, and checks Long details live in focused reference files Positive and near-miss trigger prompts tested Output compared against a no-skill baseline

What comes next

Codex first. Open format by design.

This guide starts with Codex locations, invocation, and metadata. Agent Skills are an open format adopted by multiple agent products, so future chapters can add client-specific setup without rewriting the core lessons.

01 Codex available now
02 Other agents later

Grounded in primary sources

Read the originals

Facts are linked to official documentation. Original examples and editorial advice are labelled on the page.

01 OpenAI · Build skillsCurrent Codex behaviour, locations, creation, distribution 02 OpenAI · Create a skillCreator flow and minimal SKILL.md 03 Agent Skills · Open standardFormat, progressive disclosure, creator guidance 04 Agent Skills · SpecificationNaming, metadata, directory, and validation rules 05 openai/skills · Archived catalogDeprecated—use for examples, not current setup guidance

Teach Codex your workflow. One folder at a time.

What is an Agent Skill?

From idea to a working skill

How Codex decides

Write the smallest useful file

Create it in the right place

Prove it helps

Progressive disclosure: the idea that makes skills scale

Discover

Activate

Execute

Start small. Add folders only when they earn their place.

SKILL.md

scripts/

references/

assets/

Create an incident handoff skill

Choose the scope

Create SKILL.md

Invoke and observe

A description has three jobs

A skill is not done when it works once

Does it trigger correctly?

Does it improve the result?

A sensible first evaluation

The advice people usually learn the hard way

Your first-skill checklist

Codex first. Open format by design.

Read the originals