my-sveltekit-starter
AGENTS.md1 starsChanged 6 months agoMITView on GitHub
This is a Svelte 5 + SvelteKit 2 + TypeScript + Tailwind CSS v4 project. It uses Svelte 5 runes ($state, $props, $derived, $effect) and shadcn-svelte. Este proyecto usa pnpm. No uses npm ni generes package-lock.json salvo petición explícita. NEVER write raw HTML if a component already exists for that. Before writing <button>, <h1>, <section>, <div class="card">, or similar, check this list. If a component does the job, use it.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository15 other files it gives its agents.
- accessibilitySkill
- deploy-to-vercelSkill
- frontend-designSkill
- nodejs-backend-patternsSkill
- nodejs-best-practicesSkill
- seoSkill
- shadcnSkill
- supabase-postgres-best-practicesSkill
- svelte5-best-practicesSkill
- svelte-code-writerSkill
- tailwind-css-patternsSkill
- tailwind-v4-shadcnSkill
- typescript-advanced-typesSkill
- viteSkill
- vitestSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
23 rules. About 0 are common, 9 are distinctive, and 14 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Before writing <button>, <h1>, <section>, <div class="card">, or similar, check this list.
- Very specific: line 99
Put it in src/lib/components/ui/ if it is generic
- Very specific: line 100
Use <script lang="ts"> with $props()
- Distinctive: line 101
Use Tailwind for styles
- Very specific: line 102
Use $state(), $derived(), $effect() for state
- Very specific: line 108
ALWAYS read src/lib/site-config.ts before changing names, links, or SEO.
- Very specific: line 109
ALWAYS use the components above instead of hand-written HTML.
- Very specific: line 110
ALWAYS translate visible strings with $t('key') if the page uses i18n.
- Very specific: line 295
If loading server data: +page.ts with load()
- Very specific: line 296
If it has a form: +page.server.ts with actions
- Distinctive: line 307
Use Tailwind for styles; avoid custom CSS when Tailwind can do it
- Distinctive: line 313
When the user brings reference from another tool and asks for visual parity with this template:
- Very specific: line 336
When you use Snippet as a type, import with import type:
- Distinctive: line 353
Before touching or writing any implementation code, you must invoke the 'brainstorming' skill.
- Very specific: line 359
Run the /write-plan sequence based on the approved brainstorming.
- Distinctive: line 361
Every single task MUST specify:
- Distinctive: line 369
Write or prepare a verification test/check first.
- Distinctive: line 370
Write the minimal, compliant code required to make it pass.
- Very specific: line 371
Run pnpm run check immediately to ensure 0 errors and 0 warnings before declaring a task complete.
- Distinctive: line 375
If a test, compilation, or runtime execution fails, stop immediately.
- Very specific: line 377
When creating new routes, automatically cross-verify that the endpoint is correctly mapped into sitePages, has its corresponding .md twin …
- Distinctive: line 381
Before declaring any task finished, you MUST run the verification suite:
- Very specific: line 386
Do not mark the task as complete if any step in pnpm run verify fails.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — Instructions for AI assistants
Project: My SvelteKit Starter
This is a Svelte 5 + SvelteKit 2 + TypeScript + Tailwind CSS v4 project.
It uses Svelte 5 runes ($state, $props, $derived, $effect) and shadcn-svelte.
Este proyecto usa pnpm. No uses npm ni generes package-lock.json salvo petición explícita.
GOLDEN RULE — READ THIS FIRST
NEVER write raw HTML if a component already exists for that.
Before writing <button>, <h1>, <section>, <div class="card">, or similar,
check this list. If a component does the job, use it.
<!-- BAD: raw HTML -->
<button class="bg-blue-500 px-4 py-2 rounded-lg">Click</button>
<h1 class="text-4xl font-bold">Title</h1>
<div class="p-6 rounded-xl border bg-card">Content</div>
<!-- GOOD: existing components -->
<Button variant="default">Click</Button>
<h1 class="text-4xl font-bold tracking-tight text-foreground">Title</h1>
<Card class="p-6">
<CardHeader><CardTitle>Content</CardTitle></CardHeader>
<CardContent>...</CardContent>
</Card>shadcn-svelte component catalog
| Component | Import | Key props |
| Button | $lib/components/ui/button | variant="default|secondary|outline|ghost|destructive|link" size="default|sm|lg|icon" href disabled |
| Card | $lib/components/ui/card | Card, CardContent, CardHeader, CardTitle, CardFooter, CardDescription, CardAction |
| Dialog | $lib/components/ui/dialog | open title onclose |
| Input | $lib/components/ui/input | type placeholder bind:value |
| Textarea | $lib/components/ui/textarea | rows placeholder bind:value |
| Label | $lib/components/ui/label | for |
| Skeleton | $lib/components/ui/skeleton | width height class |
| Spinner | $lib/components/ui/spinner | class="size-{n}" |
Project-specific components
| Component | Import | Key props |
| Container | $lib/components/ui/Container.svelte | as="div|section" |
| Section | $lib/components/ui/Section.svelte | variant="default|muted|soft|surface" id |
| Heading | $lib/components/ui/Heading.svelte | level={1|2|3|4} eyebrow kicker align |
| Text | $lib/components/ui/Text.svelte | variant="body|muted|small|label" align |
| Grid | $lib/components/ui/Grid.svelte | columns={n} gap className |
| HeroSection | $lib/components/ui/HeroSection.svelte | eyebrow title subtitle primaryLabel primaryHref secondaryLabel secondaryHref align |
| FeaturesSection | $lib/components/ui/FeaturesSection.svelte | eyebrow title subtitle items=[{icon,title,description}] id |
| Sonner (Toast) | $lib/components/ui/sonner | <Toaster /> in +layout.svelte |
| CopyButton | $lib/components/CopyButton.svelte | text label |
| Newsletter | $lib/components/Newsletter.svelte | title subtitle action buttonLabel |
| AiPrompt | $lib/components/AiPrompt.svelte | placeholder message maxLength |
| JsonLd | $lib/components/JsonLd.svelte | type headline datePublished dateModified description author image faq[] howto[] softwareName softwareCategory |
| Footer | $lib/components/Footer.svelte | Links; translatable copy (layout.footer.*) |
The home (src/routes/+page.svelte) loads copy from i18n (home.* in es.json / en.json). SEO is updated with setSeo inside $effect when the locale changes. Stitch/M3 styles: utilities in src/lib/styles/stitch-m3.css.
The document title in the layout uses {$seo.title} (store in src/lib/seo.ts), not a fixed i18n title string.
Stores and utilities
import { toast } from '$lib/stores/toast';
toast('Message', 'success'); // success | error | info | warning
// Layout mounts `<Toaster />` (Sonner/shadcn) and `<ToastContainer />` for the legacy toast store.
import { mode, toggleMode } from 'mode-watcher';
// mode.current === 'dark' | 'light' | 'system', toggleMode() to toggle
import { clickOutside } from '$lib/actions/clickOutside';
// use:clickOutside={fn} → runs fn on outside click
import { t, locale, setLocale } from '$lib/i18n/index';
// {$t('key')} to translate, setLocale('es'|'en')
import { setSeo } from '$lib/seo';
// setSeo({ title, description, ogImage, ... })
import { reveal } from '$lib/reveal';
// use:reveal={{ stage: 'title'|'content', delay: 120 }}
import { cn } from '$lib/utils';
// cn('foo', 'bar') → merge classes with tailwind-mergeIf the component you need does NOT exist
Then create it. But:
- Put it in
src/lib/components/ui/if it is generic - Use
<script lang="ts">with$props() - Use Tailwind for styles
- Use
$state(),$derived(),$effect()for state
Golden rules (summary)
ALWAYS read src/lib/site-config.ts before changing names, links, or SEO.
ALWAYS use the components above instead of hand-written HTML.
ALWAYS translate visible strings with $t('key') if the page uses i18n.
Key structure
| Folder | Purpose |
src/routes/ | Pages (filesystem routing) |
src/lib/components/ui/ | shadcn-svelte + shared UI |
src/lib/components/ | Project components |
src/lib/i18n/ | ES/EN translations |
src/lib/server/ | Server-only code |
src/app.css | Global CSS, Tailwind v4, shadcn theme variables |
src/lib/styles/stitch-m3.css | Stitch-style M3 tokens (text-h1, etc.) |
static/ | Static assets |
Required Svelte 5 patterns
<script lang="ts">
// Typed props — Svelte 5 style
let { title, items = [] }: { title: string; items?: string[] } = $props();
// Local state
let open = $state(false);
// Derived
const total = $derived(items.length);
// Effect
$effect(() => {
console.log('open changed:', open);
});
</script>Slots → Snippets (Svelte 5)
<!-- BEFORE (Svelte 4) -->
<slot name="header" />
<!-- NOW (Svelte 5) -->
{@render children?.()}Props with $props() — NOT with generics
<!-- BAD -->
let { title } = $props<string>();
<!-- GOOD -->
let { title }: { title: string } = $props();CSS
- Tailwind CSS v4 with
@import "tailwindcss" - shadcn variables:
--primary,--primary-foreground,--background,--foreground,--border,--muted, etc. - Custom variables:
--accent,--text-main,--text-secondary,--bg-main,--bg-soft - Scoped styles per component:
<style>...</style>
SEO + GEO (Generative Engine Optimization)
La plantilla trae SEO técnico y GEO automatizado. Solo es necesario escribir setSeo({...}) en +page.svelte y todo lo demás se inyecta solo desde el layout.
setSeo — único punto de entrada
import { setSeo } from '$lib/seo';
setSeo({
title: '...',
description: '...',
schemaType: 'WebPage', // WebPage | Article | FAQPage | HowTo | CollectionPage | …
keywords: ['svelte', 'starter'],
dateModified: new Date().toISOString(),
author: 'Tu nombre',
// GEO: estos dos campos hacen que ChatGPT/Perplexity te citen
faq: [{ question: '¿…?', answer: '…' }],
howto: [{ name: 'Paso 1', text: '…' }],
// Producto/aplicación (opcional)
softwareName: 'Mi App',
softwareCategory: 'BusinessApplication'
});Qué se inyecta automáticamente desde +layout.svelte
<title>,<meta description>,<meta keywords>,<meta author><link rel="canonical">calculado desde la ruta actual (no hace falta pasarlo)- Open Graph completo (
og:title/description/url/image/type/locale) - Twitter Cards (
summary_large_image) hreflangES/EN yx-default<link rel="alternate" type="text/plain" href="/llms.txt"><link rel="alternate" type="text/markdown">hacia el twin de la ruta (/index.md,/ruta.md)<html lang>resuelto en SSR vía cookieportfolio_locale+Accept-Language- Content negotiation AEO en
hooks.server.ts+ headerLinkHTTP en HTML
Qué se inyecta automáticamente desde JsonLd.svelte
Organizationcon logo ysameAsWebSiteconSearchAction(sitelinks searchbox)- Schema de página (
WebPage/Article/...) coninLanguage BreadcrumbListdesde la URLFAQPagesisetSeo({ faq: [...] })HowTosisetSeo({ howto: [...] })SoftwareApplicationsisetSeo({ softwareName: '...' })
Endpoints GEO (todos dinámicos)
| Endpoint | Propósito | Genera contenido desde |
/sitemap.xml | Índice con hreflang ES/EN | src/lib/site-pages.ts |
/robots.txt | Permisos para crawlers IA (GPTBot, Claude, Perplexity, Gemini, CCBot…) | src/routes/robots.txt/+server.ts |
/llms.txt | Índice Markdown estándar llmstxt.org | site-pages.ts + i18n |
/llms-full.txt | Contenido completo del sitio en Markdown para ingesta directa por LLMs | i18n |
/index.md, /ruta.md | Twins Markdown AEO por página (también vía Accept: text/markdown) | src/lib/aeo/builders/ + i18n |
/api/og?title=… | Open Graph SVG dinámico | parámetro title |
AEO (Markdown twins + content negotiation)
Cada ruta indexable tiene un twin Markdown para agentes IA (spec Dualmark / acceptmarkdown):
| Capa | Qué hace |
hooks.server.ts | Si Accept: text/markdown, URL *.md o User-Agent de crawler IA, responde twin con headers AEO |
+layout.svelte | <link rel="alternate" type="text/markdown" href="…"> |
src/lib/aeo/ | Parser Accept, headers, builders desde i18n, registry |
src/routes/*.md/+server.ts | URLs hermanas (/index.md, /components.md) |
Headers en respuestas twin (no en HTML): Content-Type: text/markdown, Vary: Accept, X-AEO-Version: 1.0, X-Markdown-Tokens, X-Robots-Tag: noindex.
Añadir una página nueva al GEO + AEO
- Crea la ruta en
src/routes/... - Llama a
setSeo({...})en su+page.svelte($effect+$locale) - Añade entrada en
sitePages(src/lib/site-pages.ts) - Añade
buildXxxMarkdownensrc/lib/aeo/builders/y regístralo ensrc/lib/aeo/registry.ts - Crea
src/routes/<slug>.md/+server.ts(home:index.md)
Con eso entra en /sitemap.xml (HTML + .md), /llms.txt, /llms-full.txt y negociación AEO automáticamente.
i18n
import {t} from '$lib/i18n/index';
{$t('key.from.json')}Dark mode
import {(mode, toggleMode)} from 'mode-watcher'; import {(Moon, Sun)} from 'lucide-svelte';
<Button variant="ghost" size="icon" onclick={toggleMode}>
{#if mode.current === 'dark'}
<Moon />
{:else}
<Sun />
{/if}
</Button>Creating a new page
src/routes/my-page/+page.svelte<script lang="ts">at the top with importssetSeo(...)for SEO- If loading server data:
+page.tswithload() - If it has a form:
+page.server.tswithactions +page.sveltemust not useasync— data loading belongs in+page.ts
Creating a new component
- Typed props with
$props() - State with
$state(), derived with$derived() - Generic →
src/lib/components/ui/ - Project-specific →
src/lib/components/ - Use Tailwind for styles; avoid custom CSS when Tailwind can do it
External design → code (Stitch, Lovable, Figma HTML, etc.)
When the user brings reference from another tool and asks for visual parity with this template:
- Do not dump raw HTML without mapping — map blocks to Button, Card, Section, Heading, Grid, etc. from the catalog above.
- Tokens first — align colors and typography with
src/app.css, M3/Stitch utilities insrc/lib/styles/stitch-m3.css, and copy in i18n if the page already uses$t(). - Ask the user (if missing) for screenshots or exported CSS/HTML and breakpoints to respect.
- Finish with
pnpm run checkand summarize what matched vs. what was approximated.
Detailed guide and copy-paste prompt: DESIGN_TO_CURSOR.md.
shadcn-svelte CLI
pnpm dlx shadcn-svelte@latest add <component>Available components: button, card, dialog, skeleton, spinner, sonner, input, textarea, label, accordion, avatar, badge, calendar, checkbox, command, dropdown-menu, form, popover, progress, select, separator, sheet, slider, switch, table, tabs, toggle-group, tooltip
type-only imports
When you use Snippet as a type, import with import type:
<script lang="ts">
import type { Snippet } from 'svelte';
let { children }: { children: Snippet } = $props();
</script>🛠️ DEVELOPMENT METHODOLOGY (Superpowers Framework Integration)
You must strictly override your default ad-hoc behavior to follow the Superpowers skills framework methodology. Never jump straight into code generation or file modifications.
Phase 1: Brainstorming & Architecture Gate
- Before touching or writing any implementation code, you must invoke the 'brainstorming' skill.
- Review the "GOLDEN RULE" of this project: mapping visual references to existing layout/UI catalog components (
Button,Card,Section,Heading,Grid) is non-negotiable. NEVER write raw HTML alternatives. - Present a structural design in clean markdown sections for human validation before proceeding.
Phase 2: Micro-Task Planning (/write-plan)
- Run the
/write-plansequence based on the approved brainstorming. - Break down the implementation into granular, atomic steps.
- Every single task MUST specify:
- Exact file paths to create or modify (respecting the Key Structure table).
- Full, production-ready Svelte 5 Runes syntax (explicit typed props with
$props(), no$props<T>()generics, and properSnippettype-only imports). - Clear verification steps. No placeholders or
// TODOallowed.
Phase 3: Test-Driven Development (TDD)
- Enforce a strict Red-Green-Refactor development cycle.
- Write or prepare a verification test/check first. Watch it fail.
- Write the minimal, compliant code required to make it pass.
- Run
pnpm run checkimmediately to ensure 0 errors and 0 warnings before declaring a task complete.
Phase 4: Systematic Debugging & GEO Validation
- If a test, compilation, or runtime execution fails, stop immediately.
- Trigger 'systematic-debugging' utilizing a strict 4-phase root cause analysis instead of guessing solutions.
- When creating new routes, automatically cross-verify that the endpoint is correctly mapped into
sitePages, has its corresponding.mdtwin server route, and triggerssetSeo({...})using$effect+$localeto avoid breaking the AEO pipeline.
Phase 5: Complete Verification Before Completion
- Before declaring any task finished, you MUST run the verification suite:
pnpm run verify - This runs: static analysis (
oxlint), dead-code analysis (knip), TypeScript check (svelte-check), code style formatting (prettier), unit testing (vitest), and a production compilation check (vite build). - Do not mark the task as complete if any step in
pnpm run verifyfails. Fix all issues and run verify again.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

