AI Skills
The bundled SKILL.md recipes that teach an agent this repo's conventions and traps.
A skill is a SKILL.md file: a trigger plus a literal procedure. Not a vague "you are a helpful assistant" prompt: the exact steps for one real task in this repo, with its conventions baked in and its known traps called out. The api-endpoint skill, for instance, hands over the Hono router template, the validation envelope, where to mount the route, the restart step, and the curl that proves it works.
Every skill lives in .agents/skills/<name>/SKILL.md. That is the one source. .claude/skills is a symlink to it, so Claude Code, Cursor, and Codex all read the same files. Edit a skill once and every agent tool sees the change. There is no second copy to keep in sync.
How an agent picks one
Each SKILL.md opens with frontmatter, a name and a description that states when to use it:
name: api-endpoint
description: Add a typed Hono API endpoint following repo conventions... Use when adding or modifying API routes in api/hono.An agent reads those descriptions, matches the task in front of it against the "Use when…" trigger, loads the one skill that fits, and follows the procedure verbatim. Only the descriptions are scanned up front, so the whole catalog costs almost nothing in context until one is needed; the full procedure loads only on a match.
When you don't know where to start, the codebase-map skill orients first; it maps where each kind of change lives and how types ripple across the stack. It is the one skill worth reading before you have a specific task.
The catalog
The skills, arranged as the arc of a real task, Navigate to find your way, Build the feature, Operate the running app, Maintain the scaffolding, Ship the change:
| Stage | Skill | What it does |
|---|---|---|
| Navigate | codebase-map | Orient fast: the "where do I edit for X" table and how a change ripples across the stack. Start here in unfamiliar territory. |
| Build | add-package | Add a shared workspace package the repo's way: skeleton, types: ["bun"] for Bun scripts, gitignored .generated/ output. |
| Build | api-endpoint | Add a typed Hono route the repo's way: router, validation envelope, OpenAPI, RPC wiring, and the restart-and-curl test. |
| Build | db-migration | Change the Drizzle schema and apply it: db:generate, then db:migrate. |
| Build | design | The canonical UI conventions: spacing, color, cursor, typography, tokens. Follow it for any component work. |
| Build | dev | Start, restart, and verify the dev stack; fixes the bun --hot trap where new files return NOT_FOUND. |
| Build | portless | Set up and use portless for stable named .localhost dev URLs instead of localhost:PORT. |
| Build | runtime-apis | Prefer Bun-native APIs; fall back to Node built-ins with the required node: prefix. |
| Operate | agent-browser | Drive the running app like a user: navigate, click, and snapshot the accessibility tree. |
| Operate | audit | Run the dependency security audit and maintain .github/notes/dependencies.md; unblocks the pre-push audit hook. |
| Operate | docker-test | Build and smoke-test the Docker images with docker compose. |
| Operate | ui-verify | Verify a frontend change in a real browser with agent-browser, then attach screenshots to the PR. |
| Maintain | fonts | Add or swap web fonts: fetch latin variable woff2 from Fontsource, localize through next/font/local. |
| Maintain | ignore-sync | Keep .dockerignore in step with .gitignore. |
| Maintain | shadcn-sync | Run bun run shadcn:update and reconcile it so a sync never silently drops your customizations. |
| Ship | doc-sync | Sync docs and skills so a change never ships drift: the surface map, a grep sweep, and the strict docs build. |
| Ship | gh-commit | Atomic commits in conventional-commit format. |
Two skills are vendored from Vercel Labs; every other skill is written for this repo. agent-browser (from vercel-labs/agent-browser) is a discovery stub pinned in skills-lock.json for integrity: its committed SKILL.md just points the agent at the live workflow (agent-browser skills get core), installed with npm i -g agent-browser && agent-browser install. portless (from vercel-labs/portless) is copied in full and self-contained. Re-vendor to update either; do not hand-edit.
Writing your own
Make a directory under .agents/skills/<name>/, add a SKILL.md, and the symlink carries it to every tool:
---
name: deploy-preview
description: Ship a preview build to staging. Use when asked to deploy a preview.
---
# Deploy Preview
## Workflow
### 1. Build
```bash
bun run build
```Keep it one task, one procedure. Write the real commands and the real traps. A skill earns its place by encoding what an agent would otherwise get wrong. When a convention changes, update its skill in the same commit; AGENTS.md makes that rule load-bearing.
Next
- Working with Agents: the loop these skills plug into.
- The Type-Safe API: the types the build skills lean on.