Writing Agent Skills

How to add or change a skill in @warp-drive/memory-alpha, the package of plain-markdown instructions that AI coding agents read when they work in this repo or in an app that depends on WarpDrive. The same files are published for humans at /skills.

Audience

Of the audiences our documentation serves, a skill has two: the coding agent that will follow it, and the human who opens the published copy to see what agents are being told. Write for the agent. It has the repo in front of it and no conversation history, so give it the rule, the reason, and the exact place to look, and nothing it can read for itself. If the skill is in skills/contributors/, assume the agent is working inside this repo and knows its layout. If it is in a consumer directory such as skills/schemas/ or skills/requests/, assume the agent is in an app that depends on WarpDrive and knows only the public API.

How agents reach a skill

Agents do not browse the package. Each agent surface in the repo (AGENTS.md, which CLAUDE.md and GEMINI.md import, plus the Copilot and Cursor pointer files) tells the agent to open one routing table and read only the row that matches its task:

• skills/contributors/index.md routes agents contributing to WarpDrive itself.
• skills/index.md routes agents consuming @warp-drive/* packages in an app.

A skill that is not in the right table does not exist as far as agents are concerned. Adding a skill therefore always means touching four files in its directory: the skill itself, index.md (the agent-facing table), overview.md (the same table with links, published in place of index.md on the website), and _meta.json (sidebar title and order for the website). Miss the overview.md row and the website's table lacks the skill; miss the _meta.json entry and it sorts last with a title generated from its filename. Nothing checks that index.md and overview.md agree, so compare them by eye. If the content outgrows the skill, a fifth file, a human guide under guides/, holds the detail and the skill links it.

Writing the skill file

• No YAML frontmatter. The package README explains why: downstream tooling adapts these files into tool-specific formats (Claude skills, Cursor rules, Copilot instructions) and adds its own frontmatter, so ours would collide. Title and ordering live in _meta.json instead.
• Open with an H1 and the trigger. The file starts with an H1 matching the title you give it in _meta.json. The first sentence under it is "Use this skill whenever..." followed by the situation, so an agent that landed here from the table can confirm it is in the right place.
• Then ## Steps, numbered, each one an action the agent can take. Put the reason for a rule in the step that states it. Existing skills such as Start in a Fresh Worktree and Keep Commits Human-Authored are the house style.
• Link, don't restate. If a human guide owns a rule, link the guide and its heading rather than copying the rule. A copied rule goes stale silently; a link fails the link checker.
• Stay tool-agnostic. Say "ask the user" and "a fresh agent instance", not the name of one product's tool or command. The skill is read by several agents.
• Put angle brackets in code spans. VitePress compiles markdown to Vue, so a bare <thing> in prose is parsed as an element and fails the docs build.
• Cross-reference other skills at the moment their case arises. The index routes one row per task, so a link from inside a skill is the only way an agent discovers a second skill mid-task: a bug-fix skill that ends "if this changed documented behavior, follow Write Documentation" reaches agents the documentation row never will. Link at the step where the other skill becomes relevant, don't summarize it, and add the reciprocal link when the dependency runs both ways.
• Link paths. Other skills are linked relatively (./other-skill.md, or ../schemas/other-skill.md across directories); guides are linked by site path (/guides/contributing/...md); anchors must match a real heading.
• Keep it short. If a skill needs more than about 100 lines, some of it belongs in a human guide that the skill links.

Wiring it in

In the skill's directory:

1. Add a row to index.md: the situation in the first column, the filename with its .md extension in the second. Rows that apply to every session are listed first and called out below the table; put a task-specific skill after them.
2. Add the matching row to overview.md, same first column, with the second column as a link: [Title](/skills/<directory>/your-skill.md).
3. In _meta.json, add the slug to items where it should sit in the sidebar, and add "your-skill": { "title": "Your Title" } under files.

Publishing and drafts

The skills directory is synced to /skills on the website like the other content roots (see How the Docs Site Is Built), with one difference: a page marked draft is removed from the site entirely rather than hidden from the sidebar. That is how each directory's agent-facing index.md stays off the website while overview.md is published in its place: the directory's _meta.json carries both "files": { "index": { "draft": true } } and "webIndex": "overview". Agents read from disk, so draft has no effect on them.

Checking your work

• pnpm lint:docs from the repo root checks every link and heading anchor in skills/ along with the guides (see Checking Links).
• Build the site as Previewing Your Changes describes and open /skills/contributors/ to see the sidebar entry and rendered page.
• Hand the skill file alone, not the index or the repo, to a fresh agent instance with a task it should cover, and check that it follows the steps to the right place and does not name a tool specific to one product.