To create an AI agent skill, make a folder with one file, SKILL.md: front matter with a name and a one-line description, then plain instructions. The description is the important part, because the agent reads only that line until a task matches it, and only then loads the rest.
This article is for developers who find themselves typing the same instructions into a coding agent every week: the same checks, the same file layout, the same warnings. The everyday problem is that the agent forgets all of it between sessions, so every run starts from zero and comes out slightly different. A skill writes those instructions down once, in a file the agent loads when the job comes up, so the work runs the same way each time and your teammates get the same behaviour.
We run 23 skills in the studio that makes this site, and the same files serve two different coding agents. Below is the format, a worked example, and the mistakes we made with our first skills.
The format
--- name: plain-english-check description: Check a draft for plain English before publishing. Use when someone asks to review, proofread or simplify an article. --- # Plain English check 1. Read the text once without editing. 2. Mark each AI tell: forced triads, staged openers, filler. 3. Rewrite only the marked lines. Keep every fact and number. 4. Check: no new claims, no lost numbers. That is a complete, if small, skill (a shortened example, not one of ours word for word). In Claude Code, a project skill lives at .claude/skills/<name>/SKILL.md. Extra files (scripts, examples, a style guide) can sit in the same folder, and the steps can point to them. Project skills travel with the repository, so everyone who clones it gets them; keep personal habits out of the project folder and team rules in it. Check the skill into version control like code, and review changes to it in pull requests, because a changed step changes what every agent does next time.
Why does the description of a skill decide whether it loads?
An agent cannot read 23 long instruction files before every task; that would fill its context. So it keeps a short list of names and descriptions, and loads a full skill only when your request matches one.
The description does the routing. It is the line the agent matches your request against, so write it for matching, not as a summary of the file. Compare:
| Description | What happens |
|---|---|
| "Video helper" | Rarely loads, because nothing matches it |
| "Render an approved episode into its Short. Use when the owner says make the video or render episode sd-N." | Loads exactly when someone says "make the video" |
The second one is our real make-video skill. It names the job and the words people use to ask for it.
Matching a request to the right capability by a short description is also how MCP tool discovery works, where a client finds new apps with no changes to its own code.
One file, two agents
Our studio runs two coding agents. Claude Code reads .claude/skills natively. Codex CLI runs our cloud automation, and its prompt carries one extra line: when the task names a SKILL.md file, read it and follow it.
So the same make-video/SKILL.md (735 words) drives a render whether Claude or Codex does the work. When we change the steps, both agents get the change on their next run, because they read the same file. This is why we like the format: the file is plain Markdown, so it is not tied to one vendor's feature set, and it still works if you change agents.
Our studio runs two coding agents; how we use both AI coding agents together is covered in its own piece, and this article is about the files they share.
How we write a skill now
- Do the job by hand once and write down the steps you actually took.
- Name the trigger in the description: the words a person types when they want this job.
- Write steps. Numbered, one action each, with the exact command or file path, not paragraphs of advice.
- Add the checks at the end: what "done" looks like, and what must never change.
- Point to files instead of pasting them: scripts and style guides live next to SKILL.md.
- Test with a plain request that does not name the skill. If it does not load, fix the description, not the steps.
Mistakes we made
- Vague descriptions. Our first skills said what they were, not when to use them, so they loaded late or never.
- Too long. A skill that tries to cover three jobs loads for all three and confuses each. Split it.
- Rules without checks. "Write simply" does nothing; "no sentence over 25 words, count them" works.
Our take
Most people will install a hundred skills and use four. What matters is simpler: does each skill have a description that fires at the right moment, and steps that end in a check? Four skills that load at the right moment will do more work than a hundred that sit unused.
Honest verdict
Good: plain Markdown, works with more than one agent, easy to review in a pull request, and it writes down the steps one person knows so anyone on the team can run them.
Worth knowing: a skill is only as good as its description, long skills cost context when they load, and an agent can still skip a step, so the checks at the end matter.
What it means for you
Pick the one job you explain to an agent most often. Write it as a SKILL.md today with a trigger-style description and a check at the end. Use it for a week, then fix the description based on when it failed to load.
