What Is SKILL.md? The Agent Skills File Explained

The short definition

A SKILL.md file is the required entry point for an Agent Skill: a reusable directory of instructions that an AI agent can load when a task matches the skill. The file combines YAML frontmatter for discovery with Markdown instructions for execution. A skill directory may also carry scripts, references, templates, schemas, or other assets.

The open Agent Skills specification defines the portable format. Products can extend it, but the durable core is intentionally small: a directory, one SKILL.md, a required name, a required description, and an instruction body.

Anatomy of a skill

A minimal skill looks like this:

---
name: code-review
description: Review a code change for correctness, tests, and risk. Use when a user asks for a pull-request or diff review.
---

Review changes with this workflow:

1. Read the proposed change and its tests.
2. Identify concrete defects before style preferences.
3. Cite the affected file and explain the impact.
4. End with the smallest useful verification plan.

The standard requires the directory name and name field to match. Names use lowercase letters, numbers, and hyphens; descriptions explain both what the skill does and when an agent should consider it. Optional frontmatter can declare a license, compatibility requirements, arbitrary metadata, and experimental pre-approved tools.

The body is ordinary Markdown. Strong skills make inputs, ordered steps, stopping conditions, expected output, and facts that must not be inferred explicit.

Progressive disclosure

Skills are designed to avoid loading every instruction into every conversation. An agent first sees lightweight metadata—normally the name and description. It reads the full SKILL.md only when the task matches or the user invokes the skill. Supporting files are opened only when the active workflow needs them.

This three-stage pattern is called progressive disclosure:

1. Metadata: enough information to decide whether the skill applies.
2. Instructions: the workflow loaded after activation.
3. Resources: scripts, references, and assets loaded or executed as needed.

Both the Agent Skills specification and the OpenAI skills guide recommend keeping the main file focused and moving detailed reference material into nearby files.

What can live beside SKILL.md?

The common optional directories have distinct jobs:

A skill does not need all three. An instruction-only skill is often easier to inspect and safer to adopt. Scripts are valuable when repeatability matters, but they should not replace a clear explanation of what will run and why.

What SKILL.md is not

A skill is not automatically a program, a service, or a permission grant.

• It can describe how an agent should use tools, but it does not itself create a live external connection.
• It can include executable scripts, but plain Markdown instructions do not become trustworthy merely because they are packaged as a skill.
• It can declare compatibility, but that declaration is not proof that every client supports every optional field.
• It can reference an MCP server, but the server remains a separate capability and security boundary.

This distinction is why SkillIndex records the exact source file, provenance, compatibility, and executable-content signals separately.

How agents discover skills

Discovery locations differ by product. Current Codex clients scan repository and user .agents/skills directories, while Claude Code supports project and personal .claude/skills directories. Both can activate a relevant skill automatically or let a user invoke it directly. The Codex skill documentation and Claude Code skill documentation describe their current paths and product-specific extensions.

Treat installation paths as client configuration, not part of the portable skill itself. Keep the skill directory valid against the open specification so it can be reviewed or adapted across compatible clients.

A practical review checklist

Before using a downloaded skill:

1. Confirm the profile points to an exact SKILL.md, not merely a repository that mentions skills.
2. Read the frontmatter and make sure the description matches the actual workflow.
3. Inspect every referenced script and follow its dependencies.
4. Identify filesystem, network, credential, shell, and destructive-action requirements.
5. Check the source owner, license, commit, and last verification date.
6. Start in a disposable repository or test environment.
7. Keep approval prompts around writes, publishing, credentials, and production access.

A well-formed file proves format compliance, not safety or quality. Source identity, maintenance, and observed behavior still matter.