Astro Dev
Use the project's installed Astro version and local conventions as the source of
truth. The references in this skill capture current Astro 7 patterns and common
migration traps; they do not justify broad refactors outside the user's request.
Quick Start
- Read
package.json, the lockfile, astro.config.*, and the target files.
- Confirm the installed Astro, Node, adapter, integration, and content setup
relevant to the task.
- Read only the matching reference from the router below.
- For a version-sensitive or unfamiliar API, verify the exact current behavior
in official Astro docs using the available official docs capability. Read
references/doc-endpoints.md only when that lookup is needed.
- Make the smallest change that completes the requested outcome and preserves
the repo's component, styling, and deployment conventions.
- Run the relevant type/check/build/test commands. For visible behavior, render
the affected route and exercise the states in scope.
Reference Router
| Task |
Read |
| Project setup, core APIs, file shape, scripts, middleware, Astro 7 upgrade or advanced routing |
references/astro-core-patterns.md |
| Build-time or live content collections, loaders, querying, Zod 4 |
references/content-collections.md |
| RSS, pagination, tags, SEO, TOC, Shiki, Markdown/MDX customization |
references/blog-recipes.md |
| Tailwind CSS v4, themes, fonts |
references/tailwind.md |
Islands and client:* hydration |
references/islands-and-hydration.md |
| Actions, forms, validation, mutations |
references/actions-and-forms.md |
<ClientRouter />, lifecycle events, state preservation |
references/view-transitions.md |
| Prerendering, sessions, env, i18n, CSP, caching, Cloudflare |
references/server-features.md |
| Official docs search and fallback URLs |
references/doc-endpoints.md |
Do not preload every reference. If a task crosses two domains, read those two;
the router is not a checklist.
Compatibility Gate
Check only the rows touched by the task.
| Area |
Current baseline |
| Content |
src/content.config.ts; every collection has a loader; import z from astro/zod; call standalone render(entry) |
| Tailwind |
Use the installed Tailwind v4 setup, normally @tailwindcss/vite plus @import "tailwindcss"; do not reintroduce deprecated @astrojs/tailwind |
| Markdown/MDX |
Astro 7 defaults to Sätteri; use markdown.processor and choose Sätteri or unified based on the project's plugin requirements |
| Hydration |
client:load for immediately interactive UI; client:idle or client:visible for deferred islands; do not hydrate static markup |
| Mutations |
Prefer typed Actions for app forms; pages that need cookies, sessions, Actions, POST handling, or per-request data must render on demand |
| Environment |
Prefer schema-backed astro:env in app code; distinguish build-time import.meta.env from documented runtime/config-time exceptions |
| ClientRouter |
Initialize with astro:page-load, use delegation for swapped elements, and set pre-paint state in astro:before-swap |
| Astro 7 |
Node 22.12+, Vite 8, ESM config; strict HTML parsing; JSX whitespace default; reserved src/fetch.ts; top-level cache and route rules |
Removed patterns such as Astro.glob(), entry.render(), legacy collection
locations/types, output: 'hybrid', CJS config, and <ViewTransitions /> should
not be copied into new code. Use references/astro-core-patterns.md for the
complete mapping when a migration touches them.
Implementation Workflow
1. Bound the change
State the requested behavior and the files likely to own it. Preserve public
routes, content IDs, adapter behavior, and design-system conventions unless the
request explicitly changes them. Do not add integrations, client frameworks, or
new abstractions merely because Astro supports them.
2. Inspect before choosing an API
- Check package-manager scripts and installed package versions.
- Check whether the route is prerendered or on demand.
- Check the adapter/runtime before using Node APIs or server features.
- Check existing content loaders, Actions, middleware, and style entry points.
- Search the repo for an established solution before introducing another one.
3. Implement at the right boundary
Keep route files focused on routing, data loading, and assembly. Reuse existing
layouts/components/helpers. Split a file only when the requested change would
otherwise mix responsibilities or make verification harder; do not turn a small
fix into a repo-wide reorganization.
Choose server-rendered Astro markup by default. Add a client island only when the
browser needs state or immediate interaction, and choose the least eager
directive that still preserves the intended interaction.
4. Verify behavior
Use the project's package manager and existing scripts first. In proportion to
the change, verify:
- Astro/type checks and targeted tests
- production build for config, integration, routing, or deployment changes
- the affected route in the target runtime for server behavior
- desktop/mobile rendering and primary interaction for visible UI work
- migration-specific cases such as invalid HTML, inline whitespace, content IDs,
environment timing, and prerender/on-demand boundaries
Do not claim an upgrade or UI change is complete from static inspection alone.
If the environment cannot run a relevant check, report that exact gap.
Templates
The files under templates/ are starting points, not replacements for inspecting
the repo. Copy only the portions compatible with installed integrations and the
deployment target.
Output Contract
Lead with the completed behavior. Then summarize the scoped files changed and
the checks actually run, including rendered routes or viewports when relevant.
Name any unverified runtime, migration case, or visual state. Add a tutorial only
when the user asks for one.
Gotchas
- The latest-looking API is not necessarily the installed API. Inspect versions
before editing and use official docs for exact version-sensitive behavior.
- Static frontmatter runs at build time; per-request logic needs on-demand
rendering and an appropriate adapter.
class does not automatically pass through Astro components, and scoped styles
do not automatically reach slotted/Markdown content.- Processed
<script> tags are bundled and deduplicated; define:vars implies
inline behavior. Multiple component instances need an instance-safe pattern.
- A passing build does not prove hydration timing, ClientRouter lifecycle, or
responsive layout. Exercise the behavior that changed.
- Avoid opportunistic migrations, dependency additions, and file splitting
outside the user's requested outcome.
1---2name: astro-dev3description: Use when editing .astro/.mdx files, astro.config.*, Astro content collections, client directives, Actions/forms, Tailwind CSS, view transitions, server features, adapters, or upgrades to Astro 7. Routes to current Astro 7 and Zod 4 patterns while guarding against removed Astro 3/4/5/6 APIs. NOT for generic framework-agnostic frontend design or non-Astro projects.4---56# Astro Dev78Use the project's installed Astro version and local conventions as the source of9truth. The references in this skill capture current Astro 7 patterns and common10migration traps; they do not justify broad refactors outside the user's request.1112## Quick Start13141. Read `package.json`, the lockfile, `astro.config.*`, and the target files.152. Confirm the installed Astro, Node, adapter, integration, and content setup16 relevant to the task.173. Read only the matching reference from the router below.184. For a version-sensitive or unfamiliar API, verify the exact current behavior19 in official Astro docs using the available official docs capability. Read20 `references/doc-endpoints.md` only when that lookup is needed.215. Make the smallest change that completes the requested outcome and preserves22 the repo's component, styling, and deployment conventions.236. Run the relevant type/check/build/test commands. For visible behavior, render24 the affected route and exercise the states in scope.2526## Reference Router2728| Task | Read |29|---|---|30| Project setup, core APIs, file shape, scripts, middleware, Astro 7 upgrade or advanced routing | `references/astro-core-patterns.md` |31| Build-time or live content collections, loaders, querying, Zod 4 | `references/content-collections.md` |32| RSS, pagination, tags, SEO, TOC, Shiki, Markdown/MDX customization | `references/blog-recipes.md` |33| Tailwind CSS v4, themes, fonts | `references/tailwind.md` |34| Islands and `client:*` hydration | `references/islands-and-hydration.md` |35| Actions, forms, validation, mutations | `references/actions-and-forms.md` |36| `<ClientRouter />`, lifecycle events, state preservation | `references/view-transitions.md` |37| Prerendering, sessions, env, i18n, CSP, caching, Cloudflare | `references/server-features.md` |38| Official docs search and fallback URLs | `references/doc-endpoints.md` |3940Do not preload every reference. If a task crosses two domains, read those two;41the router is not a checklist.4243## Compatibility Gate4445Check only the rows touched by the task.4647| Area | Current baseline |48|---|---|49| Content | `src/content.config.ts`; every collection has a loader; import `z` from `astro/zod`; call standalone `render(entry)` |50| Tailwind | Use the installed Tailwind v4 setup, normally `@tailwindcss/vite` plus `@import "tailwindcss"`; do not reintroduce deprecated `@astrojs/tailwind` |51| Markdown/MDX | Astro 7 defaults to Sätteri; use `markdown.processor` and choose Sätteri or unified based on the project's plugin requirements |52| Hydration | `client:load` for immediately interactive UI; `client:idle` or `client:visible` for deferred islands; do not hydrate static markup |53| Mutations | Prefer typed Actions for app forms; pages that need cookies, sessions, Actions, POST handling, or per-request data must render on demand |54| Environment | Prefer schema-backed `astro:env` in app code; distinguish build-time `import.meta.env` from documented runtime/config-time exceptions |55| ClientRouter | Initialize with `astro:page-load`, use delegation for swapped elements, and set pre-paint state in `astro:before-swap` |56| Astro 7 | Node 22.12+, Vite 8, ESM config; strict HTML parsing; JSX whitespace default; reserved `src/fetch.ts`; top-level cache and route rules |5758Removed patterns such as `Astro.glob()`, `entry.render()`, legacy collection59locations/types, `output: 'hybrid'`, CJS config, and `<ViewTransitions />` should60not be copied into new code. Use `references/astro-core-patterns.md` for the61complete mapping when a migration touches them.6263## Implementation Workflow6465### 1. Bound the change6667State the requested behavior and the files likely to own it. Preserve public68routes, content IDs, adapter behavior, and design-system conventions unless the69request explicitly changes them. Do not add integrations, client frameworks, or70new abstractions merely because Astro supports them.7172### 2. Inspect before choosing an API7374- Check package-manager scripts and installed package versions.75- Check whether the route is prerendered or on demand.76- Check the adapter/runtime before using Node APIs or server features.77- Check existing content loaders, Actions, middleware, and style entry points.78- Search the repo for an established solution before introducing another one.7980### 3. Implement at the right boundary8182Keep route files focused on routing, data loading, and assembly. Reuse existing83layouts/components/helpers. Split a file only when the requested change would84otherwise mix responsibilities or make verification harder; do not turn a small85fix into a repo-wide reorganization.8687Choose server-rendered Astro markup by default. Add a client island only when the88browser needs state or immediate interaction, and choose the least eager89directive that still preserves the intended interaction.9091### 4. Verify behavior9293Use the project's package manager and existing scripts first. In proportion to94the change, verify:9596- Astro/type checks and targeted tests97- production build for config, integration, routing, or deployment changes98- the affected route in the target runtime for server behavior99- desktop/mobile rendering and primary interaction for visible UI work100- migration-specific cases such as invalid HTML, inline whitespace, content IDs,101 environment timing, and prerender/on-demand boundaries102103Do not claim an upgrade or UI change is complete from static inspection alone.104If the environment cannot run a relevant check, report that exact gap.105106## Templates107108The files under `templates/` are starting points, not replacements for inspecting109the repo. Copy only the portions compatible with installed integrations and the110deployment target.111112## Output Contract113114Lead with the completed behavior. Then summarize the scoped files changed and115the checks actually run, including rendered routes or viewports when relevant.116Name any unverified runtime, migration case, or visual state. Add a tutorial only117when the user asks for one.118119## Gotchas120121- The latest-looking API is not necessarily the installed API. Inspect versions122 before editing and use official docs for exact version-sensitive behavior.123- Static frontmatter runs at build time; per-request logic needs on-demand124 rendering and an appropriate adapter.125- `class` does not automatically pass through Astro components, and scoped styles126 do not automatically reach slotted/Markdown content.127- Processed `<script>` tags are bundled and deduplicated; `define:vars` implies128 inline behavior. Multiple component instances need an instance-safe pattern.129- A passing build does not prove hydration timing, ClientRouter lifecycle, or130 responsive layout. Exercise the behavior that changed.131- Avoid opportunistic migrations, dependency additions, and file splitting132 outside the user's requested outcome.
gigio1023