Agent skills for AI coding agents: how they work, how to write one, and where they stop

Halfcycle is a module that runs a five-layer build method inside your own Claude Code or OpenAI Codex (npx halfcycle).

Every coding agent starts a session knowing nothing about how your team works. You can tell it everything up front, in a long instructions file that it reads before every task, or you can teach it in small pieces it picks up only when the work calls for them. Agent skills are the second way.

A skill is a folder with one file in it that matters, SKILL.md: a name, a one-line description, and the instructions for one job. The agent sees the name and description of every installed skill from the start of the session. It reads the rest only when a task matches. That one design choice, a short line always visible and the detail held back until needed, is why skills spread to most coding agents within a few months.

Why skills matter now that agents write the code

Before agents, a team's know-how lived in people. How we write migrations, which checks run before a release, why the payments module never calls the clock directly. A new engineer picked it up over months, from reviews and from being told.

An agent does not pick anything up between sessions. Whatever it needs, it has to be given, every time. The first answer most teams reach for is one big instructions file, CLAUDE.md or AGENTS.md, and it works until it does not. Every line in it is read before every task, relevant or not, and every line competes for the agent's attention with the task itself. The file grows, the agent follows less of it, and somebody starts deleting rules to make room.

Skills move the occasional knowledge out of that file. The migration procedure loads when somebody asks for a migration and stays out of the way otherwise. The always-true rules stay in the instructions file; the sometimes-needed procedures become skills. That split is most of the value.

Three things people mean by "agent skills"

The phrase is used for three different things, and arguments about whether skills work are often two people meaning different ones.

The format. A folder with a SKILL.md file, YAML frontmatter at the top and Markdown instructions below, optionally with scripts, reference documents and templates beside it. Anthropic published it as an open specification at agentskills.io, and Claude Code, OpenAI Codex and a long list of other tools now read the same files.

The collections. Packs of ready-made skills shared on GitHub and in marketplaces: a frontend skill, a code review skill, a test-writing skill. Installing one is quick, and quality varies a great deal, because a skill written for someone else's codebase carries someone else's assumptions.

The idea. Reusable know-how an agent can pick up on demand, in whatever file format. This is the sense people mean when they say an agent "has a skill" for something.

This article is mostly about the first, because it is what you write and maintain, with notes on the second where it matters.

What a skill is made of

A skill is a directory named after the skill. Inside it:

• SKILL.md, the only required file. It starts with frontmatter between two --- lines and continues with plain Markdown.
• scripts/, optional: code the agent can run, for the steps that need to be exact every time.
• references/, optional: longer documents the agent reads only if the instructions send it there.
• assets/, optional: templates, example files, schemas.

The frontmatter needs two fields. The open specification requires both; Claude Code will load a skill without them but recommends the description.

• name: lowercase letters, numbers and hyphens, up to 64 characters, matching the folder name.
• description: what the skill does and when to use it, up to 1,024 characters in the specification.

Tools add their own optional fields on top. Claude Code, for example, can stop the agent from loading a skill by itself (disable-model-invocation), limit a skill to certain files (paths), or pre-approve the tools it needs (allowed-tools). Codex keeps its extras in a separate agents/openai.yaml beside the skill. Fields a tool does not recognise are ignored, so a skill written to the shared fields works in both.

How an agent decides to use one

Skills load in three stages, which the specification calls progressive disclosure.

1. At the start of a session, the agent is given the name and description of every installed skill. That is all. The specification puts this at about 100 tokens a skill.
2. When a task matches a description, the agent reads the whole SKILL.md. The specification recommends keeping it under 5,000 tokens and 500 lines.
3. When the instructions point somewhere, the agent opens that reference file or runs that script, and nothing else in the folder.

You can also call a skill by hand: in Claude Code it appears as a / command, and in Codex you mention it with $ or pick it from /skills. But the more common path is the automatic one, and the automatic one depends entirely on stage one. The agent does not read your skill to decide whether to read your skill. It reads one line.

There is also a budget on that first stage. Codex gives the opening list of skills 2% of the context window by default (8,000 characters when it cannot tell the window size), and when many skills are installed it shortens descriptions first and drops some altogether, with a warning. Claude Code cuts each skill's listing at 1,536 characters. So a description competes twice: once for the agent's attention, and once for space.

The description does the work

Because the decision is made on one line, the description is the most important sentence in the skill, and the one most often written last and in a hurry.

A weak description names a topic: "Helps with database stuff." The agent cannot tell whether "add a column to orders" is database stuff, or whether "why is this query slow" is. A strong description names the job, the words a person would use when they need it, and where it stops:

Write and check a database migration for this project's Postgres schema. Use when adding, renaming or removing a table, column, index or constraint, or when someone says "migration" or "schema change". Not for writing queries or fixing slow ones.

Three habits make descriptions trigger well:

• Put the job and the trigger words first. Codex's own guidance says so, because when descriptions get shortened, the end goes first.
• Say when not to use it. Two skills with overlapping descriptions will both look right, and the agent will pick one.
• Test it with real requests. Type five ways someone might ask for the job and check the skill loads for each; type two near-misses and check it does not.

A worked example

Here is a complete skill for a team on Postgres that writes migrations by hand. It is short on purpose: one job, steps in order, the checks spelled out, and the one exact step handed to a script.

--- name: database-migration description: Write and check a database migration for this project's Postgres schema. Use when adding, renaming or removing a table, column, index or constraint, or when someone says "migration" or "schema change". Not for writing queries or fixing slow ones. --- # Database migration  Migrations live in `db/migrations/`, one file per change, named `YYYYMMDDHHMM_short_description.sql`. Each file has an `-- up` section and a `-- down` section. Production runs them in name order. ## Steps  1. Read the latest three migrations to match the house style. 2. Write the new file. The `down` section must undo the `up` section exactly. 3. If the change removes or renames a column, stop and ask: is anything still reading the old name? Search the code for it and show what you found. 4. If the change adds a column to a table with more than a million rows, add it as nullable first and backfill in a separate migration. Say why in a comment. 5. Run `scripts/check-migration.sh <file>`. It applies the migration to a scratch database, rolls it back, and applies it again. Do not continue if it fails. 6. Update `db/schema.sql` with the result and show the diff. ## Never  - Edit a migration that has already been merged. Write a new one. - Put data changes and schema changes in the same file. For the list of large tables, see `references/large-tables.md`. 

Notice what it does not contain. There is no explanation of what a migration is, which the agent already knows, and nothing about queries, which belongs to another skill or none. The judgement calls are written as questions the agent must stop and ask, because those are the steps an agent will otherwise answer on its own. The one step that has to be exact, applying and rolling back, is a script, so it does not depend on the agent following prose.

Where skills fit with everything else

Skills are one of several ways to shape what an agent does, and most trouble with them comes from using a skill for a job another piece does better.

• The instructions file (CLAUDE.md, AGENTS.md) is read at the start of every session. It is the place for rules that are true all the time: the stack, the test command, what never to touch.
• Skills are read when a task matches. They are the place for procedures that apply some of the time.
• Hooks run code before or after the agent acts, whatever the agent intended. They are the place for anything that must happen, because a hook does not depend on the agent reading or agreeing.
• Subagents run a task in a separate context and hand back a result. They are the place for work that should not see, or be swayed by, everything the main session has seen, such as a review.
• Tools and MCP servers give the agent new things it can do: query a database, open a ticket.

The line that matters most is between the second and third. A skill can say "run the tests". Only a hook, or a check outside the agent, can make sure they ran.

The loop a skill lives in

A skill is not finished when it is written. The ones that stay useful go round a short loop.

1. Notice the repeat. The third time you explain the same procedure to an agent, it is a skill.
2. Write the smallest version that does the job: description first, then the steps.
3. Test the trigger with real requests and near-misses.
4. Use it on real work and watch where the agent goes wrong.
5. Fix the cause in the skill, not in the conversation. A correction typed into one session teaches one session.
6. Prune. Delete steps the agent gets right without being told.

The fifth step is the one teams skip. A correction made in chat feels like progress and disappears when the session ends. The same correction written into the skill holds for everyone, next time.

Six ways skills fail

It never loads. The description names a topic rather than a job, or uses words nobody types. The skill sits in the folder, correct and unused, and the agent improvises.

It loads for the wrong job. The description is so broad that it matches requests it was never meant for, and the agent follows a migration procedure while fixing a query.

Two skills fight. Two collections each ship a "code-review" skill, or two of your own overlap. Codex does not merge skills with the same name, so both appear. Claude Code lets one location override another. Either way, which one runs depends on details nobody is watching.

It is too big. A 900-line skill is loaded whole the moment it triggers and stays in the session, crowding out the task. In Claude Code, a loaded skill's content stays in context for the rest of the session, and only its first 5,000 tokens survive when the session is compacted.

It goes stale. The skill says migrations live in db/migrations/; the team moved them six months ago. The agent follows the skill, because the skill is what it was given.

It is advice, not a check. The skill says "run the tests before you finish". The agent, deep in a long task, does not. Nothing notices. A skill is text the agent reads, and an agent under pressure skips text.

How many skills, and how big

A skill should do one job, and you should have as many as you have recurring jobs, not as many as you can find.

• One job per skill. "Database migration" is a job. "Backend" is not. If the description needs the word "and" to cover two unrelated things, it is two skills.
• Write one when a procedure repeats, not in advance. A skill for a task you do once a quarter will be stale the next time you need it.
• Prefer short. Most good skills are under a hundred lines. Move long references into references/ so they load only when needed.
• Watch the total. Every installed skill costs a line at the start of every session. Thirty skills you never use make it harder for the agent to find the three you do.

There is a harder sizing problem that skills do not solve, which comes up in the last two sections: a skill does the same thing every time it runs, whatever the size of the change in front of it.

When a skill goes stale

The codebase moves every week. A skill moves when someone remembers it. The gap between the two opens quietly, and an agent cannot see it: it follows the skill confidently, because following instructions is what it was asked to do.

Three habits keep the gap small:

• Point at the code, do not copy it. "Match the style of the latest three migrations" stays true when the style changes. A pasted example does not.
• Change the skill in the same pull request as the change that makes it wrong. If the migrations folder moves, the skill's path changes in the same commit.
• Read your skills when something goes wrong. When an agent does something odd and confident, check whether a skill told it to.

How to judge a skill

What a skill cannot do on its own

Skills are good at one thing: putting the right procedure in front of the agent at the right moment. Some of what teams hope skills will do sits outside that.

A skill cannot decide what should be built. It can tell the agent how your team writes a migration. It cannot tell anyone whether this feature needs a migration, which tables it should touch, or what happens to existing rows. Those are decisions, and a skill holds procedures.

A skill cannot make sure it was followed. It is text. Whether the agent read it all, skipped a step under pressure, or stopped where it was told to stop, the skill cannot see. That needs a check that runs whether or not the agent agrees, and someone, or something, that did not write the work to look at it.

A skill gives the same ceremony to every change. A code review skill runs the same review on a one-word copy fix and on a change to how payments are stored. A folder of instructions cannot tell those apart, so it either does too much for the small change or too little for the risky one. This is the limit people hit after a few months, and it is structural: the skill is written once and then read the same way each time.

A skill does not learn from anyone else. When one team finds that their migration skill missed a case, the fix lives in their repository. A team down the road with the same gap will find it the same way.

How Halfcycle does it

Halfcycle runs inside Claude Code or OpenAI Codex and installs as a small set of commands and skills in each, so you start it the way you start anything else in those tools. What it adds is the part skills cannot do alone.

The method is not stored in those files. It is served to the session one step at a time, and the step you get depends on the change in front of you. Each request is sorted first: a small change takes a short path, an ordinary feature gets a spec and a review, and a change touching money, permissions or stored data gets the full treatment. You are told which path and why. That is the property a folder of skills cannot have, because the folder reads the same for every change.

Before any code, the open decisions are asked one at a time, each with a recommendation, and recorded where every agent in the project reads them. The plan is reviewed by an agent that did not write it. During the build, each piece is reviewed by an agent that did not build it, every edit is checked as it is made, and the agent asks you in plain words before a command that would delete work, wipe data, read credentials, publish or deploy. Those checks run whether or not the agent remembers them, which is the difference between advice and a check.

And it keeps getting better without you maintaining it. When a project implementation goes wrong, both the cause and the fix are kept, and both reach every other project automatically. So most of those problems never arrive on your project, and the ones that do arrive with the answer attached. What travels back is the shape of a problem, never your code or your documents, and we do not train on anyone's work.

If you have built your own set of skills for planning and review, you will recognise the parts. The difference is that nobody on your team has to keep them current, and they size themselves to the work.

The honest limits

Halfcycle does not replace the skills that hold your team's own knowledge. How you deploy, how your design system names things, which tables are large: those belong in your own skills and instructions, and they keep working alongside it.

It also needs a connection, because the method is served rather than stored in your repository. And skills themselves are young. The specification is about a year old, tools still differ on the optional fields, and a skill that behaves well in one agent can behave differently in another. Test yours in the tools your team actually uses.

Sources

Checked 12 November 2026.

• Agent Skills specification: format, field limits, progressive disclosure and size guidance.
• Claude Code: skills: skill locations, optional fields, the 1,536-character listing limit, how loaded skills stay in context and survive compaction.
• OpenAI Codex: build skills: skill locations, explicit and implicit activation, the opening-list budget, description guidance.

Getting started

npx halfcycle 

Run that in the folder you want to work in, then open it in Claude Code or OpenAI Codex and say what you are building. Needs Node 20 or newer. There is nothing to learn first, and it tells you what is next when it is next.

halfcycle.ai