Migrate site from Preact SPA to Astro static site

.claude/CLAUDE.md

@@ -4,9 +4,8 @@ This repository contains agent-readable skill files for the Internet Computer. E
 
 ## Key Rules
 
-- **Never edit `src/skills-data.js`** — it is auto-generated and gitignored
 - **Never edit auto-generated files in `public/`** — `llms.txt`, `llms-full.txt`, `.well-known/agent.json`, `.well-known/ai-plugin.json` are all regenerated from SKILL.md sources. These files ARE committed to git (not gitignored) but must only be updated by running `npm run generate`. Note: `sitemap.xml` is generated at build time into `dist/` and is NOT committed.
-- **Never edit `src/app.jsx` to add or update a skill** — the website auto-discovers skills from SKILL.md frontmatter. Only edit app.jsx for site-level UI changes.
+- **Never edit Astro source files to add or update a skill** — the website auto-discovers skills from SKILL.md frontmatter at build time. Only edit `src/` files for site-level UI changes.
 - **One skill = one file** at `skills/<skill-id>/SKILL.md`. No nested directories, no images, no external dependencies within a skill.
 - Skill IDs are **lowercase, hyphenated** (e.g., `ckbtc`, `https-outcalls`, `stable-memory`) and must match the directory name.
 
@@ -38,8 +37,8 @@ Every SKILL.md has YAML frontmatter followed by a markdown body. See `skills/ski
 npm install          # Install dependencies
 npm run validate     # Validate all skills (frontmatter, sections, deps)
 npm run generate     # Regenerate all auto-generated files from SKILL.md sources
-npm run dev          # Validate + generate + start Vite dev server
-npm run build        # Validate + generate + production build
+npm run dev          # Validate + start Astro dev server
+npm run build        # Validate + generate + Astro production build
 ```
 
 ## Workflow
@@ -65,15 +64,39 @@ Both run in CI. Validate blocks deployment on errors. Generate output is checked
 
 DeFi, Tokens, Auth, Architecture, Integration, Governance, Frontend, Security, Infrastructure, Wallet
 
+## Tech Stack
+
+- **Framework**: [Astro](https://astro.build/) — static site generator, zero JS by default
+- **Interactive islands**: [Preact](https://preactjs.com/) — search, filters, copy buttons, theme toggle
+- **Hosting**: GitHub Pages via Actions at `https://dfinity.github.io/icskills/`
+- **Skills**: Plain markdown files in `skills/*/SKILL.md`
+
 ## Project Structure
 
 ```
-skills/*/SKILL.md           # Skill source files (the content)
-skills/skill.schema.json    # JSON Schema for frontmatter
-skills/_template/            # Skeleton for new skills
-scripts/lib/parse-skill.js  # Shared parsing utilities
-scripts/generate-*.js       # Build-time generation scripts
-scripts/validate-skills.js  # Structural validation (CI)
-src/app.jsx                 # Website (auto-discovers skills from frontmatter)
-public/                     # Auto-generated files (committed, but never edit manually)
+skills/*/SKILL.md             # Skill source files (the content)
+skills/skill.schema.json      # JSON Schema for frontmatter
+skills/_template/              # Skeleton for new skills
+scripts/lib/parse-skill.js    # Shared parsing utilities
+scripts/generate-*.js         # Build-time generation scripts
+scripts/validate-skills.js    # Structural validation (CI)
+src/                           # Astro site source
+  data/skills.ts              # Build-time skill loader
+  data/constants.ts           # Static data (API endpoints, frameworks)
+  data/site.ts                # Site URL and base path config
+  layouts/BaseLayout.astro    # HTML shell, meta tags, JSON-LD
+  layouts/SiteLayout.astro    # Shared header/nav/footer for main pages
+  components/BrowseTab.tsx    # Preact island: search + skill grid
+  components/ApiTab.tsx       # Preact island: API reference
+  components/SkillHeader.tsx  # Preact island: skill detail header
+  pages/index.astro           # Browse page
+  pages/how-it-works/         # How it works page (fully static)
+  pages/api/                  # API reference page
+  pages/skills/[slug]/        # Dynamic skill pages (pre-rendered)
+  pages/skills/[slug].md.ts   # Raw .md endpoint per skill
+  pages/llms.txt.ts           # Skills index for agents
+  pages/llms-full.txt.ts      # All skills concatenated
+  pages/.well-known/          # Agent discovery manifests
+public/                        # Auto-generated files (committed, but never edit manually)
+astro.config.mjs              # Astro configuration
 ```

.gitignore

@@ -3,3 +3,5 @@ dist
 .DS_Store
 *.local
 src/skills-data.js
+.astro
+lighthouse-*

README.md

@@ -1,8 +1,8 @@
 # IC Skills
 
-🌐 **https://dfinity.github.io/icskills**
+**https://dfinity.github.io/icskills**
 
-> **⚠️ Under active development** — Skill files are being reviewed and signed off by DFINITY engineers. Content may change. Feedback and PRs are welcome.
+> **Under active development** — Skill files are being reviewed and signed off by DFINITY engineers. Content may change. Feedback and PRs are welcome.
 
 **Agent-readable instructions for every IC need.**
 
@@ -140,17 +140,8 @@ The files are plain markdown. Copy the content into whatever instructions, rules
 | All skills | [`llms-full.txt`](https://dfinity.github.io/icskills/llms-full.txt) | All skills concatenated for direct context injection |
 | Single skill | `https://raw.githubusercontent.com/dfinity/icskills/main/skills/{id}/SKILL.md` | Raw markdown for one skill |
 | Agent discovery | [`.well-known/agent.json`](https://dfinity.github.io/icskills/.well-known/agent.json) | Machine-readable skill manifest |
-
-## REST API (Planned)
-
-| Endpoint | Description |
-|----------|-------------|
-| `GET /skills` | List all skills with metadata |
-| `GET /skills/{id}` | Full structured skill data |
-| `GET /skills/{id}/raw` | Raw SKILL.md for direct context injection |
-| `GET /skills/{id}/deps` | Dependency tree |
-| `GET /skills/search?q={query}` | Search by task description |
-| `GET /skills/{id}/pitfalls` | Just the pitfalls (guardrails only) |
+| Skill page (HTML) | [`/skills/{id}/`](https://dfinity.github.io/icskills/skills/ckbtc/) | Pre-rendered skill page with full SEO |
+| Skill page (MD) | [`/skills/{id}.md`](https://dfinity.github.io/icskills/skills/ckbtc.md) | Raw markdown served with `text/markdown` content type |
 
 ## Contributing
 
@@ -160,11 +151,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add or update skills.
 
 ## Tech Stack
 
-- **Site**: [Preact](https://preactjs.com/) + [Vite](https://vite.dev/) — 3kb runtime, ~16kb gzipped total
+- **Site**: [Astro](https://astro.build/) — static site generator, zero JS by default. Interactive islands with [Preact](https://preactjs.com/) (~18kb gzipped total)
 - **Hosting**: GitHub Pages via Actions
 - **Skills**: Plain markdown files in `skills/*/SKILL.md`
 - **Validation**: Structural linter for frontmatter, sections, and dependency graph (`npm run validate`)
 - **Schema**: JSON Schema for frontmatter at `skills/skill.schema.json`
+- **SEO**: Per-skill meta tags, JSON-LD (TechArticle), sitemap, canonical URLs
+- **AI Agent Discovery**: `llms.txt`, `llms-full.txt`, `.well-known/agent.json`, `.well-known/ai-plugin.json`, per-skill `.md` endpoints
 
 ## License
 

astro.config.mjs

@@ -0,0 +1,12 @@
+import { defineConfig } from 'astro/config';
+import preact from '@astrojs/preact';
+import sitemap from '@astrojs/sitemap';
+
+export default defineConfig({
+  site: 'https://dfinity.github.io',
+  base: '/icskills',
+  integrations: [preact(), sitemap()],
+  build: {
+    format: 'directory',
+  },
+});