# How to write a new skill for an AI agent

> The agent turns a method or a process into a skill that loads on the right tasks and can be followed without its author in the room.

Canonical: https://dawidgac.com/en/skills/how-to-write-a-skill-md
Published: 2026-09-22

## What it does

The agent starts with a short interview: what the skill changes, how people ask for it, what it should not catch and what a finished result looks like. It then splits the material: steps go into SKILL.md, per-reader settings into a context template, long reference into separate files. It writes the frontmatter description for the load decision, in the user's words. The body follows a fixed order: the problem, steps, decision rules, examples, output shape, self-check, failure modes. Finally it runs four tests in a fresh session: does the skill load, can a cold session follow it, does the result match the contract, and is the folder free of private data.

## When to use it

- You want to turn a process you run by hand into a skill for your agent.
- You have a document, chapter or framework and want the agent to apply it, not summarise it.
- Your skill exists but does not load, or the agent still improvises.
- You want to share a skill without your own paths, names and data.

## When not to use it

- A one-off instruction. A prompt in the conversation is enough.
- A one-line rule that fits in an existing project instruction file.
- A process you have not run yourself even once. Do it by hand first.

## Decision table

| Situation | What the skill does |
| --- | --- |
| Steps repeated every time | Writes them into SKILL.md as numbered, checkable steps |
| Values that differ per reader | Moves them to the context template as blanks with an example |
| Long material needed only sometimes | Splits it into its own file and says when to open it |
| The skill does not load | Rewrites the description in the words people actually type |
| The skill loads on unrelated tasks | Narrows the description or splits the skill |
| Private names or paths in the folder | Moves them to the reader's context and reruns the test |

## What you need

### An AI coding agent: Claude Code, Codex CLI or Cursor

required, app: https://code.claude.com/docs/en/overview

Writes the new skill's files and runs the tests in a fresh session. In a chat with no file access you get the contents to copy.

1. Install one agent from its official docs: Claude Code (code.claude.com/docs), Codex CLI (developers.openai.com/codex) or Cursor (cursor.com/docs).
2. Place the template folder where your agent loads skills or instructions, as in the install steps.
3. Make sure you can open a new session in a scratch copy of the project for the tests.

### Claude Code skills and Anthropic Agent Skills docs

optional, app: https://code.claude.com/docs/en/skills

For Claude Code: where skills live, which frontmatter fields exist and how a skill loads.

1. Read the skills page in the Claude Code docs.
2. For the general Agent Skills format, see platform.claude.com/docs/en/agents-and-tools/agent-skills/overview.
3. Write the skills folder and the loading behaviour you find there into CONTEXT.md.

### OpenAI Codex skills docs

optional, app: https://developers.openai.com/codex/skills

For Codex: where Codex looks for skills and what a SKILL.md must contain.

1. Read the skills page in the Codex docs.
2. If your version has no skills support, use AGENTS.md instead: developers.openai.com/codex/guides/agents-md.
3. Write the skills folder your version uses into CONTEXT.md.

### Cursor rules docs

optional, app: https://cursor.com/docs/context/rules

For Cursor: how to add instructions as a project rule or through AGENTS.md.

1. Read the rules page in the Cursor docs.
2. Write into CONTEXT.md whether you use project rules or AGENTS.md.

## Install

1. Claude Code: copy the folder to .claude/skills/skill-authoring/ in your project, or to ~/.claude/skills/skill-authoring/ for every project. Claude loads the skill when its description matches the task, or when you type /skill-authoring.
2. Codex: copy the folder to .agents/skills/skill-authoring/ in your repository, or to ~/.agents/skills/skill-authoring/ for every project. If your version has no skills support, paste the contents of SKILL.md into AGENTS.md.
3. Cursor: add SKILL.md as a project rule, or paste it into AGENTS.md.
4. A chat with no files: paste SKILL.md at the start of the conversation and attach the material the skill should come from.
5. Copy CONTEXT.template.md to CONTEXT.md next to SKILL.md and fill in every field.
6. Keep SKILL.skeleton.md in the folder. The agent copies it for every new skill.

## It's working if

- Before writing, the agent asks at most five questions about the job, the triggers and the finished result.
- The new folder is named after the name field and holds a SKILL.md and a context template.
- The frontmatter description says what the skill does and when to use it, in the words from the trigger list.
- In a fresh session the skill loads on every phrase from the list and stays unloaded on tasks outside it.
- The agent hands back a report of the four tests with what it fixed after each failure.

## Requirements

- An agent that can write files. In a chat without files you get the content to copy.
- Source material: a process description, a document or notes.
- A way to open a fresh session for the tests.

## FAQ

### Why does the frontmatter description matter so much?

The name and description are the only parts of a skill the agent sees before deciding to load it. A title-style description, such as the name of a method, does not match how people phrase a task, so the skill never loads. A description built from situations and user phrases does.

### Why test in a fresh session when the skill works in the one that wrote it?

The session that wrote the skill knows what the author meant and fills gaps from the conversation. A fresh session has only the folder. Every place it stalls or guesses is a missing step or a missing context field.

### Can I make a skill from a book or a course?

You can make a skill that applies the method to your work: steps, decisions, a self-check. Do not copy the source's text or share it on without the author's permission. A skill that only summarises does not work anyway, because the agent has nothing to execute.

### How long can a SKILL.md be?

Short enough to read in one pass. Move reference tables, full lists and schemas into separate files in the folder and say in the body when the agent should open them.

## Where it fits

This skill produces other skills. The self-correcting skill log template adds a memory of mistakes to a finished skill, and the adversarial review template helps when a skill touches code or data that can break things. Every template in this library has the shape this skill describes: SKILL.md (or CLAUDE.md for agent-instruction templates), a context template and supporting files.

## Sources

- Claude Code docs: skills: https://code.claude.com/docs/en/skills (accessed 2026-09-22)
- OpenAI Codex docs: skills: https://developers.openai.com/codex/skills (accessed 2026-09-22)
- OpenAI Codex docs: AGENTS.md: https://developers.openai.com/codex/guides/agents-md (accessed 2026-09-22)
- Cursor docs: rules: https://cursor.com/docs/context/rules (accessed 2026-09-22)

## Files

### SKILL.md

The method: interview, choosing the shape, frontmatter as a trigger, body order, the context template and four tests in a fresh session.

Download: https://dawidgac.com/en/skills/how-to-write-a-skill-md/files/SKILL.md

````markdown
---
name: skill-authoring
description: Write a new SKILL.md for an AI agent from a method, a document, a book chapter or a workflow you already run, then test that it triggers and that a fresh session can follow it. Use it when someone asks to "turn this into a skill", "write a skill for X" or "package this workflow for the agent".
---

# Writing a new skill

A skill is a folder the agent loads when a task matches it: a `SKILL.md` with a short frontmatter and a
body of instructions, plus any files the instructions point to. Most skills that fail do so in one of two
ways. They never load, because the description does not match how people phrase the task. Or they load
and the agent still does the wrong thing, because the body is a summary of the topic instead of
instructions it can act on. This workflow writes skills that avoid both and tests them before calling
them done.

Read `CONTEXT.md` next to this file first. It says where skills live in the reader's tool, the house
conventions, and what must never go into a skill file. If `CONTEXT.md` is missing or a field is blank,
ask the user for it in the language they write in, then write the answer into `CONTEXT.md`. For example:

- English: "Which agent do you use, and where does it load skills from?"
- Polish: „Którego agenta używasz i skąd wczytuje skille?"

## Before you start / What you need

- **An AI coding agent that can write files:** Claude Code, Codex CLI or Cursor. In a chat with no file
  access you hand back the file contents to copy instead.
- **Your tool's own skills documentation**, so the folder, frontmatter and loading rules match what your
  tool expects. Read the page for the tool you use:
  - Claude Code skills: https://code.claude.com/docs/en/skills
  - Anthropic Agent Skills overview: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
  - OpenAI Codex skills: https://developers.openai.com/codex/skills
  - Cursor rules: https://cursor.com/docs/context/rules
- **Source material:** a process description, a document or notes.
- **A way to open a fresh session** for the tests in step 6.

## 1. Interview before drafting

Ask only what the material does not already answer. Stop at five questions.

1. **The job:** what does the agent do differently once this skill is loaded? One sentence.
2. **Triggers:** three to five phrasings a real person would type when they need it. Include the lazy ones.
3. **Non-triggers:** tasks that look similar but should not load it.
4. **Inputs:** what the agent needs from the user or the project each time (a file, a URL, a setting).
5. **Done:** what the output looks like when the skill worked. Something you can see, not a feeling.

If the source is a document, book chapter or framework, read all of it first. Pull out the decisions and
procedures, not the prose. A skill is not a book summary.

## 2. Decide the shape

| The material is... | Put it in... |
|---|---|
| Steps the agent follows every time | the `SKILL.md` body, as numbered steps |
| Settings that differ per reader (paths, tools, thresholds, names of their things) | a `CONTEXT.template.md` the reader copies and fills in |
| Long reference (tables, full checklists, schemas) the agent needs only sometimes | a separate file in the folder, linked from the body with when to open it |
| A fixed output shape | a template file the agent copies |
| Anything that must run the same way every time (a check, a transform) | a small script in the folder, called from the body |

Keep the `SKILL.md` body short enough to read in one pass. Move reference material out and link it with a
sentence that says when to open it. The agent reads a linked file only when the body tells it to.

## 3. Write the frontmatter

Start from `SKILL.skeleton.md` in this folder: copy it into the new skill's folder as `SKILL.md`, then
fill in its frontmatter here and its body in step 4.

```yaml
---
name: lowercase-with-hyphens
description: <what it does>. Use it when <trigger situations, in the user's words>.
---
```

- `name` matches the folder name.
- The `name` and `description` are the only parts the agent sees before deciding to load the skill.
  Write the description for that decision: what it does, then when to use it, in the words from your trigger list. Name the non-obvious
  triggers. Leave out the history of the method and any praise.
- One description, one job. A description with three unrelated jobs is three skills.

## 4. Write the body

Use this order. Skip a section only when it would be empty.

1. **Title and why:** two to four sentences on the problem the skill solves and what goes wrong without it.
2. **Read first:** which context file or setting to load before starting.
3. **Steps:** numbered, imperative, each one checkable. "Check the X" is weak; "list every X with its Y,
   and stop if any Y is missing" is a step.
4. **Decision rules:** the forks the agent will hit, as a table of situation and action.
5. **Examples:** one good and one bad output, short, on a neutral fictional case. Mark invented numbers
   as invented.
6. **Output contract:** the exact shape of what the agent returns or writes.
7. **Self-check:** three to seven yes/no questions the agent answers before replying.
8. **Failure modes:** a table of symptom, cause and fix.

Writing rules:

- Instructions, not descriptions. "Ask for the order export before analysing" beats "order data is
  important".
- Say what to do instead, not only what to avoid.
- Give the reason for a rule in one line when the reason changes how it is applied.
- No private facts: no names, paths, keys, hostnames, account ids, prices, customer data or internal
  incident stories. Those belong in the reader's `CONTEXT.md`, as blanks with an example.
- Relative paths inside the folder. Absolute paths break on every other machine.

## 5. Write the context template

For every setting that differs per reader, add a section to `CONTEXT.template.md`:

```
## <setting>
(what it is and how to decide it)
<field>: ___
Example: <a neutral, invented example>
```

Open the file with "copy this to CONTEXT.md and fill in every blank" and a line saying never to put
passwords or access keys in it.

## 6. Test before calling it done

Run these in a fresh session, not the one that wrote the skill. The writing session knows what you meant.

1. **Trigger test:** type each phrase from your trigger list. The skill should load for each. Then type
   each non-trigger. It should not load. Fix the description until both hold.
2. **Cold-follow test:** give a fresh session a real task and only the skill folder. Watch where it
   stalls, guesses or asks. Each stall is a missing step or a missing context field.
3. **Output test:** compare the result with the output contract, line by line.
4. **Leak test:** search the folder for your own names, paths, hostnames, account ids and numbers. The
   count should be zero.

Record what failed and what you changed. Rerun until all four pass.

## 7. Package

- Folder name equals `name`.
- Every file the body links to exists in the folder.
- `CONTEXT.template.md` present if any setting varies per reader.
- If your tool installs skills from an archive, zip the folder itself, not its parent.

## Self-check before handing the skill over

- Does the description say both what the skill does and when to use it, in the user's words?
- Would a stranger on a different machine be able to follow every step?
- Is every per-reader value a blank in the context template, not a fact in the body?
- Did the trigger test and cold-follow test pass in a fresh session?
- Is the folder free of private names, paths, keys and numbers?

## Failure modes

| Symptom | Cause | Fix |
|---|---|---|
| The skill never loads | description written as a title, not as trigger situations | rewrite it with the phrases people actually type |
| The skill loads on unrelated tasks | description too broad, or several jobs in one | narrow it; split into separate skills |
| The agent loads it and improvises | body summarises the topic instead of giving steps | numbered, checkable steps and a decision table |
| Works for the author, fails for others | private paths, names or tools baked into the body | move them to the context template |
| The agent ignores the reference file | the body never says when to open it | link it with an explicit "open this when..." |
````

### CONTEXT.template.md

Your settings: where your tool keeps skills, how it loads them, house conventions and the list of things that must stay out of a skill.

Download: https://dawidgac.com/en/skills/how-to-write-a-skill-md/files/CONTEXT.template.md

```markdown
# Skill authoring: your context

Copy this file to CONTEXT.md next to SKILL.md and fill in every blank. Never put passwords, access keys or
card numbers here.

## Where skills live in your tool

(The folder your agent loads skills from, per project and for every project.)
Project skills: ___
Skills for every project: ___
Example: .claude/skills/<name>/ in the repository; ~/.claude/skills/<name>/ for all projects.

## How your tool loads a skill

(Automatically from the description, by a command, or both. If your tool has no skill system, where the instructions go instead.)
Example: loads automatically when the description matches, or by typing /<name>. A tool without skills: paste into the project instruction file.

## House conventions

(Language of skill files, heading style, whether every skill ships a context template, maximum body length you want.)
Language: ___
Context template in every skill: yes / no
Body length you want to stay under: ___
Example: English, a context template whenever any value differs per user, body readable in one pass with reference moved to separate files.

## Never in a skill file

(Your own list of things that must stay out: the kinds of private facts specific to your work. They go in CONTEXT.md as blanks instead.)
Example: client names, internal hostnames, account ids, prices, file paths on my machine, anything from customer records.

## Where you test

(How you open a fresh session for the trigger and cold-follow tests.)
Example: a new terminal session in a scratch copy of the project.
```

### SKILL.skeleton.md

An empty skeleton for a new skill with frontmatter and every section ready to fill in.

Download: https://dawidgac.com/en/skills/how-to-write-a-skill-md/files/SKILL.skeleton.md

````markdown
---
name: your-skill-name
description: (What it does, in one sentence.) Use it when (trigger situations in the words a user types), for example "(phrase one)" or "(phrase two)".
---

# (Title)

(Two to four sentences: the problem this solves and what goes wrong without it.)

Read `CONTEXT.md` next to this file before starting. (Say what it holds.)

## 1. (First step)

(Imperative, checkable. Say what to do and when to stop.)

## 2. (Next step)

(...)

## Decision rules

| Situation | Action |
|---|---|
| (a fork the agent will hit) | (what it does) |

## Examples

Good:
```
(short output on a neutral, invented case; mark invented numbers as invented)
```

Bad:
```
(the tempting wrong output, with one line on why it is wrong)
```

## Output contract

(The exact shape of what the agent returns or writes, and where.)

## Self-check before replying

- (yes/no question)
- (yes/no question)
- (yes/no question)

## Failure modes

| Symptom | Cause | Fix |
|---|---|---|
| (what you see) | (why) | (what to change) |
````