How to build an AI agent skill

To build an AI agent skill, choose one repeated job, create a lowercase folder with SKILL.md, add the required name and description, write the workflow and stop conditions, then validate the package before testing it in an agent. Start with instructions only. Add scripts or references when the job proves it needs them.

Starting small exposes whether the method is clear. A large template can make an unfinished process look complete. A useful skill starts with a job you understand well enough to define its input, output, evidence, and failure cases.

Start with one job you already understand

Do not start with "build a marketing skill" or "make a coding assistant." Pick one result you can inspect.

This guide uses a release-note check. Its job is narrow: compare a draft software release note with supplied change evidence, correct supported wording, and flag claims the evidence does not support. It must stop when the evidence is missing.

Write the contract before the file:

• Input: one draft release note and the change evidence behind it.
• Output: a checked note plus unsupported or missing details.
• Required judgment: distinguish user-visible changes from implementation detail.
• Stop condition: no source evidence, no rewritten claim.

If you cannot state those points yet, keep using a prompt. The workflow is still moving. Our guide to deciding whether you need an AI skill covers that earlier decision.

Create the smallest valid skill

The open Agent Skills specification starts with one directory and one required file:

release-note-check/
└── SKILL.md

SKILL.md needs YAML frontmatter followed by Markdown instructions. The minimal frontmatter has two fields:

---
name: release-note-check
description: Reviews a draft software release note against supplied change evidence. Use when checking whether a release note names the shipped change, user impact, and any required upgrade step without inventing claims.
---

The name must match the parent folder. It can contain lowercase letters, numbers, and single hyphens, with a maximum of 64 characters. It cannot start or end with a hyphen or contain two hyphens in a row. The description must be present, stay within 1,024 characters, and explain both the job and when to use it.

The description is routing metadata. Compatible agents may use it to decide whether the skill fits a request. "Checks writing" gives the agent little to match. The example names the artifact, the evidence check, and the failure it should avoid. Read how AI skills work for the discovery and activation sequence.

Write instructions an agent can follow

The Markdown body should contain the method, not a motivational description of the role. For the example skill, the complete workflow can stay short:

Review one draft release note and the supplied change evidence.

1. Confirm that every claimed change appears in the evidence.
2. State the user-visible effect in plain language.
3. Include an upgrade step only when the evidence requires one.
4. Flag any unsupported claim instead of rewriting it as fact.

Return the checked release note, followed by a short list of unsupported or missing details. If no change evidence is supplied, stop and ask for it.

For an instruction-only first version, this is enough. It names the input, decision sequence, output, and stop condition. It does not ask the agent to "be thorough" or "act as an expert" without explaining what either phrase means.

Use the same test on your own workflow. A useful SKILL.md should tell another person what evidence matters, which decisions repeat, what the result looks like, and when the agent must stop. If the answer depends on a product rule or rubric, name the source instead of relying on general model knowledge.

Add files only when they remove real ambiguity

scripts/, references/, and assets/ are optional. Empty directories do not make a skill more complete.

Add a reference when detailed material would bury the main workflow. A code-review skill may need a repository-specific risk rubric. Add a script when a deterministic check is safer or cheaper than asking the model to reproduce it, such as validating JSON against a schema. Add an asset when the result needs a template or starter file.

Reference each file from SKILL.md with a relative path and say when to read or run it. The specification recommends keeping references shallow and SKILL.md under 500 lines so the agent does not load unrelated material. OpenAI's current skill authoring guide also treats instruction-only as the default.

Do not add code merely because the format permits it. Every script adds dependencies, permissions, failure paths, and review work. The release-note example needs none.

Validate the package before testing behavior

Run the reference validator from the skill's parent directory:

skills-ref validate ./release-note-check

For the sample built for this article, the validator returned Valid skill. A second local validator also accepted the folder. The checked package had one file, a matching 18-character name, a 207-character description, valid frontmatter, and a non-empty Markdown body.

The run also tested a deliberately invalid sibling named Release--Note-Check. The reference validator rejected it because the name used uppercase letters and consecutive hyphens. That failure proves the validator does more than check for a file named SKILL.md.

Package validation has a narrow meaning. It proves that the frontmatter and naming follow the format. It does not prove that the instructions route correctly, produce a useful result, avoid unsafe behavior, or work the same way in every host.

Test routing and output separately

Install the valid folder in one supported agent, then run three different tests:

1. Invoke the skill by name with a representative draft and evidence. Check whether it follows the method and returns the promised shape.
2. Ask for the same job in ordinary language. Check whether the description routes the request to the skill.
3. Ask for nearby work that should not use the skill, such as writing a release plan. Check that it stays out of the way.

Then test the work itself. Supply one complete case, one case with an unsupported claim, and one case with no evidence. A correct package may still produce weak results. Record the input, agent and model, expected checks, actual output, and failures before revising the instructions.

Hosts differ. OpenAI and Claude Code both support skills, but each host controls discovery paths, extra frontmatter, tools, permissions, and invocation behavior. Keep the portable core in SKILL.md, then document and test every host-specific claim. The Codex installation guide shows one concrete install path.

Build for inspection before you sell it

A buyer should not have to reverse-engineer the package to understand the job. State the expected input, output, included files, dependencies, permissions, compatible hosts, example result, and known limits. Show enough of the method to make the promise testable.

Schema validity is only the first piece of evidence. A paid skill should also have representative cases, failure behavior, readable scripts, and a maintenance plan where the surrounding tools can change. Do not promise that a validator proves safety or effectiveness.

When the method survives those tests, you can browse AI skills on Capabase to compare how other creators describe scope, dependencies, examples, and limits before packaging your own.

Common questions

Do I need to write code to build an AI agent skill?

No. An instruction-only skill can be useful when the job is reading, checking, classifying, or drafting from supplied material. Add code when a deterministic operation or external tool is genuinely part of the workflow, then document its dependencies and permissions.

What is the minimum valid Agent Skill?

A directory containing SKILL.md with valid YAML frontmatter, a required name and description, and Markdown instructions. The name must follow the specification and match the directory. Scripts, references, and assets are optional.

Does a valid skill work in every AI agent?

No. Format validation checks the portable package shape. Each host decides where it discovers skills, which extensions it accepts, what tools are available, and how activation works. Test every host you claim to support.