What is SKILL.md?

SKILL.md is the main instruction file inside an Agent Skill. It combines structured metadata with Markdown instructions that tell an AI agent how to perform a specialized task.

Think of a Skill as a reusable capability for an AI agent, with SKILL.md as its main instruction file.

What is an Agent Skill?

An Agent Skill packages instructions and optionally scripts, references and assets that help an AI agent perform a specialized task.

Examples could include skills for:

SKILL.md directory structure

my-skill/
│
├── SKILL.md
├── scripts/
├── references/
└── assets/

Only SKILL.md is required. The other directories can be added when the skill needs additional resources.

SKILL.md format

A SKILL.md file starts with YAML frontmatter followed by Markdown instructions. 

---
name: code-review
description: Reviews code for quality, maintainability and common issues. Use when reviewing source code or pull requests.
---

# Code Review

## Instructions

1. Understand the purpose of the change.
2. Inspect the relevant code.
3. Identify correctness and maintainability issues.
4. Suggest focused improvements.
5. Explain important findings clearly.

Required metadata

Field Purpose
name Identifies the skill.
description Describes what the skill does and when it should be used.

The Agent Skills specification requires both fields. Additional optional metadata can also be included.

Why the description matters

The description explains what the skill does and when it should be used. A precise description therefore helps an agent identify when the skill is relevant.

SKILL.md vs AGENTS.md

File Main role
SKILL.md Defines a reusable specialized capability.
AGENTS.md Provides instructions for agents working inside a repository.

SKILL.md vs PROJECT-GOALS.md

File Main question
PROJECT-GOALS.md What should this project achieve?
SKILL.md How should an agent perform this specialized task?

A modern AI project structure

my-project/
│
├── README.md
├── PROJECT-GOALS.md
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
│
├── .github/
│   └── copilot-instructions.md
│
└── skills/
    │
    └── code-review/
        ├── SKILL.md
        ├── scripts/
        └── references/
Goals define the destination. Skills define capabilities.

Use PROJECT-GOALS.md to keep the project's objectives and boundaries clear alongside agent-specific instructions and reusable skills.

Generate PROJECT-GOALS.md

Related guides