01
Write valid frontmatter
Create stable skill names and concise descriptions that state the use case, trigger terms, exclusions, and important boundaries.
SKILL.md authoring
CategoryAI & Codex Skills
Codex Skills Markdown File
Codex Skills Markdown File guidance helps you write the SKILL.md file that defines when a Codex skill should activate and what workflow it should follow. Download the skill for clear frontmatter, concise instructions, progressive disclosure, useful references, output requirements, boundaries, and verification steps.
SKILL.mdYAML frontmatterSkill triggersProgressive disclosure
01
02
03
04
05
06
07
08
09
02
03
04
05
06
07
08
09
task: complete skill.md authoring task
inspect:
- requirements and context
- existing standards
- failure and edge cases
verify: outputs + checks + handoffWhy a specialist workflow matters
A long SKILL.md can still be ineffective when its description does not trigger correctly, important steps are buried, and the workflow cannot tell when it is finished.
SKILL.md is the required file in a Codex skill folder and includes name and description frontmatter plus the workflow instructions.
This skill helps authors write a strong trigger description, choose the right amount of freedom, route detailed material into references, and make outputs and checks explicit.
What the downloadable skills can do
What Codex Skills Markdown File can help accomplish
02
Structure actionable instructions
Organize prerequisites, context gathering, workflow steps, decisions, outputs, quality requirements, failure handling, and completion checks.
03
Use progressive disclosure
Keep core instructions compact while routing specialized knowledge, examples, scripts, templates, and assets into supporting files.
04
Review and test the file
Check ambiguity, conflicting instructions, token cost, path references, dependencies, explicit invocation, implicit matching, and realistic outputs.
A repeatable working process
How the skill.md authoring workflow moves from request to verified result
The steps keep context, implementation, and verification visible so the result can be reviewed and repeated.
workflow.statusREADY
Context → Plan → Work → Verify
01
Define the skill contract
State when the skill should and should not run, what inputs it needs, what it produces, and how success is verified.
02
Draft frontmatter for discovery
Use a unique name and front-load the description with the task, audience, trigger terms, and relevant exclusions.
03
Write the smallest useful workflow
Make steps concrete, distinguish required actions from judgment calls, and move detail into references where appropriate.
04
Test and revise from behavior
Run representative and near-miss prompts, inspect activation and artifacts, then change the file based on observed failures.
Useful across real projects
Where Codex Skills Markdown File fit
The workflow adjusts to the project, audience, tools, and risk while preserving the same quality standard.
Instruction-only skills
Package a reusable decision process or checklist without adding scripts or external dependencies.
Tool-backed skills
Explain when and how to use bundled scripts, formats, connectors, commands, and verification procedures.
Knowledge-heavy skills
Keep specialized reference material outside the main file and load only the sections needed for the task.
Artifact skills
Define finished documents, sites, code, images, reports, or other outputs with suitable quality checks.
Common requests
Tasks these skills can handle
Start with one defined outcome and provide the source material, constraints, and checks that matter.
01Create SKILL.md frontmatter
02Improve a skill description
03Organize workflow instructions
04Move details into references
05Document scripts and dependencies
06Add output and verification rules
07Reduce unnecessary skill length
08Test skill triggering
Who benefits most
Who Is This For?
These skills are designed for people who need dependable skill.md authoring work with a visible process.
New skill authors
Create a correct, understandable first skill without overloading the main instruction file.
Experienced Codex users
Improve triggering, context efficiency, failure handling, and output consistency.
Teams maintaining shared skills
Standardize frontmatter, workflow sections, dependencies, review, and testing.
Plugin authors
Prepare skill folders that can later be bundled and distributed through a plugin.
Good to know:
A well-written SKILL.md improves guidance but cannot supply missing tools, permissions, credentials, project context, or validation environments. Bundled scripts and external sources still require review.
Set up the workflow
Installation Guide
Install the complete skill folder and add the project-specific context before beginning.
Download and extract the SKILL.md authoring skill
Keep its examples, review checklist, progressive-disclosure guidance, and test prompts together.
Choose the target skill scope
Decide whether the new skill belongs in a repository, user collection, managed environment, or distributable plugin.
Write the required frontmatter
Add a stable name and a concise description that explains exactly when the skill should and should not trigger.
Validate with representative prompts
Test explicit invocation, implicit matching, near misses, missing inputs, outputs, and completion behavior.
Before you download
Frequently Asked Questions
Practical answers about capabilities, limits, setup, and review.
What is the required Codex skills Markdown file called?+
The required file is named SKILL.md and lives inside the skill folder.
What frontmatter is required?+
The file must include name and description fields in YAML frontmatter.
How long should SKILL.md be?+
Only as long as needed to guide the workflow. Put detailed references, examples, scripts, and assets in separate files.
Why is the description important?+
Codex uses the skill name and description for discovery and implicit matching before loading the complete instructions.
Can SKILL.md run code?+
The file provides instructions and can direct Codex to bundled scripts or tools, but those resources must exist and be reviewed separately.
Make the work repeatable
Give every Codex skill a Markdown file with a precise trigger, an efficient workflow, clear boundaries, and a result that can be checked.
Clear context. Purposeful work. Relevant checks. A result others can understand.