static_

Building with AI

Every project created with static new includes two files at its root:

  • AGENTS.md: a guide for AI coding assistants, covering the project layout, the workflow for turning a brief into a site, the components and design rules, and the checks to run.
  • CLAUDE.md: one line that points Claude Code at AGENTS.md. Codex, Cursor and most other assistants read AGENTS.md directly.

Build a site from a prompt

static new plumbing --template=default --yes
cd plumbing
claude

Then describe the site:

Build a site for a two-person plumbing firm in Leeds. Pages: home, services, about,
contact. Friendly, plain tone. Phone 0113 000 0000, hello@example.com. Brand colour green.

The assistant reads the starter, fills in data/site.json, writes the pages and components, sets the accent colour, and runs static check until the build is clean. It does not deploy or commit unless you ask.

A good brief says what the business or project is, who it is for, which pages you want, the tone, any real facts (contact details, services, prices) and the colour or mood. The more real content you give, the less placeholder text you have to replace.

What the guide teaches

  • Read the existing files before changing anything, and reuse the starter's components.
  • Put identity, navigation and structured data in data/site.json, and one file per page in pages/.
  • Write real copy, with a title, a 120 to 160 character description and one <h1> on every page.
  • Use <Image> with alt text, <Icon> for icons, and Tailwind classes in the starter's style.
  • Run static check, which fails on missing metadata, broken links and unknown components, and fix every warning.

Keeping it up to date

AGENTS.md is a normal file in your project. Add your own rules to it, such as your tone of voice, banned words or a component the assistant should always use. It is not overwritten by later static commands.

Working on Static itself

The Static repository has its own CLAUDE.md for assistants working on the CLI. See Internals.