agentleFS
moisesvaleromoisesvalero/my-sveltekit-starter/AGENTS.md

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.

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
  1. Very specific:

    Before writing <button>, <h1>, <section>, <div class="card">, or similar, check this list.

    line 16
  2. Very specific:

    Put it in src/lib/components/ui/ if it is generic

    line 99
  3. Very specific:

    Use <script lang="ts"> with $props()

    line 100
  4. Distinctive:

    Use Tailwind for styles

    line 101
  5. Very specific:

    Use $state(), $derived(), $effect() for state

    line 102
  6. Very specific:

    ALWAYS read src/lib/site-config.ts before changing names, links, or SEO.

    line 108
  7. Very specific:

    ALWAYS use the components above instead of hand-written HTML.

    line 109
  8. Very specific:

    ALWAYS translate visible strings with $t('key') if the page uses i18n.

    line 110
  9. Very specific:

    If loading server data: +page.ts with load()

    line 295
  10. Very specific:

    If it has a form: +page.server.ts with actions

    line 296
  11. Distinctive:

    Use Tailwind for styles; avoid custom CSS when Tailwind can do it

    line 307
  12. Distinctive:

    When the user brings reference from another tool and asks for visual parity with this template:

    line 313
  13. Very specific:

    When you use Snippet as a type, import with import type:

    line 336
  14. Distinctive:

    Before touching or writing any implementation code, you must invoke the 'brainstorming' skill.

    line 353
  15. Very specific:

    Run the /write-plan sequence based on the approved brainstorming.

    line 359
  16. Distinctive:

    Every single task MUST specify:

    line 361
  17. Distinctive:

    Write or prepare a verification test/check first.

    line 369
  18. Distinctive:

    Write the minimal, compliant code required to make it pass.

    line 370
  19. Very specific:

    Run pnpm run check immediately to ensure 0 errors and 0 warnings before declaring a task complete.

    line 371
  20. Distinctive:

    If a test, compilation, or runtime execution fails, stop immediately.

    line 375
  21. Very specific:

    When creating new routes, automatically cross-verify that the endpoint is correctly mapped into sitePages, has its corresponding .md twin …

    line 377
  22. Distinctive:

    Before declaring any task finished, you MUST run the verification suite:

    line 381
  23. Very specific:

    Do not mark the task as complete if any step in pnpm run verify fails.

    line 386

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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

ComponentImportKey props
Button$lib/components/ui/buttonvariant="default|secondary|outline|ghost|destructive|link" size="default|sm|lg|icon" href disabled
Card$lib/components/ui/cardCard, CardContent, CardHeader, CardTitle, CardFooter, CardDescription, CardAction
Dialog$lib/components/ui/dialogopen title onclose
Input$lib/components/ui/inputtype placeholder bind:value
Textarea$lib/components/ui/textarearows placeholder bind:value
Label$lib/components/ui/labelfor
Skeleton$lib/components/ui/skeletonwidth height class
Spinner$lib/components/ui/spinnerclass="size-{n}"

Project-specific components

ComponentImportKey props
Container$lib/components/ui/Container.svelteas="div|section"
Section$lib/components/ui/Section.sveltevariant="default|muted|soft|surface" id
Heading$lib/components/ui/Heading.sveltelevel={1|2|3|4} eyebrow kicker align
Text$lib/components/ui/Text.sveltevariant="body|muted|small|label" align
Grid$lib/components/ui/Grid.sveltecolumns={n} gap className
HeroSection$lib/components/ui/HeroSection.svelteeyebrow title subtitle primaryLabel primaryHref secondaryLabel secondaryHref align
FeaturesSection$lib/components/ui/FeaturesSection.svelteeyebrow title subtitle items=[{icon,title,description}] id
Sonner (Toast)$lib/components/ui/sonner<Toaster /> in +layout.svelte
CopyButton$lib/components/CopyButton.sveltetext label
Newsletter$lib/components/Newsletter.sveltetitle subtitle action buttonLabel
AiPrompt$lib/components/AiPrompt.svelteplaceholder message maxLength
JsonLd$lib/components/JsonLd.sveltetype headline datePublished dateModified description author image faq[] howto[] softwareName softwareCategory
Footer$lib/components/Footer.svelteLinks; 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-merge

If the component you need does NOT exist

Then create it. But:

  1. Put it in src/lib/components/ui/ if it is generic
  2. Use <script lang="ts"> with $props()
  3. Use Tailwind for styles
  4. 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

FolderPurpose
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.cssGlobal CSS, Tailwind v4, shadcn theme variables
src/lib/styles/stitch-m3.cssStitch-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)
  • hreflang ES/EN y x-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 cookie portfolio_locale + Accept-Language
  • Content negotiation AEO en hooks.server.ts + header Link HTTP en HTML

Qué se inyecta automáticamente desde JsonLd.svelte

  • Organization con logo y sameAs
  • WebSite con SearchAction (sitelinks searchbox)
  • Schema de página (WebPage/Article/...) con inLanguage
  • BreadcrumbList desde la URL
  • FAQPage si setSeo({ faq: [...] })
  • HowTo si setSeo({ howto: [...] })
  • SoftwareApplication si setSeo({ softwareName: '...' })

Endpoints GEO (todos dinámicos)

EndpointPropósitoGenera contenido desde
/sitemap.xmlÍndice con hreflang ES/ENsrc/lib/site-pages.ts
/robots.txtPermisos para crawlers IA (GPTBot, Claude, Perplexity, Gemini, CCBot…)src/routes/robots.txt/+server.ts
/llms.txtÍndice Markdown estándar llmstxt.orgsite-pages.ts + i18n
/llms-full.txtContenido completo del sitio en Markdown para ingesta directa por LLMsi18n
/index.md, /ruta.mdTwins Markdown AEO por página (también vía Accept: text/markdown)src/lib/aeo/builders/ + i18n
/api/og?title=…Open Graph SVG dinámicoparámetro title

AEO (Markdown twins + content negotiation)

Cada ruta indexable tiene un twin Markdown para agentes IA (spec Dualmark / acceptmarkdown):

CapaQué hace
hooks.server.tsSi 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.tsURLs 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

  1. Crea la ruta en src/routes/...
  2. Llama a setSeo({...}) en su +page.svelte ( $effect + $locale )
  3. Añade entrada en sitePages (src/lib/site-pages.ts)
  4. Añade buildXxxMarkdown en src/lib/aeo/builders/ y regístralo en src/lib/aeo/registry.ts
  5. 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

  1. src/routes/my-page/+page.svelte
  2. <script lang="ts"> at the top with imports
  3. setSeo(...) for SEO
  4. If loading server data: +page.ts with load()
  5. If it has a form: +page.server.ts with actions
  6. +page.svelte must not use async — data loading belongs in +page.ts

Creating a new component

  1. Typed props with $props()
  2. State with $state(), derived with $derived()
  3. Generic → src/lib/components/ui/
  4. Project-specific → src/lib/components/
  5. 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:

  1. Do not dump raw HTML without mapping — map blocks to Button, Card, Section, Heading, Grid, etc. from the catalog above.
  2. Tokens first — align colors and typography with src/app.css, M3/Stitch utilities in src/lib/styles/stitch-m3.css, and copy in i18n if the page already uses $t().
  3. Ask the user (if missing) for screenshots or exported CSS/HTML and breakpoints to respect.
  4. Finish with pnpm run check and 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-plan sequence based on the approved brainstorming.
  • Break down the implementation into granular, atomic steps.
  • Every single task MUST specify:
    1. Exact file paths to create or modify (respecting the Key Structure table).
    2. Full, production-ready Svelte 5 Runes syntax (explicit typed props with $props(), no $props<T>() generics, and proper Snippet type-only imports).
    3. Clear verification steps. No placeholders or // TODO allowed.

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 check immediately 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 .md twin server route, and triggers setSeo({...}) using $effect + $locale to 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 verify fails. Fix all issues and run verify again.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.