Skip to main content

📝 Skills & SKILL.md

Description​

< What are Agent Skills? >​

Agent Skills are reusable folders that give an AI agent task-specific knowledge and workflows. Each skill has a required SKILL.md file with name, description, and instructions; it may also include scripts, references, templates, and other assets.

< Why use them? >​

  • Domain expertise: package organization- or task-specific knowledge.
  • Repeatable workflows: make multi-step work more consistent and easier to verify.
  • Progressive disclosure: an agent first sees a skill’s name and description, then reads its full instructions only when the skill is relevant.

< How do they work? >​

  1. Discovery: the agent sees a skill’s name and description.
  2. Activation: the agent loads the full SKILL.md when the task matches.
  3. Execution: the agent follows the instructions and may use bundled resources.

< Prompt vs. skill >​

A prompt describes the request at hand. A skill describes a reusable way to perform a class of requests.

AspectPromptSKILL.md
PurposeDescribe what to do nowDescribe how to perform a reusable workflow
LifetimeUsually one request or conversationPersists as a reusable capability
ActivationSent directly in the requestSelected explicitly or when its description matches the task
ContentTask, context, constraints, and desired outputMetadata, procedures, rules, references, and tool guidance
Supporting filesUsually noneMay include scripts, templates, examples, and assets
Example“Create a sales report from this CSV”A sales-report skill that explains how to analyze, format, and verify reports

A SKILL.md still contains natural-language instructions. The user’s prompt supplies the concrete objective, inputs, and task-specific requirements.

Prompt: what the user wants
             ↓
Skill: reusable knowledge about how to do it
             ↓
Task-specific result

Key points​

< When should I use a skill? >​

  • Use a normal prompt for one-off work.
  • Create a skill for a recurring workflow, especially one that needs consistent steps, scripts, templates, or verification rules.

< A minimal skill structure >​

sales-report/
├── SKILL.md
├── scripts/
│   └── build_report.py
├── references/
│   └── metric_definitions.md
└── assets/
    └── report_template.xlsx

SKILL.md must include name and description in its frontmatter:

---
name: sales-report
description: Create a formatted sales report from CSV or Excel data.
---

# Instructions

1. Validate the source data.
2. Calculate the required metrics.
3. Use the report template.
4. Verify formulas before delivery.

A user can then write: Use the sales-report skill to create the August report from sales.csv.

< Where should SKILL.md go? >​

  • Project-specific: .agents/skills/<skill-name>/SKILL.md — commit it to the repository for the team.
  • Personal: $HOME/.agents/skills/<skill-name>/SKILL.md — available across your projects.
  • Machine-wide: /etc/codex/skills — for shared administrative skills.
  • Distribute broadly: package the skill as a plugin.

Codex scans .agents/skills from the current working directory up to the repository root. The filename must be exactly uppercase: SKILL.md.

Reference​