Frameworks

Astro sites and islands

Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code.

fe-astroastro7 rules73 tokens always loaded, 920 tokens when used, 1501 tokens in references on demand.

Install

init installs this skill when the project uses astro. Pick your agent to see where its files land.

npx github:dawidolko/frontend-skills init

Not tested yet with this runner. npx and pnpm dlx are tested; if this one fails, use one of them.

Without --agents, init finds the agents from what the project already has, and asks when it finds none:

How init finds each of the 17 agents

Agent	Found by
Claude Code	`CLAUDE.md` `.claude` `CLAUDE.local.md`
OpenAI Codex	`.codex` `AGENTS.override.md`
Cursor	`.cursor` `.cursorrules`
GitHub Copilot	`.github/copilot-instructions.md` `.github/instructions` `.github/skills` `.github/prompts`
Gemini CLI	`GEMINI.md` `.gemini`
Antigravity CLI	`.agents/rules` `.agent/rules`
Devin / Windsurf	`.devin` `.windsurf` `.windsurfrules`
OpenCode	`opencode.json` `opencode.jsonc` `.opencode`
Cline	`.clinerules` `.cline`
Zed	`.rules` `.zed`
JetBrains Junie	`.junie`
Kiro	`.kiro`
Augment	`.augment` `.augment-guidelines`
Trae	`.trae`
Continue	`.continue`
Amazon Q Developer	`.amazonq`
Aider	`.aider.conf.yml` `CONVENTIONS.md`

Where fe-astro lands for Claude Code

.claude/skills/fe-astro/SKILL.mdskill
.claude/skills/fe-astro/references/astro.mdskill
.claude/rules/fe-astro.mdrule file
CLAUDE.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.claude/rules/fe-astro.md

---
paths:
  - "**/*.astro"
  - "astro.config.*"
  - "src/content.config.*"
  - "src/pages/**"
  - "src/layouts/**"
  - "src/components/**"
---

# Astro sites and islands (frontend-skills)

Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code.

- Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
- `client:only` names its framework and has a `slot="fallback"` (astro/client-only-framework).
- `client:*` goes only on framework components imported into the `.astro` file, never on Astro components (astro/directive-on-framework-component).
- A `server:defer` island has `slot="fallback"` content and gets small serializable props (astro/server-defer-fallback).
- `<script>` tags carry no attribute but `src` so Astro bundles them; `is:inline` only on purpose; data via `data-*`, not `define:vars` (astro/script-processed).
- Secrets never get the `PUBLIC_` prefix; declare them in `astro:env` as server secrets (astro/public-env-secret).
- Local images live in `src/` and render with `<Image>` or `<Picture>`; never hard-code `/images/...` paths (js/asset-import).
- `set:html` only with trusted or sanitized HTML; it is not escaped.
- Every page has a unique `<title>`; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Before larger changes, read the full skill: `.claude/skills/fe-astro/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-astro lands for OpenAI Codex

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

OpenAI Codex has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

AGENTS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-astro lands for Cursor

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
.cursor/rules/fe-astro.mdcrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.cursor/rules/fe-astro.mdc

---
description: Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code.
globs: **/*.astro, astro.config.*, src/content.config.*, src/pages/**, src/layouts/**, src/components/**
alwaysApply: false
---

# Astro sites and islands (frontend-skills)

- Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
- `client:only` names its framework and has a `slot="fallback"` (astro/client-only-framework).
- `client:*` goes only on framework components imported into the `.astro` file, never on Astro components (astro/directive-on-framework-component).
- A `server:defer` island has `slot="fallback"` content and gets small serializable props (astro/server-defer-fallback).
- `<script>` tags carry no attribute but `src` so Astro bundles them; `is:inline` only on purpose; data via `data-*`, not `define:vars` (astro/script-processed).
- Secrets never get the `PUBLIC_` prefix; declare them in `astro:env` as server secrets (astro/public-env-secret).
- Local images live in `src/` and render with `<Image>` or `<Picture>`; never hard-code `/images/...` paths (js/asset-import).
- `set:html` only with trusted or sanitized HTML; it is not escaped.
- Every page has a unique `<title>`; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Before larger changes, read the full skill: `.agents/skills/fe-astro/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-astro lands for GitHub Copilot

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
.github/instructions/fe-astro.instructions.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.github/instructions/fe-astro.instructions.md

---
applyTo: "**/*.astro,astro.config.*,src/content.config.*,src/pages/**,src/layouts/**,src/components/**"
description: "Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code."
---

# Astro sites and islands (frontend-skills)

- Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
- `client:only` names its framework and has a `slot="fallback"` (astro/client-only-framework).
- `client:*` goes only on framework components imported into the `.astro` file, never on Astro components (astro/directive-on-framework-component).
- A `server:defer` island has `slot="fallback"` content and gets small serializable props (astro/server-defer-fallback).
- `<script>` tags carry no attribute but `src` so Astro bundles them; `is:inline` only on purpose; data via `data-*`, not `define:vars` (astro/script-processed).
- Secrets never get the `PUBLIC_` prefix; declare them in `astro:env` as server secrets (astro/public-env-secret).
- Local images live in `src/` and render with `<Image>` or `<Picture>`; never hard-code `/images/...` paths (js/asset-import).
- `set:html` only with trusted or sanitized HTML; it is not escaped.
- Every page has a unique `<title>`; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Before larger changes, read the full skill: `.agents/skills/fe-astro/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-astro lands for Gemini CLI

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
GEMINI.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Gemini CLI: Gemini CLI was replaced by Antigravity CLI for unpaid tiers on 2026-06-18; choose "antigravity" too if you use it.

Gemini CLI has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

GEMINI.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-astro lands for Antigravity CLI

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
.agents/rules/fe-astro.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.agents/rules/fe-astro.md

---
trigger: glob
globs: "**/*.astro, astro.config.*, src/content.config.*, src/pages/**, src/layouts/**, src/components/**"
description: "Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code."
---

# Astro sites and islands (frontend-skills)

- Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
- `client:only` names its framework and has a `slot="fallback"` (astro/client-only-framework).
- `client:*` goes only on framework components imported into the `.astro` file, never on Astro components (astro/directive-on-framework-component).
- A `server:defer` island has `slot="fallback"` content and gets small serializable props (astro/server-defer-fallback).
- `<script>` tags carry no attribute but `src` so Astro bundles them; `is:inline` only on purpose; data via `data-*`, not `define:vars` (astro/script-processed).
- Secrets never get the `PUBLIC_` prefix; declare them in `astro:env` as server secrets (astro/public-env-secret).
- Local images live in `src/` and render with `<Image>` or `<Picture>`; never hard-code `/images/...` paths (js/asset-import).
- `set:html` only with trusted or sanitized HTML; it is not escaped.
- Every page has a unique `<title>`; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Before larger changes, read the full skill: `.agents/skills/fe-astro/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-astro lands for Devin / Windsurf

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
.devin/rules/fe-astro.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Devin / Windsurf: Devin CLI also reads .cursor/rules; with Cursor chosen too, the CLI sees both rule files of a skill.

Planned by the installer itself for the example React project in the repository.

.devin/rules/fe-astro.md

---
trigger: glob
globs: "**/*.astro,astro.config.*,src/content.config.*,src/pages/**,src/layouts/**,src/components/**"
---

# Astro sites and islands (frontend-skills)

Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code.

- Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
- `client:only` names its framework and has a `slot="fallback"` (astro/client-only-framework).
- `client:*` goes only on framework components imported into the `.astro` file, never on Astro components (astro/directive-on-framework-component).
- A `server:defer` island has `slot="fallback"` content and gets small serializable props (astro/server-defer-fallback).
- `<script>` tags carry no attribute but `src` so Astro bundles them; `is:inline` only on purpose; data via `data-*`, not `define:vars` (astro/script-processed).
- Secrets never get the `PUBLIC_` prefix; declare them in `astro:env` as server secrets (astro/public-env-secret).
- Local images live in `src/` and render with `<Image>` or `<Picture>`; never hard-code `/images/...` paths (js/asset-import).
- `set:html` only with trusted or sanitized HTML; it is not escaped.
- Every page has a unique `<title>`; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Before larger changes, read the full skill: `.agents/skills/fe-astro/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-astro lands for OpenCode

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

OpenCode has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

AGENTS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-astro lands for Cline

.claude/skills/fe-astro/SKILL.mdskill
.claude/skills/fe-astro/references/astro.mdskill
.clinerules/fe-astro.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Cline: If .clinerules is a single file rather than a folder, Cline rule files are not written; skills still are.

Planned by the installer itself for the example React project in the repository.

.clinerules/fe-astro.md

---
paths:
  - "**/*.astro"
  - "astro.config.*"
  - "src/content.config.*"
  - "src/pages/**"
  - "src/layouts/**"
  - "src/components/**"
---

# Astro sites and islands (frontend-skills)

Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code.

- Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
- `client:only` names its framework and has a `slot="fallback"` (astro/client-only-framework).
- `client:*` goes only on framework components imported into the `.astro` file, never on Astro components (astro/directive-on-framework-component).
- A `server:defer` island has `slot="fallback"` content and gets small serializable props (astro/server-defer-fallback).
- `<script>` tags carry no attribute but `src` so Astro bundles them; `is:inline` only on purpose; data via `data-*`, not `define:vars` (astro/script-processed).
- Secrets never get the `PUBLIC_` prefix; declare them in `astro:env` as server secrets (astro/public-env-secret).
- Local images live in `src/` and render with `<Image>` or `<Picture>`; never hard-code `/images/...` paths (js/asset-import).
- `set:html` only with trusted or sanitized HTML; it is not escaped.
- Every page has a unique `<title>`; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Before larger changes, read the full skill: `.claude/skills/fe-astro/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-astro lands for Zed

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
CLAUDE.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Zed: Zed reads only the first instruction file of its list; the block is placed in that file.

Zed has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

CLAUDE.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-astro lands for JetBrains Junie

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

JetBrains Junie: Junie reads .agents/skills only in a trusted project.

JetBrains Junie has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

AGENTS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-astro lands for Kiro

.kiro/skills/fe-astro/SKILL.mdskill
.kiro/skills/fe-astro/references/astro.mdskill
.kiro/steering/fe-astro.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.kiro/steering/fe-astro.md

---
inclusion: fileMatch
fileMatchPattern: ["**/*.astro", "astro.config.*", "src/content.config.*", "src/pages/**", "src/layouts/**", "src/components/**"]
---

# Astro sites and islands (frontend-skills)

Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code.

- Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
- `client:only` names its framework and has a `slot="fallback"` (astro/client-only-framework).
- `client:*` goes only on framework components imported into the `.astro` file, never on Astro components (astro/directive-on-framework-component).
- A `server:defer` island has `slot="fallback"` content and gets small serializable props (astro/server-defer-fallback).
- `<script>` tags carry no attribute but `src` so Astro bundles them; `is:inline` only on purpose; data via `data-*`, not `define:vars` (astro/script-processed).
- Secrets never get the `PUBLIC_` prefix; declare them in `astro:env` as server secrets (astro/public-env-secret).
- Local images live in `src/` and render with `<Image>` or `<Picture>`; never hard-code `/images/...` paths (js/asset-import).
- `set:html` only with trusted or sanitized HTML; it is not escaped.
- Every page has a unique `<title>`; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Before larger changes, read the full skill: `.kiro/skills/fe-astro/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-astro lands for Augment

.agents/skills/fe-astro/SKILL.mdskill
.agents/skills/fe-astro/references/astro.mdskill
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Augment has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

AGENTS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-astro lands for Trae

.trae/skills/fe-astro/SKILL.mdskill
.trae/skills/fe-astro/references/astro.mdskill
.trae/rules/fe-astro.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Trae: Trae reads AGENTS.md only after it is enabled in its settings.

Planned by the installer itself for the example React project in the repository.

.trae/rules/fe-astro.md

---
description: "Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code."
globs: **/*.astro,astro.config.*,src/content.config.*,src/pages/**,src/layouts/**,src/components/**
alwaysApply: false
---

# Astro sites and islands (frontend-skills)

- Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
- `client:only` names its framework and has a `slot="fallback"` (astro/client-only-framework).
- `client:*` goes only on framework components imported into the `.astro` file, never on Astro components (astro/directive-on-framework-component).
- A `server:defer` island has `slot="fallback"` content and gets small serializable props (astro/server-defer-fallback).
- `<script>` tags carry no attribute but `src` so Astro bundles them; `is:inline` only on purpose; data via `data-*`, not `define:vars` (astro/script-processed).
- Secrets never get the `PUBLIC_` prefix; declare them in `astro:env` as server secrets (astro/public-env-secret).
- Local images live in `src/` and render with `<Image>` or `<Picture>`; never hard-code `/images/...` paths (js/asset-import).
- `set:html` only with trusted or sanitized HTML; it is not escaped.
- Every page has a unique `<title>`; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Before larger changes, read the full skill: `.trae/skills/fe-astro/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-astro lands for Continue

.frontend-skills/skills/fe-astro/SKILL.mdskill
.frontend-skills/skills/fe-astro/references/astro.mdskill
.continue/rules/fe-astro.mdrule file

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.continue/rules/fe-astro.md

---
name: "Astro sites and islands"
description: "Writes and reviews Astro 7 sites - islands and client directives, server islands, processed scripts, astro:assets images, content collections and environment variables - so pages ship little JavaScript and stay safe. Use when editing .astro files or astro.config, adding a React, Vue or Svelte island, upgrading from Astro 6, or asked to review Astro code."
globs: ["**/*.astro", "astro.config.*", "src/content.config.*", "src/pages/**", "src/layouts/**", "src/components/**"]
alwaysApply: false
---

# Astro sites and islands (frontend-skills)

- Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
- `client:only` names its framework and has a `slot="fallback"` (astro/client-only-framework).
- `client:*` goes only on framework components imported into the `.astro` file, never on Astro components (astro/directive-on-framework-component).
- A `server:defer` island has `slot="fallback"` content and gets small serializable props (astro/server-defer-fallback).
- `<script>` tags carry no attribute but `src` so Astro bundles them; `is:inline` only on purpose; data via `data-*`, not `define:vars` (astro/script-processed).
- Secrets never get the `PUBLIC_` prefix; declare them in `astro:env` as server secrets (astro/public-env-secret).
- Local images live in `src/` and render with `<Image>` or `<Picture>`; never hard-code `/images/...` paths (js/asset-import).
- `set:html` only with trusted or sanitized HTML; it is not escaped.
- Every page has a unique `<title>`; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Before larger changes, read the full skill: `.frontend-skills/skills/fe-astro/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-astro lands for Amazon Q Developer

.frontend-skills/skills/fe-astro/SKILL.mdskill
.frontend-skills/skills/fe-astro/references/astro.mdskill
.amazonq/rules/frontend-skills.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Amazon Q Developer: Amazon Q Developer IDE plugins reach end of support on 2027-04-30; AWS points to Kiro.

Amazon Q Developer has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

.amazonq/rules/frontend-skills.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

### Skills

- `fe-astro` (Astro sites and islands): when editing `**/*.astro`, `astro.config.*`, `src/content.config.*`, `src/pages/**`, `src/layouts/**`, `src/components/**`, first read `.frontend-skills/skills/fe-astro/SKILL.md`.

The real file

Where fe-astro lands for Aider

.frontend-skills/skills/fe-astro/SKILL.mdskill
.frontend-skills/skills/fe-astro/references/astro.mdskill
CONVENTIONS.mdinstruction block
.aider.conf.ymlconfig

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Aider has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

CONVENTIONS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

### Skills

- `fe-astro` (Astro sites and islands): when editing `**/*.astro`, `astro.config.*`, `src/content.config.*`, `src/pages/**`, `src/layouts/**`, `src/components/**`, first read `.frontend-skills/skills/fe-astro/SKILL.md`.

The real file

How to use it

Once installed, the agent loads the skill by itself when a task matches its description. You can also ask for it in your own words, for example:

And to check and fix the work:

Use the fe-astro skill on this file.
Run the front-end audit on what I changed and fix everything serious.
Explain astro/static-by-default and fix it here.

Rules it teaches

astro/static-by-default
Render framework components without a client directive unless they need interactivity, and pick the latest directive that works.
moderatemanual
astro/client-only-framework
Give client:only the framework of the component (client:only="react"), and a fallback slot for the space it fills.
moderatestatic
astro/directive-on-framework-component
Put client:* directives only on UI framework components imported into the .astro file, never on Astro components.
moderatestatic
astro/server-defer-fallback
A server island (server:defer) has slot="fallback" content of the same size, and receives only small serializable props.
moderatestatic
astro/script-processed
Astro script tags carry no attribute but src so they are bundled; is:inline only on purpose, data-* instead of define:vars.
moderatestatic
astro/public-env-secret
Never give a secret the PUBLIC_ prefix; in Astro those variables are built into client code. Declare secrets in astro:env as server secrets.
seriousstatic
js/asset-import
In a bundled project, images, fonts and media in component markup are imported or use the base-path helper, not hard-coded root paths.
moderatestatic

The rule digest

This part is copied into each agent's scoped rule file, so it stands on its own:

Framework components render without a directive unless they need interactivity; then use the latest directive that works (astro/static-by-default).
client:only names its framework and has a slot="fallback" (astro/client-only-framework).
client:* goes only on framework components imported into the .astro file, never on Astro components (astro/directive-on-framework-component).
A server:defer island has slot="fallback" content and gets small serializable props (astro/server-defer-fallback).
<script> tags carry no attribute but src so Astro bundles them; is:inline only on purpose; data via data-*, not define:vars (astro/script-processed).
Secrets never get the PUBLIC_ prefix; declare them in astro:env as server secrets (astro/public-env-secret).
Local images live in src/ and render with <Image> or <Picture>; never hard-code /images/... paths (js/asset-import).
set:html only with trusted or sanitized HTML; it is not escaped.
Every page has a unique <title>; close every tag and keep valid nesting (Astro 7 errors or no longer repairs it).

Steps the agent follows

Read astro.config.*: integrations (@astrojs/react, vue, svelte), the adapter (needed for server:defer and prerender = false), site, base, image, env.schema.
Keep pages prerendered; opt one route out with export const prerender = false, and personalise parts with server islands instead of making the whole page dynamic.
Use content collections (src/content.config.ts with a loader and a schema) for Markdown and data, and getCollection() to read them.
Pass the above-the-fold image priority on <Image>; give public/ images explicit width and height.
Style with scoped <style> in the component; use is:global or :global() only where needed, and class:list for conditional classes.
For small behaviour without a framework, define a custom element in a processed <script>; it runs once per page and works for every instance.

How the agent checks the work

npx github:dawidolko/frontend-skills audit --changed reports client:only without a framework, directives on Astro components, server islands without fallback, unprocessed scripts, public secrets and hard-coded asset paths.
astro check (with @astrojs/check) type-checks .astro files; astro build fails on unclosed tags in Astro 7.
Use the dev toolbar's Audit app as a first pass, then a browser audit (audit --url).

Checked by the audit

The static checks of these rules run in audit; this is a real session on the example project:

Terminal recording: audit lists findings by severity with rule ids and file:line, and fails at serious. — `audit`: counts by severity, each rule with its first location, the exit code.

Reference files

references/astro.md1501 tokens

SKILL.md on GitHub