A SKILL.md file gives an AI agent a reusable way to carry out a particular kind of work. It can describe when the skill should be used, the steps to follow, the evidence to inspect and the output to produce. This guide follows one release review from a repeated prompt into a maintainable skill, then explains where skills fit beside project guidance, scripts and ordinary automation.
01
The problem is not the prompt. It is repeating the process.
AI agents are very good at responding to a clear instruction. The awkward part arrives when the same job returns next week and the instruction has to be rebuilt from memory.
Imagine a developer preparing a software release. They ask an agent to inspect the changed files, run the right tests, check database migrations, look for missing configuration, review the deployment notes and return a short risk summary. The first prompt works well, so it is copied into a document for next time.
A month later the wording has changed. One person checks migrations before the test suite, another forgets the rollback notes and a third asks for a completely different output. The agent is not necessarily the unreliable part. The process itself has no stable home.
A SKILL.md file gives that repeated procedure a name, a description and a set of instructions. Instead of recreating the release review in every conversation, the team can maintain one skill that explains what good work looks like.
That does not make the agent infallible. It does make the expected method visible, reviewable and easier to improve.
02
What SKILL.md actually is
The open Agent Skills specification defines a skill as a directory containing at least one required SKILL.md file. That file begins with YAML frontmatter and continues with ordinary Markdown instructions.
The frontmatter contains a required name and description. The name identifies the skill. The description explains what the skill does and when it should be used. This matters because a compatible agent can use the description to decide whether the skill is relevant before loading the full instructions.
The Markdown body contains the working method. It may describe the inputs to collect, the order of checks, the tools to use, common failure cases and the shape of the final answer.
A skill directory can also contain scripts, references and assets. Scripts handle deterministic work such as checking a file or formatting an output. References hold detailed rules that are only needed for certain tasks. Assets hold templates, examples or other resources used to produce the result.
The simplest description is therefore a reusable playbook for an AI agent. It is more structured than a prompt saved in a notes app, but it is still made from instructions, resources and optional code rather than new intelligence.
03
Follow one release review into a skill
Return to the release review. The team wants the agent to help decide whether a change is ready to deploy. That is a useful skill candidate because the task repeats, the method contains several steps and the final judgement still needs context.
The skill could be called release-readiness. Its description should say that it reviews a proposed release for test, migration, configuration, deployment and rollback risks, and that it should be used when somebody asks whether a branch or release is ready to ship.
The body can tell the agent to begin by reading the repository guidance and the proposed changes. It can list the required checks, require evidence for each conclusion and forbid the agent from calling a release safe merely because the automated tests passed.
A references folder might contain the organisation's deployment checklist and the rules for different application types. A script might compare expected environment variables with the example configuration or identify new database migrations. An asset might provide the exact release report template used by the team.
When the release process changes, the team updates the skill once. The next review starts from the current procedure instead of somebody's recollection of the last prompt.
That is the main value. The skill does not remove judgement. It gives judgement a consistent route through the evidence.
04
The anatomy of a useful skill
A skill can be tiny. It should only grow when the task genuinely needs more detail or supporting material.
The parts have different jobs. Keeping those jobs separate makes a skill easier to understand and prevents the main file from becoming a cupboard where every note has been pushed onto the same shelf.
| Part | Purpose | Release review example |
|---|---|---|
| Frontmatter | Names the skill and explains when it should be used | Activate for release readiness and deployment risk reviews |
| Markdown instructions | Defines the workflow, decisions and output | Read changes, run checks, record evidence and produce a risk summary |
| References | Stores detailed guidance loaded only when needed | Deployment checklist, migration rules and environment conventions |
| Scripts | Performs repeatable checks where code is clearer than prose | Compare environment variables or list pending migrations |
| Assets | Provides templates and resources used in the final work | The approved release report template |
05
Progressive disclosure is the clever part
Loading every instruction for every possible skill into every conversation would waste context and make the agent harder to steer. Agent Skills are designed around progressive disclosure instead.
A compatible agent can begin with the small amount of metadata in each skill, particularly the name and description. When the request matches a skill, it loads the full SKILL.md instructions. Supporting files are then read only when the current job needs them.
The Agent Skills specification recommends keeping the main file under 500 lines and the instructions below about 5,000 tokens. These are sensible design pressures rather than a competition to fill the allowance. A short, precise procedure is easier to follow and maintain than a long collection of loosely related advice.
Progressive disclosure also explains why the description deserves care. A vague description such as helps with releases gives the agent very little information. A useful description names the work, the likely requests and the situations where the skill belongs.
The same applies to references. A detailed security standard should not sit in the main instructions if it is only needed for security-sensitive releases. The skill can point to that reference and say when to read it.
06
Skills, prompts, project rules and automation
Not every instruction should become a skill. Choosing the wrong home creates more ceremony without making the work better.
A one-off prompt is usually enough for an isolated task. Always-on project guidance belongs with the repository instructions because it should affect work throughout the project. A script or continuous integration check is stronger when a rule must execute every time and produce a deterministic pass or failure.
A skill sits between those choices. It earns its place when the task is conditional and repeatable, contains a recognisable method, needs judgement and may draw on supporting resources.
| Option | Use it for | Main limit |
|---|---|---|
| One-off prompt | An isolated request with little reusable process | The method can drift when the task returns |
| Project guidance | Rules and context that should apply throughout one repository | It can become noisy when filled with conditional procedures |
| Agent skill | A repeatable procedure that should load for a particular kind of task | The agent still interprets the instructions and evidence |
| Script or CI check | A deterministic rule that must run consistently | Code cannot replace every contextual decision |
07
Treat skills as executable instructions
A Markdown file can look harmless because it opens like documentation. A skill may still tell an agent to run commands, read files, call services or use bundled scripts. That makes provenance and review important.
Inspect a community skill before installing it. Read the complete SKILL.md file, then check every script and referenced file. Look for network calls, external uploads, broad file access, destructive commands, secret handling and permissions that are larger than the task needs.
Project-level skills deserve the same attention. Cloning a repository does not make its instructions trustworthy. A skill committed to a project can influence how an agent works inside that repository, so it should be reviewed like code and kept under version control.
A skill is not a sandbox. It does not guarantee that a command is safe, that an external service protects the data or that the model will interpret every step correctly. The agent and its runtime still need permission boundaries, confirmation rules and technical controls.
The open specification includes an experimental allowed-tools field, but support can vary between implementations. It is better to regard that field as a useful declaration than assume it provides universal enforcement.
Where the platform supports versions, pinning or approving known skill bundles can make changes easier to review. OpenAI's current API Skills resources, for example, expose versioned skill bundles for API projects. That managed API model is separate from a local skill directory, but the principle is similar: know which instructions and resources produced the work.
08
How to write a skill that survives real use
Start with a task people already repeat. Write down the inputs, decisions, checks and output before creating the folder. If the process cannot be explained clearly to another person, wrapping it in SKILL.md will not repair it.
Keep the skill narrow enough to have one recognisable purpose. A skill called software-development that covers planning, coding, testing, deployment and client communication is unlikely to load the right detail at the right time. Release-readiness, database-migration-review or incident-summary are easier to trigger and maintain.
Use the description to say both what the skill does and when to use it. Write the body as a sequence of useful decisions rather than a motivational essay. State required evidence, safe stopping points and the final output format.
Move long reference material out of the main file. Use scripts for checks that should behave the same way every time, then make their dependencies and failure messages clear. Avoid a script that quietly changes production simply because the skill was asked to inspect it.
Test the skill with realistic requests. Check whether it activates when expected, stays out of unrelated work, reads the correct resources and returns an output somebody can use. Then review it after several real tasks. The gaps found in use are more valuable than another page of speculative instructions.
09
When a skill earns its place
A SKILL.md file earns its place when it removes repeated setup while keeping the method visible. It is useful for code reviews, document production, release checks, project handovers, research workflows and other jobs where the same judgement is applied to new material each time.
The release review is a good example because the evidence changes but the responsibilities remain familiar. The agent still has to inspect this release, understand this repository and report this risk. The skill stops the team having to redesign the route on every run.
Begin with one procedure that already matters. Keep the first skill small, review every instruction and script, and compare its output with the way an experienced person would carry out the task. If it makes the process clearer and more consistent, it can grow with the work. If it only hides a long prompt inside a folder, simplify it.
I help established businesses understand where AI automation can remove repetitive work without losing control of the underlying process. The same principle applies here: make the method clear first, then use the agent to carry it out more consistently.
Useful questions
Checks for a useful and trustworthy SKILL.md file:
- Does the skill solve one repeatable task?
- Does the description say what it does and when to use it?
- Are the required inputs and evidence clear?
- Does the workflow include safe stopping points and an output format?
- Have long references been moved out of the main instructions?
- Are deterministic checks implemented as small, reviewable scripts?
- Have every instruction, script and external call been reviewed?
- Does the skill avoid loading for unrelated requests?
- Has its output been tested against a realistic piece of work?
