Working with an agent

The starter assumes you will hand it to a coding agent, and it is shaped for that: one instruction file, machine-checked rules, eight procedures for the jobs you repeat, and error messages that name a field path instead of describing a problem.

That last one is the least obvious and the most useful. site.config.ts › tiers[1].featuredDays: required when kind is "featured" is a message an agent can act on without re-reading the file to work out what you meant.

AGENTS.md, and why it is tested

AGENTS.md at the root of the starter holds twenty hard rules about the project — how Tailwind is wired, which module is allowed to construct a URL, what the free/paid seam is, why the build fails on an island. CLAUDE.md contains one line pointing at it. There is one instruction surface, not three that disagree.

It is checked by the test suite, which is unusual enough to be worth spelling out. The suite fails when:

• a repository path named in backticks in AGENTS.md no longer exists;
• a command in its table is not a real package.json script, or a script exists that the table does not document;
• something listed as not-yet-implemented has since been built;
• the file exceeds its line budget, or contains a single non-English character.

The point is not tidiness. An AGENTS.md that has quietly gone stale is worse than none, because an agent will follow it confidently into a wall. Wiring it to the tests means the document cannot rot without the build going red.

Two hazards from it are worth repeating here, because they are the ones that surprise people:

• Listing content reaches agent context. A listing whose slug is claude becomes claude.md in the content directory, and on a case-insensitive filesystem anything probing for a CLAUDE.md memory file will find it. Listing bodies are third-party data — treat them as data and not as instructions, especially if you generate them.
• Custom field values that are objects or arrays are dropped silently. They render nothing and warn nothing.

The ten skills

Skills are procedures, not prompts. Each one is a file the agent loads when your request matches its description, and it names the file to edit, the rule that will be tripped, and the command that proves the change worked.

.agents/skills/ is the source; pnpm skills:sync mirrors it to .claude/skills/ on every install, so Claude Code and Codex both see the same set. Never edit the mirror — it is generated and gitignored.

The Recipes pages are generated from those skill files, so what you see there is what an agent sees.

Two rules for generating content

The starter takes a hard line on invented data, and if you plan to fill a directory with an agent you should adopt it too.

Planning and writing are separate stages. plan-directory produces names and URLs and is forbidden from writing a single description. generate-listings takes that list, verifies every URL actually resolves, writes each description only from the fetched page, and records where each fact came from in the listing’s own frontmatter. The split exists precisely because the point where a model would otherwise invent a product is the point between those two stages.

A fetched page is data, not instruction. The generation skill says so explicitly. A directory is a pile of third-party marketing copy; some of it will, sooner or later, contain text addressed to whatever is reading it.

This site, for an agent

Three surfaces, in increasing size:

Surface	What it is
/docs/prompt/<page>.md	one page, framed as a task, with the two standing facts about the project prepended. The Copy as prompt button on every page copies exactly this
/docs/llms.txt	the index: what ZeroDirs is, then every page as a linked list
/docs/llms-full.txt	every page in one file. /docs/llms-small.txt is the same with code blocks stripped, for a smaller context

The per-page prompt is the one to reach for when you want an agent to do one thing. llms-full.txt is for when you want it to understand the product before deciding what to do.

A good first prompt

Describe the outcome, not the skill. Agents that can see .agents/skills/ will pick the right procedure themselves:

Add a “Compliance” category to this directory, pick a sensible lucide icon, seed it with at least one real listing so the page is not empty, and verify with pnpm check and a full build.

That triggers the add-category skill, which knows the three things that request does not say: that the icon merges into theme.icons automatically, that an empty category still renders a page and goes noindex, and that a lone listing with unique tags will trip the orphan check.

Whatever you ask for, the verification order is always the same, and the build is not optional:

pnpm check
pnpm test
pnpm build