AI Agent Skills and Skills.md Development

How a Skill Is Packaged on Disk

On disk, a skill is a Markdown file with a YAML frontmatter block at the top. The frontmatter carries the identifying fields, typically a name and a description; everything below it is the procedure in ordinary prose. Scripts, templates, and reference documents sit beside it in the same directory and are called by relative path, which is what makes a skill a folder you can move rather than a file with dependencies scattered around the repository.

Loading is selective, and that is a context budget decision rather than a stylistic one. What is resident at the start of a session is the short identifying text, not the body; the body is pulled in when the task appears to match. A library of thirty skills whose bodies were all permanently present would spend the context window on procedures that have nothing to do with the task in front of it.

So write the description for the router. It should name the conditions that should trigger it, in the words someone would actually use when the situation arises. "Helps with documents" gives the matcher nothing to work with. "Extracts line items from vendor invoices in PDF form and checks them against the purchase order" names the artifact, the format, and the check, and those are the words that will appear in the request.

• Keep the body short and push long reference material into separate files the procedure points to, so the detail arrives at the step that needs it rather than at the top.
• Reference scripts and files by path relative to the skill's own directory, so the folder can be moved or renamed in one operation.
• Frontmatter is parsed as YAML, so a colon inside an unquoted description value, or a tab character used for indentation, is a parse failure rather than a soft warning.
• Write steps as imperatives with one action each. A sentence joining two actions with "and" is where a step gets half done.

Push the Fragile Steps into Code

Any step with exactly one correct answer should be a script the skill calls, not a sentence the agent interprets. Date arithmetic across month boundaries, currency rounding, ID and checksum formats, sort orders, schema validation, and anything with a lookup table behind it.

The dividing line is judgment against determinism. A model reading "round half up to two decimals" will usually do it correctly, and "usually" is the problem for a step that runs a few hundred times. Prose also cannot be tested on its own. A script has unit tests and can be run against the awkward inputs directly, without invoking the agent at all.

The failure signatures differ as well. A script that breaks raises an error with a line number and stops. A prose instruction the model reads differently on one run produces a well-formed answer that is wrong in a way nothing flags.

• Have the script validate its own output shape and exit non-zero when the shape is wrong, so the next step cannot proceed on a bad value.
• Put retry and pagination logic inside the script. A procedure telling the agent to keep fetching until it is done is a loop with no bound.
• Keep the script interface small: named arguments in, structured text out. The agent has to construct the call from prose, and every optional flag is another chance to construct it wrong.
• Leave the judgment in the procedure. Which exception is worth escalating, which of two conflicting sources to trust, when output is not good enough to send: those do not reduce to encodable rules, and pretending otherwise produces a script full of thresholds nobody can defend.

What the Build Needs From You

The filter earlier on this page comes first: if the procedure cannot be written down clearly enough for a new hire, it will not survive being turned into a skill, and the writing is worth doing on its own terms. What a handed-over document does not contain is the part its author does not know they are doing: the check they run without thinking, the input they discard on sight, the case where they quietly go ask someone. The document is the input, and one session watching the procedure run is what fills in around it. That session is the one part of this work that cannot be done asynchronously.

Access is the other dependency, and read-only is enough for most of the build. A procedure can be written, run against past work, and argued about before the skill ever holds a credential that can change anything. Where the systems hold regulated or customer data, a copied subset with the same shape usually makes a better test bed than the live one, because the awkward inputs can be constructed instead of waited for.

• Completed outputs from past runs, plus the reason each one passed review. The reason is what the test cases actually compare against; the output alone only tells you the shape.
• Who is allowed to approve the steps the procedure stops on, stated by role, because the skill has to name it rather than say "get sign-off".
• What the procedure should do when two inputs disagree: a precedence order, or a stop. Left unstated, the agent will pick one and the pick will not be recorded.
• Who owns the skill afterward, decided while the procedure is being written rather than at handover, since the owner is usually the person whose corrections shape it.

What the Procedure Does When a Step Cannot Run

Most written procedures describe the path where everything is present. An agent will follow that path even when the preconditions are not met, because an incomplete input still permits a plausible answer. The procedure has to say, inside the step itself, what missing looks like and what to do about it: stop and report which precondition failed, or continue with a named default.

The distinction worth writing down is between a step that can be skipped and a step that invalidates everything after it. Skipping an optional enrichment lookup changes how complete the output is. Skipping the check that the source data covers the period being reported changes whether the output means anything, and there the procedure should refuse rather than continue. If that difference is not in the file, the agent decides it for you, differently on different runs.

Partial results need a label, and the label has to be in the output rather than in someone's memory of the run. Say which fields are populated, which are marked unknown, and that unknown is written out explicitly, because a blank field reads as a value that happened to be empty.

• Put the precondition in the step, not in a preamble. A list of checks at the top of a long procedure gets read once and applied loosely.
• Distinguish "not found" from "not checked" in the output. They lead to different next actions and both otherwise look like an absent value.
• Give stop conditions a fixed phrase that can be searched for, so incomplete runs can be found later without reading each one.
• Where a step calls an external system, say what happens on a timeout as distinct from an error. A timeout may mean the other side already did the work, which makes a blind retry the wrong default.

Steps That Were Workarounds for an Older Model

Procedures accumulate lines written to route around a limitation that no longer exists. Chunk the input into small pieces. Restate the question before answering. Do not attempt the table, produce a list instead. They quietly cost context, constrain the output shape, and go on being followed precisely because the skill is doing its job.

They persist because the file records the instruction and not the reason for it. Six months later the constraint reads as deliberate, and the reasoning cannot be reconstructed afterward by someone reading the file cold, so nobody removes it. Write the reason beside the constraint when you add it, in one clause, including what you saw that made you add it.

When the underlying model changes, those annotations become a work list. Take the constraints one at a time, remove the workaround, run the stored test cases, and keep the removal only where every test still passes.

• Date the constraint, or name the model version it was written against. Without that, the annotation is an opinion of unknown age.
• Formatting scaffolding is the usual survivor: the schema restated before every item, examples repeated for each field, explicit instructions to emit valid JSON.
• Instructions that ban a tool are worth rechecking early, because a banned tool is usually replaced by a longer manual procedure somewhere else in the same file.
• A workaround removed in one skill is usually present in several. Search the library for the phrase before assuming it was local to the file you are editing.