How to create an AI agent skill: a practical SKILL.md guide

To create an AI agent skill, choose one repeatable task, create a folder containing SKILL.md, add a valid name and a precise description, write the shortest instructions that reliably produce the result, and test both when the skill should run and when it should not.

The file format is the easy part. The real work is deciding what behavior deserves to be packaged, what context the agent cannot infer, and how you will know the skill made the result better. If the format itself is new to you, start with what AI agent skills are.

This guide builds a small source-review skill from an empty folder to a testable bundle. It uses only the open Agent Skills fields in the core example so the workflow has the best chance of remaining portable across compatible agents.

Step 1: choose a narrow, repeated job

A good first skill is not “make my agent better at research.” It is a task with a recognizable starting point and an observable finish:

Given a draft and a set of sources, list factual claims, match each claim to evidence, and flag anything unsupported before publication.

That definition tells us the inputs, the output, and the failure condition. It is also narrow enough to test.

Use a skill when the same procedure, constraints, or corrections recur. Keep using an ordinary reusable prompt when the task is a one-off, the process changes every time, or two sentences of instruction already solve it.

Before writing files, collect three examples:

1. a normal case the skill should handle;
2. a difficult case with missing or conflicting evidence; and
3. a nearby request that should not activate the skill.

Those examples will shape the description and become the beginning of the test set.

Step 2: create the skill folder

Start with this structure:

source-review/
└── SKILL.md

The Agent Skills specification requires the folder to contain SKILL.md. Optional directories can be added later:

source-review/
├── SKILL.md
├── references/
│   └── review-rubric.md
├── scripts/
│   └── extract-links.py
└── assets/
    └── source-ledger.csv

Do not create every directory because a diagram showed them. Empty structure is not capability. Add a resource only when a real test demonstrates that the agent needs it.

Step 3: write valid frontmatter

The portable core requires name and description:

---
name: source-review
description: Reviews drafts against supplied sources and flags unsupported claims. Use before publishing an article, report, research brief, or other evidence-based document.
---

The name must match the parent directory. Under the current specification, it uses lowercase letters, numbers, and hyphens, cannot begin or end with a hyphen, and cannot contain consecutive hyphens.

The description is more important than it looks. Compatible agents read it during discovery to decide whether the full skill should be loaded. Write two things explicitly:

• what it does: reviews drafts against supplied sources; and
• when to use it: before publishing evidence-based documents.

“Helps with sources” provides neither a useful capability boundary nor strong trigger language.

Optional standard fields include license, compatibility, metadata, and the experimental allowed-tools. Use compatibility metadata when the skill genuinely requires a particular client, system package, runtime, or network connection. Do not claim broad compatibility until you have tested it.

Step 4: write instructions for the behavior you can observe

Now add the Markdown body:

## Required inputs

- A complete draft.
- The source URLs or source files the author used.

If either input is missing, ask for it. Do not search for replacement sources unless the user asks.

## Review process

1. Extract factual claims that a reader could verify.
2. Match each claim to the supplied source that directly supports it.
3. Mark a claim unsupported when no supplied source supports it.
4. Keep inferences separate from source-backed statements.
5. Return a table with claim, source, status, and next action.

## Rules

- Never invent a citation or supporting passage.
- Do not treat a source title as evidence; inspect the source content.
- Mark changing facts such as prices, versions, and policies for freshness review.
- Quote only the minimum text required to identify the evidence.

This body works because its requirements are checkable. A reviewer can see whether the output has the four columns, whether unsupported claims were marked, and whether a citation was invented.

Prefer imperatives over essays. The agent already knows general concepts; the skill should supply the workflow, local rules, exceptions, and quality bar it would otherwise miss.

Step 5: add one useful example

Examples earn their space when they resolve ambiguity. For this skill, show a claim that is only partly supported:

## Example

Draft claim: The feature is available on every plan and works without code execution.

Source says: The feature is available on every plan and requires code execution to be enabled.

Result:
- Status: contradicted
- Reason: the plan claim is supported, but the requirement is stated incorrectly
- Next action: revise the sentence to include the code-execution requirement

Do not spend half the skill demonstrating easy cases. Use examples for the boundary the agent is most likely to cross: partial support, ambiguous instructions, missing input, or an action that requires approval.

Step 6: move detail into focused resources

The specification recommends progressive disclosure: lightweight metadata is available during discovery, the full SKILL.md loads on activation, and supporting resources load only as needed.

Every line in the main file becomes context once the skill activates. If the source-review rubric grows to include policies for medical, legal, and product documentation, split those into focused files:

references/
├── medical-claims.md
├── legal-claims.md
└── product-claims.md

Then link them directly from SKILL.md and tell the agent exactly when to read each one. Keep the reference chain shallow; an agent should not need to follow five files to discover the actual rule.

Use assets/ for materials consumed or copied by the workflow, such as a document template or CSV schema. Use references/ for information the agent reads. The distinction is not enforced by Markdown, but it makes the bundle easier for humans and agents to navigate.

Step 7: add scripts only for deterministic work

A script is useful when the same mechanical operation is repeatedly re-created or when exactness matters more than interpretation. It is not a badge that makes a skill advanced.

Our source-review skill might eventually need a script that extracts and normalizes every URL in a large draft. That is deterministic, testable, and easy to fail loudly. Deciding whether a passage really supports a claim remains judgment work and belongs in the instructions and review process.

If you add a script:

• make dependencies explicit;
• validate inputs;
• return useful errors;
• avoid embedding secrets;
• restrict file and network access; and
• test it separately from the model behavior.

Remember that a third-party skill is both an instruction package and a software dependency. Readers will need to inspect both.

Step 8: test routing and results

Test at least four categories:

Test	Example	Expected result
Clear trigger	“Check this draft against these sources.”	Skill activates and returns the review table
Alternate wording	“Which claims in this brief lack evidence?”	Skill activates
Non-trigger	“Rewrite this introduction in a warmer tone.”	Skill stays inactive
Missing input	Draft supplied without sources	Skill asks for sources instead of inventing them

Then score the output itself:

• Were all material factual claims found?
• Did every supported claim point to a source that actually supports it?
• Were inferences labeled?
• Were unsupported claims preserved for review rather than quietly deleted?
• Did the result follow the requested schema?

Run the same cases after changing the description, instructions, client, or model. A routing change can improve one trigger while making the skill appear in unrelated conversations.

LLM Mart's five-case eval harness is a practical starting point for turning these examples into regression tests.

Step 9: validate and package the bundle

The Agent Skills project provides a reference validator:

skills-ref validate ./source-review

Validation checks the format and naming rules. It cannot prove that the workflow is useful, that the description routes reliably, or that bundled code is safe. Keep the behavioral tests.

Before sharing the skill:

• remove secrets, private examples, local absolute paths, and generated clutter;
• state the license and compatibility requirements;
• inspect every script and dependency;
• confirm all file references resolve;
• test from a clean environment; and
• record a version or immutable source revision.

For Claude or Claude Desktop, package the complete skill folder as a ZIP before uploading. For Claude Code, place it in the appropriate personal or project skills directory. The Claude Code skills guide documents additional client-specific fields and invocation features; add them only when the workflow needs them.

The pre-publish checklist

Before calling the skill finished, verify:

• The skill solves one named job.
• The folder name and name field match.
• The description says what the skill does and when to use it.
• The instructions are concise and checkable.
• Missing and unsafe inputs have defined behavior.
• Examples cover a meaningful edge case.
• Long details live in focused references.
• Scripts are necessary, inspectable, and independently tested.
• Positive, alternate, negative, and missing-input tests pass.
• The bundle contains no secrets or unexplained network access.

A useful skill is not the one with the most files. It is the one an agent can find at the right time, another person can inspect, and a test can prove is better than the prompt it replaced.

Sources

• Agent Skills: specification
• Agent Skills: overview
• Claude Code: extend Claude with skills