JordanChoo/acfs-agent-skills

astro-site

Logique de décision pour les projets Astro statiques dans cet environnement. Objectif : maintenir la cohérence des nouveaux sites avec la lignée astro-template et éviter les pièges récurrents en SEO/build.

Déclencheurs

Chargez cette compétence si l'UN des éléments suivants est présent :

• Fichiers : astro.config.{mjs,ts,js}, src/content.config.ts, src/content/, fichiers *.astro
• Dépendances : astro, @astrojs/mdx, @astrojs/sitemap, @astrojs/rss, @tailwindcss/vite, astro-custom-toc
• Mentions utilisateur : astro, content collection, sitemap, MDX, RSS, Tailwind v4, WP migration, redirect, getCollection, <Image>

Signature de pile canonique

Les projets Astro de cette lignée partagent une pile restreinte — confirmez avant de supposer :

"astro": "^5.x"
"@astrojs/mdx", "@astrojs/sitemap", "@astrojs/rss"   # toujours
"@tailwindcss/vite", "tailwindcss": "^4.x"            # Tailwind v4 via le plugin Vite (PAS v3 PostCSS)
"astro-custom-toc"                                    # généralement
"zod": "^4.x"                                         # schémas de contenu
"@astrojs/check"                                      # vérification de types

Si le projet a @astrojs/cloudflare, @astrojs/netlify, @astrojs/vercel, ou @astrojs/node, il s'agit d'un projet Astro rendu côté serveur — la plupart des règles ci-dessous s'appliquent toujours, mais vérifiez d'abord output: dans astro.config.mjs.

Disposition canonique de src/

src/
  components/         # composants .astro / .ts
  config/             # configuration du site (nav, marque, pied de page)
  content/
    blog/
    services/         # ou locations/, team/, projects/, etc.
    team/             # auteurs, référencés depuis blog via reference('team')
  content.config.ts   # schémas Zod pour chaque collection
  data/               # fichiers de données statiques (.ts/.json)
  layouts/            # mises en page de base + par type de page
  pages/              # routes
  styles/
  utils/
public/               # actifs statiques, robots.txt, favicon
prd/PRD.md            # exigences produit (convention du modèle)

Lors de l'ajout d'un nouveau type de contenu, ajoutez d'abord le schéma dans src/content.config.ts, puis ajoutez le répertoire et la première entrée. La couche de contenu d'Astro échoue au build si le répertoire existe mais pas le schéma.

---

Playbooks

Ajouter une collection de contenu

1. Modifiez src/content.config.ts — ajoutez un bloc defineCollection avec loader: glob(...) et un schéma Zod.
2. Utilisez reference('<autre-collection>') pour les références croisées (ex : article de blog → auteur de l'équipe).
3. Utilisez z.coerce.date() pour pubDate afin que les chaînes frontmatter soient analysées correctement.
4. Rendez les champs facultatifs explicites avec .optional() — Astro v5 est strict ; les champs obligatoires manquants font échouer le build.
5. Exécutez npm run check (= astro check) après les modifications de schéma ; il détecte les incohérences schéma/données avant le build.
6. Référence : astro-template/src/content.config.ts est l'exemple canonique (blog + équipe avec reference()).

Ajouter une page ou une route

1. Nouvelle page → src/pages/<route>.astro ou src/pages/<route>/index.astro. Le routage Astro est basé sur le système de fichiers.
2. Si la page doit être exclue du sitemap (page de remerciement, 404, doublons de pagination), mettez à jour le filtre sitemap() dans astro.config.mjs — voir "Discipline du sitemap" ci-dessous.
3. Si vous remplacez ou déplacez un chemin, ajoutez une redirection dans astro.config.mjs (redirects: { '/old': '/new' }). Ne comptez pas sur les 404.
4. Pour les routes dynamiques ([slug].astro), implémentez getStaticPaths() et lisez les collections via getCollection('<nom>').

Discipline du sitemap (piège récurrent)

Chaque projet de cette lignée filtre le sitemap. Modèle :

sitemap({
  filter: (page) => {
    const path = new URL(page).pathname;
    // Pages de pagination en double
    if (/\/blog\/\d+\/$/.test(path)) return false;
    if (/\/blog\/tags\/[^/]+\/\d+\/$/.test(path)) return false;
    if (/\/blog\/categories\/[^/]+\/\d+\/$/.test(path)) return false;
    // Pages sans indexation
    if (path === '/thank-you/') return false;
    if (path === '/404/') return false;
    return true;
  },
  changefreq: 'weekly',
  priority: 0.7,
  lastmod: new Date(),
})

Lors de l'ajout de routes paginées (tags, catégories, archives annuelles), étendez le filtre en même temps. Sinon, le sitemap se remplit de /blog/2/, /blog/3/, etc. et dilue le SEO.

Migration WordPress (cas d'usage récurrent)

Deux projets de cette lignée ont migré depuis WordPress (arp-astro, gkn-static). Le modèle :

1. Redirections — chaque ancienne URL WP a besoin d'une entrée redirects: dans astro.config.mjs. Modèles de chemins WP courants : /feed, /feed/atom, /?p=N, /category/..., /tag/..., /<slug> (règles de réécriture WP), et les chemins singuliers /service/... ou /location/....
2. Slash final — définissez trailingSlash: 'always' si le site WP utilisait des slashes finaux, pour garder les URL canoniques stables. Des slashes finaux incompatibles brisent les liens entrants et les classements de recherche.
3. Scripts de migration — gkn-static a scripts/migrate/{parse,transform,extract,media,redirects,validate}.ts piloté par npm run migrate:all. Si vous commencez une nouvelle migration WP, copiez cette structure de script plutôt que d'improviser.
4. Validez avant le lancement : lancez un crawl de l'ancien site, diffèrez-le avec le nouveau sitemap, confirmez que chaque ancienne URL résout ou redirige.

Pièges Tailwind v4 (cette lignée est en v4)

• Le plugin est @tailwindcss/vite, PAS le plugin v3 PostCSS. N'ajoutez pas postcss.config.js.
• La configuration vit dans le CSS via des blocs @theme { ... }, pas tailwind.config.js. Certains agents ajoutent par réflexe un fichier de configuration de style v3 — ne le faites pas.
• @tailwindcss/typography fonctionne en v4 mais est configuré différemment — vérifiez les src/styles/ existants avant d'ajouter.
• Les noms de classes se transfèrent majoritairement depuis v3, mais certains noms d'utilitaires ont changé (ex : échelle d'ombre). Lorsque vous portez des exemples v3, vérifiez dans la documentation v4.

Images

astro:assets d'Astro v5 est le bon outil — import { Image } from 'astro:assets' et passez un actif importé (pas un chemin de chaîne). Pour les images du frontmatter de collection, utilisez image() dans le schéma Zod :

schema: ({ image }) => z.object({
  cover: image(),
  ...
})

Cela vous donne automatiquement width/height/format et permet à la pipeline de build d'optimiser.

Build, check et tests

• npm run check (= astro check) — vérifie les types .astro + les schémas de contenu. Exécutez avant chaque PR.
• npm run build — strict ; échoue en cas de références de collection cassées, frontmatter obligatoire manquant, liens cassés dans MDX.
• npm run test — Vitest avec happy-dom ; principalement des tests unitaires pour les utilitaires, pas le rendu des pages.
• npm run dev — HMR. Les modifications de schéma de contenu nécessitent parfois un redémarrage complet, pas seulement HMR.

Beads (suivi des problèmes) — notez la version

Ces projets utilisent bd (beads legacy), pas br (beads_rust). Si vous mettez à jour des documents ou commandes de workflow, la compétence bd-to-br-migration s'applique — mais ne migrez pas sauf demande explicite, car le reste des outils du projet attend bd.

---

Drapeaux rouges — arrêtez-vous et demandez

• Ajout de tailwind.config.js ou postcss.config.js — c'est Tailwind v4, configurez dans le CSS à la place
• Un nouveau répertoire de contenu sous src/content/ sans defineCollection correspondant dans src/content.config.ts
• Nouvelles routes paginées sans mise à jour du filtre de sitemap
• Remplacement/renommage d'une page sans ajout d'une redirection
• Chemins d'image sous forme de chaîne nue (<img src="/photos/foo.jpg">) dans des endroits où astro:assets devrait être utilisé — perte d'optimisation
• Changement de output: de static à server sans adaptateur et plan de déploiement correspondant
• Ajout d'une fonctionnalité côté serveur (routes API, SSR dynamique) à un projet qui n'a ni adaptateur ni histoire de déploiement pour SSR

---

Que lire en premier dans un dépôt Astro inconnu

1. astro.config.mjs — URL du site, intégrations, redirections, filtre sitemap, mode de sortie
2. src/content.config.ts — chaque schéma de collection ; vérifiez avant de modifier tout frontmatter markdown
3. Scripts package.json — confirmez que dev/build/check/test sont les noms conventionnels
4. src/layouts/ — les mises en page de base enveloppent chaque page ; SEO/méta vit ici
5. src/config/ — configuration à l'échelle du site (navigation, pied de page, marque)
6. prd/PRD.md si présent — exigences produit pour ce site spécifique
7. CLAUDE.md / AGENTS.md pour les surcharges spécifiques au projet