Skills
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 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.mdEach file starts with a name and a description:
---
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-testonly 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:
- Frontmatter. A
namethat matches the folder, and adescriptionthat 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. - The files it touches, in the order they are touched.
- 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.
- 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 — the rules in
AGENTS.md - Testing — the long version of
write-a-test - Deployment — the long version of
deploy - Swap a provider — the long version of that skill