surfskills.surf: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

surfskills.surf — a curated directory of open-source AI agent skills. Astro 5 site deployed to Cloudflare Workers. The catalog is a frozen build-time snapshot (no database at runtime); PostHog handles analytics.

Commands

npm run dev          # astro dev; .dev.vars secrets available via Cloudflare platformProxy
npm run build        # astro build → dist/
npm run preview      # build + wrangler dev — closest to production runtime
npx astro check      # typecheck (.astro + .ts); no npm script for it

There is no test suite and no linter configured.

Git workflow

core.hooksPath is set to .githooks, which blocks committing and pushing to main. Always work on a feature branch and PR into main.

Environment / secrets

Two distinct channels — don't mix them up:

• .env (from .env.example): PUBLIC_* build-time values, inlined by Vite, read via import.meta.env. PostHog key/host.
• .dev.vars (from .dev.vars.example): runtime secrets, read via Astro.locals.runtime.env (typed in src/env.d.ts). Production uses wrangler secret put + wrangler.jsonc vars.

Architecture

Rendering model: static by default, SSR opt-in

astro.config.mjs keeps output: 'static'; marketing/blog/legal pages and the whole catalog prerender. The catalog is a frozen build-time snapshot (content collections), so /discover, /s/[owner]/[repo], /s/[owner]/[repo]/[skill], sitemap.xml.ts, and llms.txt.ts are all prerender = true — the dynamic /s/** routes enumerate every path via getStaticPaths from the snapshot. The homepage (index.astro) is the lone remaining prerender = false route. URLs never have trailing slashes (trailingSlash: 'never' + build.format: 'file' — both are needed so static output serves /discover without a redirect, matching canonicals/sitemap).