agentleFS
delineasdelineas/astro-framework-agents/skills/astro-framework/AGENTS.md

astro-framework-agents / astro-framework

AGENTS.md44 starsChanged 8 months agoMITView on GitHub

Version: 2.0.0 | Astro 5.x | Updated: 2026-03-22 | Author: webreactiva.com

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. midudev/la-velada-web-oficial★ 1.9k100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • 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 32,671 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 repository3 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

10 rules. About 1 is common, 1 is distinctive, and 8 are very specific to this project.

  • ≈1

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    NEVER: use client:load on everything — defeats islands architecture

    line 61
  2. Very specific:

    NEVER: use client:only without the framework string argument

    line 62
  3. Very specific:

    NEVER: use plain z.date() for frontmatter dates — use z.coerce.date()

    line 63
  4. Very specific:

    NEVER: use string paths for local images (src="/images/hero.jpg") — import them

    line 64
  5. Distinctive:

    NEVER: use sessions in edge middleware or static pages

    line 68
  6. Very specific:

    NEVER: use any — use unknown and narrow

    line 71
  7. Very specific:

    NEVER: import Zod from zod — use astro/zod (Astro 5+)

    line 72
  8. Very specific:

    Use Referer header inside island to get parent page URL

    line 90
  9. Very specific:

    Import from astro:env/client or astro:env/server

    line 102
  10. Common:

    No secret client vars — not supported by design

    line 104

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Astro Framework Cheatsheet

Version: 2.0.0 | Astro 5.x | Updated: 2026-03-22 | Author: webreactiva.com


Quick Reference Card

TopicRule of Thumb
ComponentsDefine interface Props; frontmatter = server only; use class:list for conditional classes
HydrationDefault: no directive (zero JS). Question every client:
Server Islandsserver:defer for personalized/dynamic server content on cached pages
Content CollectionsContent Layer API with loaders in src/content.config.ts (NOT src/content/config.ts)
Rendering contentimport { render } from 'astro:content' then const { Content } = await render(entry)
RoutingFile-based; getStaticPaths() required for dynamic routes in static mode
Output modesstatic (default), server (all SSR), hybrid (static default, opt-in SSR)
SessionsAstro.session?.get/set; always use optional chaining; SSR only
Env varsastro:env schema with envField for type safety; import from astro:env/client or astro:env/server
ImagesImport local images; use <Image> / <Picture> from astro:assets; always set alt text
i18nUse getRelativeLocaleUrl() for links, never hardcode locale prefixes
TypeScriptExtend astro/tsconfigs/strict; define path aliases; type App.Locals in src/env.d.ts
API routesExport named handlers (GET, POST, etc.) typed as APIRoute

Decision Trees

Output Mode

All static? ──> output: 'static' (default, no adapter)
All dynamic? ──> output: 'server' + adapter
Mix? ──> output: 'hybrid' + adapter
  Opt into SSR (hybrid): export const prerender = false
  Opt out of SSR (server): export const prerender = true

Hydration Directive

Needs interactivity?
├─ No ──> No directive (zero JS)
└─ Yes ──> Above fold + critical? ──> client:load
            Above fold + non-critical? ──> client:idle
            Below fold? ──> client:visible
            Device-specific? ──> client:media="(query)"
            Browser APIs only, skip SSR? ──> client:only="react"

Server Island vs Client Island

Needs server data (cookies, DB, personalization)? ──> server:defer + slot="fallback"
Needs browser interactivity? ──> client:* directive
Neither? ──> Static .astro component

Critical "NEVER Do" List

  • NEVER access window/document in .astro frontmatter (server-only)
  • NEVER use client:load on everything — defeats islands architecture
  • NEVER use client:only without the framework string argument
  • NEVER use plain z.date() for frontmatter dates — use z.coerce.date()
  • NEVER use string paths for local images (src="/images/hero.jpg") — import them
  • NEVER access Astro.request/Astro.cookies/Astro.session in prerendered pages
  • NEVER rely on Astro.url inside a server island (returns internal route; use Referer header)
  • NEVER pass large objects/functions as server island props (IDs only; >2048 bytes forces POST)
  • NEVER use sessions in edge middleware or static pages
  • NEVER forget getStaticPaths() for [param] routes in static output
  • NEVER skip slot="fallback" on server:defer components
  • NEVER use any — use unknown and narrow
  • NEVER import Zod from zod — use astro/zod (Astro 5+)

Astro 5+ Migration Notes (Post-Training Knowledge)

Content Collections (Content Layer API)

  • Config file: src/content.config.ts (was src/content/config.ts)
  • Uses loader property instead of type: 'content' / type: 'data'
  • Loaders: import { glob, file } from 'astro/loaders'
  • Zod: import { z } from 'astro/zod' (NOT from zod package)
  • Rendering: import { render } from 'astro:content' then await render(entry) (was entry.render())
  • reference() for cross-collection relationships; image() schema helper for optimized images

server:defer (Stable in Astro 5)

  • Requires adapter; props must be serializable and small
  • Use Referer header inside island to get parent page URL

Sessions (Astro 5.7+)

  • Astro.session?.get(key) / .set(key, value) — always optional-chain
  • Configure session.driver in config via sessionDrivers from astro/config
  • session.regenerate() after login, session.destroy() on logout
  • Type via App.SessionData in src/env.d.ts

astro:env (Stable in Astro 5)

  • Schema in astro.config.mjs with envField from astro/config
  • Import from astro:env/client or astro:env/server
  • Three kinds: public client (bundled), public server (server bundle), secret server (not bundled)
  • No secret client vars — not supported by design

Actions

  • defineAction from astro:actions with astro/zod schemas

Key Patterns (Brief)

  • Component structure: imports, interface Props, destructure with defaults, logic, template, scoped <style>
  • Slots: Astro.slots.has('name') to conditionally render named slot wrappers
  • Middleware: defineMiddleware from astro:middleware; chain with sequence(a, b); file: src/middleware.ts
  • Pagination: getStaticPaths({ paginate }) returns page.data, page.url.prev/next
  • Redirects: redirects: { '/old': '/new' } in astro.config.mjs
  • Cookies (SSR): Astro.cookies.get('name')?.value / .set('name', value, options)

References

Deep-dive docs with full code examples live in references/:

actions.md client-directives.md components.md configuration.md content-collections.md environment-variables.md i18n-routing.md images.md middleware.md routing.md server-islands.md sessions.md ssr-adapters.md styling.md view-transitions.md

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.