The short answer
An agent skill is a reusable workflow packaged in a directory with a SKILL.md file. Its metadata tells an agent when to use it; its Markdown body explains how to do the work. Skills can include scripts and references, but they do not grant permissions or make every client behave identically.
What is an agent skill?
An agent skill is a reusable procedure that an AI agent can discover and load when a task calls for it. It lives in a directory, with a SKILL.md file at its center. That file describes when to use the skill and gives the agent instructions for carrying out the work. Supporting files can include scripts, reference documents and templates.
Think of a skill as a written playbook. A code-review skill might explain how to examine a change, which failure modes to check and how to report findings. A release skill might describe the order of checks, the artifacts to inspect and where approval is required. The skill provides the procedure; the agent still needs access to the relevant files and tools.
The Agent Skills specification defines the portable core of this format. Individual clients decide where they discover skills, how users invoke them and which extra metadata they support. A valid file is a starting point, not proof that every agent will run it identically.
Inside a SKILL.md file
The file has two parts: YAML frontmatter and a Markdown body. In the shared specification, name and description are required. The name identifies the skill; the description helps the agent decide when it is relevant.
---
name: review-pull-request
description: Review a code change for correctness and regressions. Use when asked to review a pull request or local diff.
---
# Review a pull request
1. Read the repository instructions and the diff.
2. Trace the changed behavior through its callers.
3. Check failure paths and compatibility.
4. Report actionable findings with file locations.
5. State which checks you ran and what remains unverified.This example describes a workflow without granting new permissions. It does not authorize a push, a merge or access to a private service. Those decisions remain governed by the user's instructions and the agent's environment.
Put larger reference material next to the file rather than pasting everything into the main instructions:
review-pull-request/
├── SKILL.md
├── references/
│ └── review-checklist.md
└── scripts/
└── check-links.pyReference supporting files from the skill using paths relative to its directory. A script is optional. If a few written steps are enough, the skill does not need an executable component.
Skills, prompts and repository rules
A prompt describes the work you want right now. A skill preserves a repeatable method. Repository instructions such as AGENTS.md or CLAUDE.md preserve project conventions. These overlap in subject matter, but have different jobs.
| Format | Good use | Example |
|---|---|---|
| Task prompt | A specific request and its boundaries | Review this change; do not deploy it. |
| Repository rules | Facts and conventions for this codebase | Use Bun; preserve the existing API contract. |
| Agent skill | A procedure reused across tasks | Trace a bug, reproduce it, fix it, then verify. |
| MCP server | Access to tools or external data | Read issue details from an authorized service. |
Keep project facts in the repository and put a repeatable procedure into a skill when it becomes useful across tasks. If you want the deeper distinction between instructions and tool access, read agent skills vs MCP.
How agents discover and load skills
Skills are designed around progressive disclosure. An agent can start with a skill's name and description, then read the full instructions when it selects that skill. Supporting references can be read later as needed. This helps avoid putting every workflow into every conversation.
Discovery depends on the client. Claude Code supports project and personal skill directories. Codex uses .agents/skills/ for repository skills. Cursor supports the shared directory as well as its own directories and compatibility paths. Explicit invocation also differs: Claude Code exposes skills as slash commands, while Codex provides a skill selector and dollar-prefixed mentions.
Installing a directory is therefore only half the check. Open the target agent, confirm that it recognizes the skill and ask it to perform a small representative task. Restart or reload the client if its documentation requires it.
When a skill is worth creating
A skill pays off when the same procedure recurs and the sequence matters. Good candidates include reviewing migrations, preparing release notes, checking a landing page or turning a document into a specific output format. A vague instruction such as “write good code” usually adds less than a concrete checklist with a clear end condition.
- Start with one task: choose a workflow you already perform, not an imagined library of future workflows.
- Define the trigger: say when to select the skill and when a simpler task does not need it.
- Define completion: describe the artifact or evidence the agent should produce.
- Try a failure case: make sure missing input or a failed command leads to an honest report.
Keep the library understandable
As the collection grows, the hard part becomes knowing which version is installed where. Similar names, stale copies and different agent paths make manual copying difficult to audit. Skiller provides a desktop view of installed skills, their agent targets and their content, with an editor and synchronization controls.
Start with writing your first SKILL.md, then install it in one agent before sharing it more widely. A small library with tested procedures is easier to maintain than a large collection whose behavior you have never checked.
FAQ
What is an AI agent skill?
An agent skill is a reusable procedure stored in a directory with a SKILL.md file. The agent discovers its name and description, then loads the instructions when the task calls for them.
Are agent skills the same as prompts or MCP tools?
No. A prompt describes the current task; a skill preserves a reusable procedure. MCP provides tool or data access. A workflow can combine them, but installing a skill does not configure its MCP dependencies.
How can I manage skills across several coding agents?
Skiller lets you inspect installed skills, edit their instructions and manage agent targets from a desktop library. Verify that each target agent discovers the synchronized copy.
Your skills. One place.
Inspect, edit and sync your skill library across coding agents.
Download Skiller
