astro
Guides building and reviewing Astro sites: .astro components, islands and client directives (client:load, client:visible, client:idle, client:only), file-based routing and getStaticPaths, Content Collections (src/content, src/content.config.ts, Zod schemas), static versus server output and adapters, integrations (Tailwind, MDX, sitemap, astro:assets), environment variables, deployment, performance and security, and bundles a script that checks an Astro project for a missing site option, missing collection config, pages without a layout, images without alt and bare client:only. Use when authoring or reviewing .astro files, astro.config.mjs, a content collection for blog posts, hydration directives on framework components, or a project with astro in package.json, or when an Astro build fails. Not for generic HTML or CSS or WCAG audits (frontend), page copy (copywriting), Playwright tests (web-tester) or GitHub Actions workflow authoring (github-actions).
- License 许可
- Apache-2.0
- 所属仓库
- crewrig/crewrig
- 最近更新
- 2026-11-15
- Stars
- ★ 24
- Forks
- 6
01 前言 Front Matter
- name
- astro
- license
- Apache-2.0
- metadata
- { "provenance": { "version": "2.0.0", "feedback": "https://github.com/crewrig/crewrig", "canonical": "https://github.com/crewrig/crewrig" } }
- description
- Guides building and reviewing Astro sites: .astro components, islands and client directives (client:load, client:visible, client:idle, client:only), file-based routing and getStaticPaths, Content Collections (src/content, src/content.config.ts, Zod schemas), static versus server output and adapters, integrations (Tailwind, MDX, sitemap, astro:assets), environment variables, deployment, performance and security, and bundles a script that checks an Astro project for a missing site option, missing collection config, pages without a layout, images without alt and bare client:only. Use when authoring or reviewing .astro files, astro.config.mjs, a content collection for blog posts, hydration directives on framework components, or a project with astro in package.json, or when an Astro build fails. Not for generic HTML or CSS or WCAG audits (frontend), page copy (copywriting), Playwright tests (web-tester) or GitHub Actions workflow authoring (github-actions).
- compatibility
- Astro 4 or 5 projects; notes say where Astro 5 differs. The bundled script needs Node.js 24 (node scripts/check-astro-project.ts) and reads files only.
02 资源文件 7
- 参考文档references/components.md3.0 KB
- 参考文档references/content-collections.md2.9 KB
- 参考文档references/deployment.md3.4 KB
- 参考文档references/integrations.md2.2 KB
- 参考文档references/performance-security.md2.4 KB
- 参考文档references/routing.md2.3 KB
- 脚本scripts/check-astro-project.ts10.9 KB
03 SKILL.md 正文
Astro
Load this skill for any task on an Astro project: content collections, hydration directives, config and the project check.
Astro renders pages as HTML on the server and ships JavaScript only for the components you mark as islands. Every rule below follows from that bias: start from zero client JavaScript and justify each addition. The model knows the framework basics; this skill holds the conventions, the Astro 4 versus 5 differences and the check that settles the fixed questions.
Hand a change to the security skill when it adds authentication, a secret or untrusted Markdown, and to the frontend skill for CSS, accessibility or Core Web Vitals work that is not specific to Astro.
Decision rules
- Output mode. Use
staticunless a feature needs a server (authenticated routes, form handling, on-demand image transforms). Astro 5 removedoutput: "hybrid": per-page choice isexport const prerender. - Hydration. Default to
client:visibleorclient:idle.client:loadis for above-the-fold interaction,client:mediafor a query-bound widget, andclient:only="<framework>"for code that cannot run on the server; it always names the framework. - Content. Structured Markdown, MDX or JSON goes in a Content Collection with a Zod
schema, not in ad-hoc imports. Astro 5 keeps the config in
src/content.config.tswith aloader; Astro 4 usessrc/content/config.tswithtype. - Dynamic routes. A static
[param]or[...rest]page exportsgetStaticPaths; a server-rendered one readsAstro.params. - Images. Use
<Image>or<Picture>fromastro:assetswith a realalt(alt=""when decorative). The LCP image isloading="eager"withfetchpriority="high"; the others stay lazy. - Pages. Every page sits in a layout so
<head>,langand metadata are shared. - Secrets. Declare variables in the
astro:envschema; a secret iscontext: "server". OnlyPUBLIC_names reach the browser throughimport.meta.env. siteandbase. Setsitealways; sitemap, canonical URLs and RSS need it. Setbasefor a project page on GitHub Pages.
Script
Run it from this skill's directory on the project root; it reads files and writes nothing:
node scripts/check-astro-project.ts <project-dir> [--json]
Run it after you write or change pages, components or astro.config.*, and when
reviewing a project. It reports no-config, site-missing (sitemap integration
without site), site-missing-warn, collection-config (entries under
src/content with no collection config), page-no-layout (warning),
img-missing-alt (<img>, <Image>, <Picture>) and client-only-bare.
| Exit | Meaning |
|---|---|
0 |
No error finding. Warnings may be listed; read them. |
1 |
At least one error finding: fix it and run again. |
2 |
Usage error: pass exactly one directory. |
3 |
The directory cannot be read. |
--json prints one {ok, data, findings} object. The script is a text scan, not a
build: it does not replace astro check and astro build, so report those as not
run when you did not run them. A page that gets its layout through a wrapper that is
not named like a layout is a false positive of page-no-layout.
References
Read one only when its subject is the task.
references/components.md: component syntax, props, slots, scoped styles, the hydration directive table.references/routing.md: file-based routes, dynamic and rest parameters,getStaticPaths, server-rendered routes.references/content-collections.md: schemas, loaders, queries, the Astro 4 and 5 differences, failure modes.references/integrations.md: Tailwind, MDX, sitemap,astro:assetsusage.references/deployment.md: output modes, adapters, build andastro:envconfiguration, per-target deployment; the GitHub Pages workflow is delegated to thegithub-actionsskill.references/performance-security.md: images, fonts, scripts, island budget, secrets, CSP, MDX and form handling.
Friction
When something in this skill misleads or blocks you, tag it with the harness-report skill.
04 同仓库更多 Skills
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.