---
title: Skills
description: The task recipes that ship with zap.ts - what each one covers, when it fires, and how to write your own.
---

A skill is a recipe for one task. It is a markdown file that says which files
to touch, in which order, and which command proves the work is done.

[`AGENTS.md`](/guides/agents) holds the rules of the whole codebase. A skill
holds the steps of one job. The rules are always loaded. A skill is read only
when its job comes up.

## Where they live

```
.claude/skills/<name>/SKILL.md
```

Each file starts with a `name` and a `description`:

```md
---
name: add-an-api-route
description: Add a route to apps/api - a Hono router with hono-openapi, the
  session middleware, the shared validation hook, and the regenerated OpenAPI
  file. Use for public API endpoints customers call, not for your own app's
  page data.
---
```

Claude Code reads those two lines for every skill at the start of a session,
and opens the body of a file only when the task matches. That is why the
description ends with the words a person would actually use. The body stays out
of the context window until it is needed.

They are plain markdown, so they are not only for Claude Code. Cursor, Copilot
or a person can open the same file and follow the same steps. Nothing in them
is tool-specific.

## The skills that ship

**Starting a project**

| Skill               | Use it for                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `slim-the-template` | Deleting the providers, apps and features this project will never use — it asks first, and says what each removal costs to undo |

**Building**

| Skill                  | Use it for                                                                  |
| ---------------------- | --------------------------------------------------------------------------- |
| `add-a-feature`        | A table, a migration, a server function and a page — one feature end to end |
| `add-an-api-route`     | A public route in `apps/api`, described with OpenAPI                        |
| `add-a-background-job` | Work that runs after the response, on either host                           |
| `add-a-ui-component`   | A shared component in `@zap-ts/ui`                                          |
| `add-a-translation`    | User-facing text in `apps/web` or `apps/marketing`                          |
| `add-an-env-var`       | A new setting or secret key                                                 |
| `add-a-package`        | A new workspace package, or any new dependency                              |
| `write-a-test`         | Any test — before the code it tests                                         |

**Changing a provider**

| Skill                   | Use it for                      |
| ----------------------- | ------------------------------- |
| `swap-a-provider`       | Mail, file storage or payments  |
| `swap-an-ai-provider`   | The company behind `@zap-ts/ai` |
| `add-an-oauth-provider` | A social sign-in next to Google |

**Finishing**

| Skill                   | Use it for                              |
| ----------------------- | --------------------------------------- |
| `debug-a-failing-check` | A check from `AGENTS.md` that fails     |
| `deploy`                | Shipping an app to Cloudflare or Vercel |

## How to use one

With Claude Code, do nothing. Describe the task in your own words — "add a
billing page", "the typecheck fails" — and the matching skill loads itself. You
can also name it: `/add-a-feature`.

With another agent, paste the path or the file: "follow
`.claude/skills/add-a-feature/SKILL.md`".

On your own, read it. Each one is a page long and ends with the commands that
prove the change works.

Two habits are worth keeping:

- **Open the skill before you start, not after.** Most of them say what to
  write _first_, and `write-a-test` only makes sense before the code exists.
- **Run the gate at the bottom.** It is the short list of commands that catch
  what that particular task breaks, which is faster than the whole table in
  `AGENTS.md`.

## Writing your own

Your product will have its own repeated jobs. Add a folder under
`.claude/skills` and write the same shape:

1. **Frontmatter.** A `name` that matches the folder, and a `description` that
   says what the skill does _and_ the words that should trigger it. The
   trigger words are the whole job of the description — a skill nobody finds is
   a skill nobody runs.
2. **The files it touches**, in the order they are touched.
3. **The rule that is easy to get wrong.** The reason a skill beats a guess is
   usually one line: a generated file that must not be edited by hand, a
   command that has to run after the change.
4. **A gate.** The commands that prove the work is done.

Keep it to a page. A skill is read while working, not studied.

Add the new skill to the table in `AGENTS.md` as well. That table is how an
agent without skill support finds the file at all.

## Related

- [AI Agents](/guides/agents) — the rules in `AGENTS.md`
- [Testing](/guides/testing) — the long version of `write-a-test`
- [Deployment](/guides/deployment) — the long version of `deploy`
- [Swap a provider](/recipes/swap-a-provider) — the long version of that skill