---
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..." |