ASTRO AGENTS.MD

An Astro site that ships HTML first and JavaScript only where an island needs it. The rules protect that default, because agents tend to add client directives and frameworks the page never needed.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
AGENTS.mdFor Codex, Cursor, Copilot, Jules, Windsurf and more
# AGENTS.md

Project: astro-site. A content-focused Astro site with Markdown content collections and static output.

This file is the single source of truth for every coding agent working in this repository. The tool-specific files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md and .cursor/rules/project.mdc) point here. Edit this file, not those.

## Stack

- Languages: TypeScript, HTML and CSS
- Framework: Astro
- Hosting: Netlify
- Tests: Playwright
- Package manager: npm

## Commands

Run these from the repository root.

- Install dependencies: `npm install`
- Run locally: `npm run dev`
- Build: `npm run build`
- Run all tests: `npx playwright test`
- Run one test file: `npx playwright test tests/path.spec.ts`
- Lint: `npx eslint .`
- Type-check: `npx astro check`
- Format: `npx prettier --write .`

## Project layout

- `src/pages/`: File-based routes (.astro, .md, endpoints)
- `src/content/`: Content collection entries (Markdown, MDX)
- `src/content.config.ts`: Collection schemas
- `src/components/`: Astro components and framework islands
- `src/layouts/`: Page layouts
- `public/`: Static files served as-is

## Code style

- Indent with 2 spaces. Never tabs.
- TypeScript runs in strict mode. Do not use `any`; use `unknown` and narrow it, or write the real type.
- Match the style and patterns of the surrounding code, even where you would personally choose differently.
- Delete code you make unused, including imports, flags and files. Do not leave commented-out code behind.
- Every new UI control works with a keyboard, has a visible focus state and an accessible name.

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Change only what the task needs. Do not refactor, rename or reformat unrelated code.

## Product constraints

- Watch the performance budget: no new blocking requests on page load, and justify any bundle-size increase in the change description.
- Public pages must render their main content as HTML on the server, with a unique title, meta description and one h1.

## Project-specific notes

- Default to `.astro` components, which ship zero JavaScript. Use a UI framework component only when it needs interactivity.
- Add the smallest client directive that works: prefer `client:visible` or `client:idle` over `client:load`.
- Content lives in content collections with a schema in `src/content.config.ts`; query it with `getCollection`, not file globs.
- Every page sets a unique `<title>`, meta description and canonical URL through the shared layout.
- Use the `<Image />` component from `astro:assets` for local images so they are optimized and sized.
- Run `npx astro check` after changing components or collection schemas.

## Project phase

This project is in active development. Follow the patterns that already exist; consistency beats novelty.
CLAUDE.mdFor Claude Code
# CLAUDE.md

@AGENTS.md

## Claude Code

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file, so every agent stays in sync.
- Put Claude-only preferences below this line. Personal, uncommitted notes belong in CLAUDE.local.md.
GEMINI.mdFor Gemini CLI
# GEMINI.md

@./AGENTS.md

## Gemini CLI

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file.
- Alternative: delete this file and set "context": { "fileName": ["AGENTS.md"] } in .gemini/settings.json so Gemini CLI reads AGENTS.md directly.
.github/copilot-instructions.mdFor GitHub Copilot
# Copilot instructions

Project: astro-site. A content-focused Astro site with Markdown content collections and static output.

The full instructions are in AGENTS.md at the repository root. Read it before you change code; if anything here disagrees with it, AGENTS.md wins. The essentials are repeated below for Copilot surfaces that only read this file.

## Stack

- Languages: TypeScript, HTML and CSS
- Framework: Astro
- Hosting: Netlify
- Tests: Playwright
- Package manager: npm

## Commands

- Install dependencies: `npm install`
- Run locally: `npm run dev`
- Build: `npm run build`
- Run all tests: `npx playwright test`
- Run one test file: `npx playwright test tests/path.spec.ts`
- Lint: `npx eslint .`
- Type-check: `npx astro check`
- Format: `npx prettier --write .`

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Change only what the task needs. Do not refactor, rename or reformat unrelated code.
.cursor/rules/project.mdcFor Cursor
---
description: Project instructions for every task (mirrors AGENTS.md)
globs:
alwaysApply: true
---

# Project rules

The project instructions live in @AGENTS.md at the repository root, which Cursor loads automatically. They are not repeated here, so they cost context only once. Edit AGENTS.md, not this rule.

Before you change code, check the Commands and Working rules sections of AGENTS.md, and run its test and lint commands before you say a task is done.

Put Cursor-only rules below, or add scoped rules as more .mdc files with `globs` (for example `src/components/**/*.tsx`).

These are the exact files the generator writes for this preset. Change any command or rule in the generator and download your own set.

About the Astro preset

What Is in the Astro AGENTS.md?

The preset describes a a content-focused Astro site with Markdown content collections and static output. Its AGENTS.md is 49 non-empty lines with 8 exact commands, 6 key directories, and 6 stack-specific rules on top of the shared working rules.

  • Commands: npm install, npm run dev, npm run build, npx playwright test, npx playwright test tests/path.spec.ts, npx eslint ., npx astro check, npx prettier --write ..
  • Layout: src/pages/, src/content/, src/content.config.ts, src/components/, src/layouts/, public/.
  • Wrappers: CLAUDE.md and GEMINI.md import AGENTS.md; the Copilot file repeats the essentials; the Cursor rule points to AGENTS.md.

Why These Rules for Astro?

Islands are opt-in for a reason

Astro pages are fast because they ship no JavaScript by default. An agent that wraps a static list in a React component with client:load adds a framework runtime for nothing. The rule makes interactivity a deliberate choice.

Content collections catch typos

A schema validates every Markdown frontmatter field at build time, so a missing date or misspelled tag fails loudly instead of rendering a broken page. Agents prefer quick globs, which skip validation.

Images are a performance budget

Raw <img> tags skip resizing and dimension hints, causing layout shift and heavy pages. The Image component handles both.

SEO is the point of a content site

Duplicate titles and missing descriptions are the most common defects on generated pages; routing them through one layout keeps them consistent.

Which Stack Rules Does the File Add?

  • Default to .astro components, which ship zero JavaScript. Use a UI framework component only when it needs interactivity.
  • Add the smallest client directive that works: prefer client:visible or client:idle over client:load.
  • Content lives in content collections with a schema in src/content.config.ts; query it with getCollection, not file globs.
  • Every page sets a unique <title>, meta description and canonical URL through the shared layout.
  • Use the <Image /> component from astro:assets for local images so they are optimized and sized.
  • Run npx astro check after changing components or collection schemas.

How Do You Add These Files to a Astro Repository?

  1. Download the zip above. It is laid out exactly as the files go into the repository.
  2. Unzip it at the repository root. AGENTS.md, CLAUDE.md and GEMINI.md go next to your README; the Copilot file goes in .github/ and the Cursor rule in .cursor/rules/.
  3. Open AGENTS.md and check every command against your package scripts or Makefile.
  4. Delete wrappers for tools your team does not use, and any old .cursorrules or .windsurfrules file.
  5. Commit, then run the linter on AGENTS.md whenever you change it.

Want different commands or rules? Load this preset into the generator, change anything, and download your own set.

Which Agents Will Read These Files?

AGENTS.md is read directly by Codex, Cursor, Windsurf, Cline, Zed and Jules, and by GitHub Copilot's cloud agent, code review and CLI. Claude Code reads it through the generated CLAUDE.md, and Gemini CLI through GEMINI.md. See the compatibility table for details, last verified 2026-11-13.

Which Similar Stacks Are in the Library?

All presets are on the stacks page.

Frequently Asked Questions

Can an Astro site use React or Vue components?

Yes, through official integrations. The rule only asks the agent to use them where interactivity is needed and to hydrate them as late as possible.

Does this template support server rendering?

It assumes static output. If you use an adapter for on-demand rendering, note which routes are server-rendered in the generator so the agent knows.

Why Playwright instead of unit tests?

A content site has little logic and a lot of pages. A few end-to-end checks that pages render, link and pass accessibility checks catch more real problems.

Are these Astro files free to use?

Yes. Copy them into any project, commercial or not, without attribution. They are a starting point: adjust the commands and rules to match your repository.

How Can You Verify That Nothing Leaves This Browser?

You do not have to take our word for it. Developer tools show every request a page makes, so you can watch this page work and confirm that nothing you type is sent. The check takes under a minute.

  1. Open your browser developer tools with F12, or Cmd+Option+I on a Mac, and select the Network tab.
  2. Reload the page and let it finish. You will see the page's own files, its web fonts, and one anonymous page-view request. Nothing has been typed yet, so none of them can contain your input.
  3. Click the clear icon in the Network tab so that the log is empty.
  4. Switch between the file tabs, copy a file and download the zip.
  5. Look at the Network tab again. It is still empty. Downloads are built in the page as Blob URLs, so even the zip never touches a server. For extra proof, turn on offline mode after the page loads: everything keeps working.

Only the feedback form can add a line to that log, and it sends only the vote and comment you type into it. 2prompt has no server code at all: no API, no model and no database of your files. The production site also sends a Content-Security-Policy header that tells your browser to refuse connections to anywhere except this site, the fonts and the anonymous analytics endpoint.

Was this helpful?