hotrod
AGENTS.md1 starsChanged 12 days agoMITView on GitHub
Hotrod is Roboto Studio's agent-first Astro starter: an Astro 6 + MDX + Tailwind v4 marketing site where pages are built from Zod-typed blocks in frontmatter. This file is the rulebook for any agent working here. Cursor, Codex, Copilot, v0 and most other tools read it directly; Claude Code reads it through CLAUDE.md. 1. Compose before you extend. Most requests are content: fill existing blocks in a page's blocks: list. Touch src/blocks/ only when no block can express the content.…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- compose-blockSkill
- compose-pageSkill
- write-a-skillSkill
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Strict Zod everywhere: Every schema is .strict() and every field has a plain-English error message.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — Hotrod
Hotrod is Roboto Studio's agent-first Astro starter: an Astro 6 + MDX +
Tailwind v4 marketing site where pages are built from Zod-typed blocks in
frontmatter. This file is the rulebook for any agent working here. Cursor,
Codex, Copilot, v0 and most other tools read it directly; Claude Code reads it
through CLAUDE.md.
Golden rules
- Compose before you extend. Most requests are content: fill existing
blocks in a page's
blocks:list. Touchsrc/blocks/only when no block can express the content. - Strict Zod everywhere. Every schema is
.strict()and every field has a plain-English error message. When content fails validation, fix the content; never loosen the schema to make it pass. public/is chrome only (favicon, robots.txt). Content images go to Vercel Blob and are referenced by key; video goes to Mux and is referenced by playback ID. The build checks both exist.- Design tokens only. Colours come from
src/styles/global.css. No hex codes or palette classes in components. - kebab-case filenames for everything, including
.astrofiles. Import bindings stay PascalCase (import SiteNav from './site-nav.astro'). - The build is the gate, then look.
pnpm buildruns every schema. A green build is not done: open the page inpnpm devand check it at phone and desktop width. maindeploys to production. Work on a branch and open a pull request; never push tomain. Every other branch gets a Vercel preview.
Where things live
| What | Path |
| Pages (MDX, URL = file path) | src/content/pages/**/*.mdx |
| Blog posts | src/content/blog/*.mdx |
| Authors | src/content/authors/*.mdx |
| Frontmatter schemas | src/content.config.ts |
| Blocks (schema + component per folder) | src/blocks/<name>/{schema.ts,index.astro} |
| Block registry | src/blocks/registry.ts |
| Shared block fields (button, image, video) | src/blocks/_shared/ |
| Shared components (icons, dividers, media) | src/components/ |
| Header and footer links (hard-coded) | src/components/site-nav.astro, src/components/site-footer.astro |
| Layouts and site chrome | src/layouts/ |
| Page routing (blocks vs prose) | src/pages/[...slug].astro |
| Design tokens | src/styles/global.css |
| Blob and Mux manifests (generated at build, gitignored) | src/generated/ |
Skills
Step-by-step procedures live in .claude/skills/. Read the one that matches
the task before starting.
| Skill | Use it for |
.claude/skills/compose-page/SKILL.md | Adding or editing a page or blog post: finding the file, frontmatter rules, the block catalog, field shapes, and how to validate. |
.claude/skills/compose-block/SKILL.md | Creating or changing a block or any visible component: the folder contract, registry, shared parts, and the design rules every block follows. |
.claude/skills/write-a-skill/SKILL.md | Asked to remember a rule or save a convention: write it here as a skill so every agent gets it, then add a row to this table. |
Commands
| Command | Does |
pnpm install | Install dependencies |
shelve pull | Pull env vars from Shelve (project and env come from shelve.json). pnpm dlx vercel env pull .env.local works too. dev, build and astro check fail without BLOB_READ_WRITE_TOKEN, MUX_TOKEN_ID and MUX_TOKEN_SECRET. |
pnpm dev | Dev server at http://localhost:4321, drafts included |
pnpm build | Production build; validates every page |
pnpm astro check | Type check |
There is no test framework. Verification is pnpm astro check, pnpm build
and looking at the page.
When the build fails
Zod errors name the file, the field path and what was expected, for example
`hero.buttons` can contain at most three buttons. Fix the content the
message points at. A Blob or Mux error means the key or playback ID does not
exist in that account: upload the asset, or correct the reference.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.