carlosvin · carlosvin · May 11, 2026 · May 9, 2026 · May 10, 2026 · May 10, 2026
diff --git a/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md b/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,3 +1,13 @@
+<!-- intent-skills:start -->
+## Skill Loading
+
+Before substantial work:
+- Skill check: run `pnpm dlx @tanstack/intent@latest list`, or use skills already listed in context.
+- Skill guidance: if one local skill clearly matches the task, run `pnpm dlx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
+- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
+- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
+<!-- intent-skills:end -->
+
 # Agent Instructions
 
 This document is the default agent and contributor guide for projects built from this template. It covers project structure, conventions, tooling, and operational detail.

diff --git a/README.md b/README.md
@@ -8,43 +8,45 @@ Built with [TanStack Start](https://tanstack.com/start) — with every external
 
 **[Live Demo](https://leafy-manatee-16b96c.netlify.app)** | **[Blog Post](building-ai-promptable-fullstack-apps.md)**
 
-## Quick Start
+## Use the Agent Skill
 
 ```bash
-# Clone the template
-git clone https://github.com/carlosvin/tanstack-fullstack-ai-template.git
-cd tanstack-fullstack-ai-template
+npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
+```
 
-# Install dependencies
-pnpm install
+Optional: `-g` installs globally; `npx skills add carlosvin/tanstack-fullstack-ai-template --list` lists skills from this repo; `npx skills list` verifies installed skills.
 
-# Start the dev server (uses in-memory seed data, no DB required)
-pnpm dev
-```
+The **TanStack Promptable Fullstack** skill is an [Agent Skill](https://agentskills.io) that teaches coding assistants the template’s **architecture contract**: interface-first boundaries, three schema layers with `Schema.parse()` at each boundary, thin routes + loaders (no `useEffect` data fetching for route data), URL state via `validateSearch`, repository interfaces, AI tools aligned with server functions, auth + invalidation on mutations, and TypeScript discipline inside the typed flow. **[AGENTS.md](./AGENTS.md)** stays the **handbook** (UI, auth snippets, chat, tests, checklist); the skill is the **rules agents must not break**.
 
-Open [http://localhost:3000](http://localhost:3000). The app works immediately with seed data — no database, no API keys, no configuration needed.
+**Why it helps:** fewer regressions when scaffolding features, migrating code, or refactoring routes — agents follow the same non-obvious invariants the template depends on.
 
-## Install The Skill (npx skills)
+**When to use it:** starting from this template, adding entities or AI tools, adopting the pattern in another TanStack Start app, or fixing duplicated parent/child route work.
 
-You can install this repository's generated Agent Skill directly from GitHub:
+### Other ways to install
 
-```bash
-# List skills available in this repository
-npx skills add carlosvin/tanstack-fullstack-ai-template --list
+- **Shell installer** (Cursor / Windsurf / Claude Code global dirs):  
+  `curl -sL https://raw.githubusercontent.com/carlosvin/tanstack-fullstack-ai-template/main/scripts/skills/install.sh | bash -s -- --force`
+- **Manual copy:** copy `.agents/skills/tanstack-promptable-fullstack-app-template/` to `~/.cursor/skills/`, `~/.claude/skills/`, or your editor’s documented skills path.
+- **Using this repo as-is:** Windsurf and compatible tools can read `.agents/skills/` directly — no extra step.
 
-# Install the TanStack fullstack pattern skill
-npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
+More user-focused detail: **[skills/README.md](./skills/README.md)** · Editing/regenerating the skill (YAML, CI): **[skills/AUTHORING.md](./skills/AUTHORING.md)**.
 
-# Optional: install globally (available across projects)
-npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template -g
+### Try it
 
-# Optional: verify installed skills
-npx skills list
-```
+Ask your agent:
 
-The skill is published in the standard location used by the CLI:
+- "What are the core contract items in the TanStack fullstack skill I must not violate?"
+- "Add a new domain entity following this template’s schema layers, repository, server functions, routes, and AI tools."
+- "Should any of my nested routes move shared `beforeLoad` or loader work to a parent layout?"
 
-- `.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md`
+### What the skill enforces (outcomes)
+
+- **One tools-layer schema** for both server functions and AI tools; **parse both ways** (tools ↔ repo) at mapper boundaries.
+- **Thin routes**; **loaders** fetch data; **URL search params** hold filters/tabs/selections with `loaderDeps` for cache keys.
+- **POST mutations** use auth + invalidation middleware; callers normalize errors consistently for UI and AI.
+- **AI:** expose repository capabilities as tools; client **navigate** / **invalidateRouter**; gate chat on availability; bounded agent loop in `chat()`.
+- **Parent layouts** own shared guards and expensive reads; children read parent loader data instead of duplicating work.
+- **TypeScript** after parsing: preserve inference — prefer `satisfies`, exhaustive handling, and guards over `any` and loose `as` casts.
 
 ## Architecture
 
@@ -271,27 +273,45 @@ Create a new class implementing `AIAdapterService` from `src/services/ai/types.t
 
 Replace Mantine imports in components. The architectural layers (repository, server functions, middleware) are unaffected.
 
-## Scripts
+## Generated Example
+
+You can easily run it just by.
+
+```bash
+
+# Install dependencies
+pnpm install
+
+# Start the dev server (uses in-memory seed data, no DB required)
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000). The app works immediately with seed data — no database, no API keys, no configuration needed.
+
+### Run it with Docker
 
 ```bash
+docker build -t my-app .
+docker run --rm -p 3000:3000 my-app
+```
+
+### Scripts
+
+```bash
+# commands for the app generated by the skill
 pnpm dev        # Start dev server on port 3000
 pnpm build      # Production build
 pnpm start      # Run production server
 pnpm test       # Run unit tests (Vitest)
 pnpm test:e2e   # Run E2E tests (Playwright, uses seed data)
 pnpm lint       # Lint + typecheck (Biome)
 pnpm format     # Auto-format (Biome)
+
+# skill dev commands
 pnpm skills:build  # Generate Cursor + markdown skill artifacts
 pnpm skills:check  # Validate canonical skills and check for drift
 ```
 
-## Docker
-
-```bash
-docker build -t my-app .
-docker run --rm -p 3000:3000 my-app
-```
-
 ## Tech Stack
 
 - **Framework**: [TanStack Start](https://tanstack.com/start) (full-stack React with SSR)
@@ -328,70 +348,9 @@ Then follow the end-to-end workflow:
 6. Create file-based routes under `src/routes/` (data in loaders, state in URL search params)
 7. When ready for real data, implement `mongoRepository.ts` and set `MONGODB_URI`
 
-### Option B: AI-Assisted via Generated Skill (New or Existing Project)
-
-The skill is defined once in a canonical YAML source and generated into the [agentskills.io](https://agentskills.io) standard at `.agents/skills/tanstack-promptable-fullstack-app-template/`. Windsurf and other compatible tools read this path directly.
-
-The generated outputs are committed intentionally so you can copy the skill into another project or tool without running the build pipeline first. The machine-readable metadata lives in `skills/registry.json`, and the portable markdown copy lives in `skills/dist/`.
-
-**Use the skill in this repo:** clone the template — the skill is at `.agents/skills/tanstack-promptable-fullstack-app-template/`.
-
-**Install the skill globally** (available in all your projects):
-
-Run this one-liner in your terminal to automatically download and install the skill into the global directories for Cursor, Windsurf, and Claude Code:
-
-```bash
-curl -sL https://raw.githubusercontent.com/carlosvin/tanstack-fullstack-ai-template/main/scripts/skills/install.sh | bash -s -- --force
-```
-
-To manually install instead:
-
-```bash
-# Windsurf (reads .agents/skills/ when in repo; for global copy)
-cp -r .agents/skills/tanstack-promptable-fullstack-app-template ~/.codeium/windsurf/skills/
-
-# Cursor (copy from shared standard)
-cp -r .agents/skills/tanstack-promptable-fullstack-app-template ~/.cursor/skills/
-
-# Claude Code (copy from shared standard)
-cp -r .agents/skills/tanstack-promptable-fullstack-app-template ~/.claude/skills/
-```
-
-To regenerate after editing the canonical source:
-
-```bash
-pnpm skills:build
-```
-
-To verify the generated outputs are current:
-
-```bash
-pnpm skills:check
-pnpm test:skills
-```
-
-To verify that your editor actually loaded the skill, ask the agent a direct pattern question such as:
-
-- *"What are the rigid rules in the TanStack fullstack pattern?"*
-- *"How should this project structure repository and observability services?"*
-
-If the skill loaded correctly, the response should mention the interface-first boundaries, loaders-first data fetching, URL-as-state, and mutation invalidation conventions.
-
-Once active, ask the agent to apply the pattern:
-
-- *"Set up this project using the TanStack fullstack pattern"*
-- *"Add the repository pattern to this existing app"*
-- *"Migrate this project to use interface-first architecture"*
-
-The skill covers:
-
-- The 6 architectural layers and their boundaries
-- All 4 interface contracts (`ReadRepository`/`WritableRepository`, `AIAdapterService`, `ObservabilityService`, `AuthContext`)
-- Rigid rules (loaders-first, URL-as-state, schema-first types, invalidation middleware)
-- Implementation choices (swap any layer: database, AI, UI, observability, schema library)
-- A validation checklist to verify the pattern is correctly applied
+### Option B: AI-assisted (skill)
 
-Tool support note: the canonical metadata now tracks support targets and install mode per tool. The current target tools are Windsurf (`native`) plus Cursor and Claude Code (`copy`). Use `skills/registry.json` as the source of truth for current support status.
+See **[Use the Agent Skill](#use-the-agent-skill)** above for install commands, quick prompts, and what the skill enforces. Contributor workflow (edit YAML, regenerate): **[skills/AUTHORING.md](./skills/AUTHORING.md)**.
 
 ### Option C: Adopt Incrementally (Existing Project)
 

diff --git a/scripts/skills/buildSkills.test.ts b/scripts/skills/buildSkills.test.ts
@@ -76,7 +76,9 @@ describe('buildSkills', () => {
 		const parsedRegistry = JSON.parse(registry)
 		expect(parsedRegistry.skills[0].author.name).toBe('Carlos Martin-Sanchez')
 		expect(parsedRegistry.skills[0].supportedTools[0].id).toBe('windsurf')
-		expect(parsedRegistry.skills[0].outputsByFormat.skill).toBe('.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md')
+		expect(parsedRegistry.skills[0].outputsByFormat.skill).toBe(
+			'.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md',
+		)
 
 		const agentSkill = await readFile(
 			path.join(rootDir, '.agents', 'skills', 'tanstack-promptable-fullstack-app-template', 'SKILL.md'),

diff --git a/skills/AUTHORING.md b/skills/AUTHORING.md
@@ -0,0 +1,43 @@
+# Skills authoring (contributors)
+
+This project stores skills in a vendor-agnostic canonical format and generates platform-specific outputs.
+
+## Canonical source
+
+- Canonical schema: `skills/spec/skill.schema.json`
+- Canonical skill files: `skills/src/*.skill.yaml`
+
+Each canonical file contains:
+
+- Portable metadata (`id`, `title`, `summary`, `version`, `tags`, `triggers`)
+- Publication metadata (`author`, `license`, `homepage`, `repository`, `documentationUrl`, `status`, `supportedTools`)
+- Structured execution hints (`inputs`, `outputs`, `constraints`, `steps`, `examples`)
+- Canonical markdown body in `content`
+
+## Generated outputs
+
+Generated files are derived from canonical source and should not be edited manually.
+
+| Path | Purpose |
+| --- | --- |
+| `.agents/skills/<id>/SKILL.md` | [agentskills.io](https://agentskills.io) standard — read natively by Windsurf and any compatible tool |
+| `skills/dist/<id>.md` | Portable docs (GitHub, wikis, copy-paste) |
+| `skills/registry.json` | Machine-readable manifest for discovery |
+
+Generated outputs are committed on purpose so other projects can consume the skill without running the build pipeline first.
+
+Tools that don't yet read `.agents/skills/` (for example Cursor, Claude Code) can use the same `SKILL.md` by copying the skill folder into their tool's directory (for example `~/.cursor/skills/` or `.claude/skills/`).
+
+## Commands
+
+```bash
+pnpm skills:build   # Validate + generate all outputs
+pnpm skills:check   # Validate + fail if generated files drift
+```
+
+## Workflow
+
+1. Edit or add a canonical file under `skills/src/`.
+2. Run `pnpm skills:build`.
+3. Commit both canonical and generated outputs.
+4. CI/lint should run `pnpm skills:check` to prevent drift.
diff --git a/skills/README.md b/skills/README.md
@@ -1,43 +1,51 @@
-# Skills Authoring Guide
+# TanStack Promptable Fullstack skill
 
-This project stores skills in a vendor-agnostic canonical format and generates platform-specific outputs.
+This repo ships an **[Agent Skill](https://agentskills.io)** that teaches coding agents the **architecture contract** for this template: interface-first services, three schema layers with explicit parsing at boundaries, loader-first routes, URL-as-state, AI tool coverage, and strong TypeScript inside the typed flow. Operational detail (UI kit, auth snippets, chat wiring, tests) stays in the repo's **[AGENTS.md](../AGENTS.md)** — the skill focuses on **what to enforce**, not every implementation recipe.
 
-## Canonical Source
+**Use it when** you scaffold or extend a TanStack Start app from this pattern, migrate an existing app, or need agents to follow current TanStack docs instead of guessing.
 
-- Canonical schema: `skills/spec/skill.schema.json`
-- Canonical skill files: `skills/src/*.skill.yaml`
+## Super quick install
 
-Each canonical file contains:
+From any machine with Node/npm:
 
-- Portable metadata (`id`, `title`, `summary`, `version`, `tags`, `triggers`)
-- Publication metadata (`author`, `license`, `homepage`, `repository`, `documentationUrl`, `status`, `supportedTools`)
-- Structured execution hints (`inputs`, `outputs`, `constraints`, `steps`, `examples`)
-- Canonical markdown body in `content`
+```bash
+npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
+```
 
-## Generated Outputs
+Optional: install **globally** so the skill is available in every project:
 
-Generated files are derived from canonical source and should not be edited manually.
+```bash
+npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template -g
+```
 
-| Path | Purpose |
-| --- | --- |
-| `.agents/skills/<id>/SKILL.md` | [agentskills.io](https://agentskills.io) standard — read natively by Windsurf and any compatible tool |
-| `skills/dist/<id>.md` | Portable docs (GitHub, wikis, copy-paste) |
-| `skills/registry.json` | Machine-readable manifest for discovery |
+List what this repo publishes, then confirm:
 
-Generated outputs are committed on purpose so other projects can consume the skill without running the build pipeline first.
+```bash
+npx skills add carlosvin/tanstack-fullstack-ai-template --list
+npx skills list
+```
 
-Tools that don't yet read `.agents/skills/` (e.g. Cursor, Claude Code) can use the same `SKILL.md` by copying the skill folder into their tool's directory (e.g. `~/.cursor/skills/` or `.claude/skills/`).
+## Skill files in this repository
 
-## Commands
+After clone, the generated skill lives here (committed on purpose):
 
-```bash
-pnpm skills:build   # Validate + generate all outputs
-pnpm skills:check   # Validate + fail if generated files drift
-```
+- `.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md` — standard skill document agents load
+- `skills/dist/tanstack-promptable-fullstack-app-template.md` — portable copy for docs or paste
+- `skills/registry.json` — machine-readable manifest
+
+## Other install options
+
+- **One-shot installer** (Cursor, Windsurf, Claude Code global dirs): see the root [README.md](../README.md#use-the-agent-skill).
+- **Manual copy**: copy the folder `.agents/skills/tanstack-promptable-fullstack-app-template/` into your tool's skills directory (for example `~/.cursor/skills/`).
+
+## Try it
+
+Paste one of these into your agent after install:
+
+- "Follow this repo's TanStack fullstack skill: what are the core contract items I must not violate?"
+- "Add a new domain entity using the template's schema layers, repository, server functions, routes, and AI tools."
+- "Review my nested routes: shared `beforeLoad` / loaders should live on the parent layout — what should move?"
 
-## Workflow
+## Contributors
 
-1. Edit or add a canonical file under `skills/src/`.
-2. Run `pnpm skills:build`.
-3. Commit both canonical and generated outputs.
-4. CI/lint should run `pnpm skills:check` to prevent drift.
+To edit or regenerate the skill from YAML, see **[AUTHORING.md](./AUTHORING.md)**.