What Is an Agent Skill?
A practical definition of agent skills, how they work, and why teams use them for repeatable AI workflows.
A skill is a reusable workflow package for an AI coding agent. It usually contains a SKILL.md file with metadata and instructions, plus optional scripts, references, and assets. Good skills turn repeated work into reliable agent behavior.
The short definition
An agent skill packages specialized instructions and supporting resources so an AI agent can perform a specific job more reliably than it would from a one-off prompt.
The key idea is repeatability. If you ask for the same kind of review, QA pass, release note, or debugging workflow every week, a skill lets you codify the steps once and reuse them.
What a skill contains
- A required SKILL.md file with metadata and task instructions.
- Optional scripts for deterministic work that should not be left to prose.
- Optional references for long documentation, examples, or checklists.
- Optional assets such as templates, images, or reusable starter files.
my-skill/
SKILL.md
scripts/
references/
assets/
agents/
openai.yamlWhat skills are good for
- PR reviews that should always check the same risk categories.
- Browser QA passes that need screenshots and console checks.
- Release notes that need a stable editorial shape.
- Incident debugging workflows that should find root cause before changing code.
- Skill authoring workflows that need templates and evaluation prompts.
Use a skill when the work is repeatable, bounded, and benefits from a clear trigger. Keep one-off instructions as prompts.
What skills should not do
A skill should not become a vague personality prompt or a giant manual that tries to cover everything. The narrower it is, the easier it is for the agent to choose it correctly and follow it well.
- Avoid broad skills that trigger on almost any coding task.
- Avoid hiding dangerous shell behavior inside scripts.
- Avoid mixing unrelated workflows in one skill.
- Avoid copying large docs into SKILL.md when references can be loaded only when needed.