nuxt-skill-hub 0.0.1-beta.1

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions, type SkillHubContribution, type SkillHubContributionContext, type SkillHubTarget } from './module.mjs'

package/nuxt-best-practices/index.template.md

@@ -0,0 +1,74 @@
+# Nuxt Best Practices
+
+These notes improve execution quality for AI agents in this repository.
+They complement Nuxt docs; they do not replace official documentation.
+
+## Source baseline
+- Nuxt docs: `docs/3.guide/2.best-practices/*`, `docs/1.getting-started/10.data-fetching.md`, `docs/3.guide/4.modules/6.best-practices.md`
+- Nuxt source: `packages/nuxt/src/app/composables/{asyncData,fetch,once}.ts`, `packages/nuxt/src/app/nuxt.ts`
+
+## How to use this file
+1. Start with the smallest high-priority pack that matches the actual surface or symptom.
+2. Apply rule IDs directly; do not paraphrase away Nuxt-specific caveats.
+3. Treat the first six packs as disambiguation overlays before broader infra packs.
+4. Keep scope narrow: open only the sections needed for the current change.
+5. Nuxt guidance is default; module guidance overrides it only inside explicit module scope.
+
+## Rule Packs by Priority
+
+| Priority | Pack | Focus | Rule ID Prefix |
+| --- | --- | --- | --- |
+| 1 | Abstraction Disambiguation | Choose framework-owned primitives before generic Vue or raw HTML | `disambiguation-` |
+| 2 | Page Meta, Head, and Layout | Separate page behavior, document metadata, and layout structure | `page-` |
+| 3 | Error Surfaces and Recovery | Cover both global and local error surfaces with the right recovery utilities | `error-` |
+| 4 | Verification and Finish | Re-check paired surfaces and verify framework behavior before concluding | `verify-` |
+| 5 | Data Fetching and SSR | Deduplication, payload correctness, and request safety | `data-` |
+| 6 | Hydration and SSR Consistency | SSR and CSR determinism and client-only boundaries | `hydration-` |
+| 7 | Architecture Boundaries | Server-only secrets and request-safe state | `arch-` |
+| 8 | Server Routes and Runtime Config | Handler contracts and config exposure | `server-` |
+| 9 | Nitro and h3 Server Patterns | Request contracts, caching behavior, and edge-safe server work | `nitro-` |
+| 10 | Plugins and Runtime Boot | Plugin startup cost, ordering, and isolation | `plugin-` |
+| 11 | Performance and Rendering | Rendering strategy, links, payload, and asset cost | `perf-` |
+| 12 | Module Authoring Conventions | Nuxt Kit module safety and ecosystem fit | `module-` |
+| 13 | Migrations and Compatibility | Safe incremental upgrades | `migration-` |
+
+## Rule Packs
+
+<!-- automd:file src="./rules/abstraction-disambiguation.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/page-meta-head-layout.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/error-surfaces-recovery.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/verification-finish.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/data-fetching-ssr.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/hydration-consistency.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/architecture-boundaries.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/server-routes-runtime-config.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/nitro-h3-patterns.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/plugins.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/performance-rendering.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/module-authoring.md" -->
+<!-- /automd -->
+
+<!-- automd:file src="./rules/migrations.md" -->
+<!-- /automd -->

package/nuxt-best-practices/rules/abstraction-disambiguation.md

@@ -0,0 +1,58 @@
+## Abstraction Disambiguation
+
+### Rule ID: `disambiguation-framework-primitives-first`
+### Rule: Prefer framework-owned primitives before generic Vue or raw HTML
+### When to apply
+Any fix where generic Vue code, hand-rolled HTML, or custom event wiring looks plausible.
+
+### Wrong pattern
+Solving a Nuxt problem with ad hoc watchers, raw fetches, or custom markup when Nuxt, Nuxt Content, or Nuxt UI already owns the surface.
+
+### Recommended pattern
+Identify the framework-owned abstraction first, then use generic Vue primitives only when the framework does not provide a suitable surface.
+
+### Nuxt-specific caveat
+Visually correct custom code can still be the wrong answer if it bypasses a Nuxt-native abstraction that hidden evals or framework conventions expect.
+
+### Execution checklist
+- [ ] Inputs to inspect: the exact surface being edited and whether Nuxt, Nuxt Content, or Nuxt UI already provides a first-class primitive.
+- [ ] Minimal verification: the final solution uses the framework abstraction when one exists.
+- [ ] Stop condition: the task explicitly requires behavior outside the owned abstraction.
+
+### Rule ID: `disambiguation-nearby-concepts-before-editing`
+### Rule: Resolve nearby concept pairs before changing code
+### When to apply
+Tasks that could map to two similar Nuxt concepts.
+
+### Wrong pattern
+Editing the first plausible API without deciding the actual concept pair first.
+
+### Recommended pattern
+Explicitly decide the concept pair before editing, such as `definePageMeta` vs `useHead`, data collection vs page collection, `NuxtLink` vs raw `<a>`, or `useCookie` vs `document.cookie`.
+
+### Nuxt-specific caveat
+Many strong agents fail Nuxt tasks by choosing the wrong nearby abstraction rather than by writing broken code.
+
+### Execution checklist
+- [ ] Inputs to inspect: prompt symptoms, file location, and framework-owned surface.
+- [ ] Minimal verification: the chosen abstraction matches the actual responsibility of the change.
+- [ ] Stop condition: both concepts are intentionally involved and clearly separated.
+
+### Rule ID: `disambiguation-do-not-stop-at-visually-correct`
+### Rule: Do not accept a visually correct result as sufficient
+### When to apply
+UI, docs, or content tasks where a hand-built implementation can look correct.
+
+### Wrong pattern
+Declaring success because the output looks fine while bypassing Nuxt UI, Content, or SSR-aware primitives.
+
+### Recommended pattern
+Check whether the implementation is framework-correct, not only visually correct.
+
+### Nuxt-specific caveat
+Nuxt evals often reject custom HTML solutions even when they render acceptably, because the intended abstraction was a framework primitive.
+
+### Execution checklist
+- [ ] Inputs to inspect: component usage, slot API, and data source wiring.
+- [ ] Minimal verification: the implementation matches the expected framework primitive and API shape.
+- [ ] Stop condition: the prompt explicitly asks for custom markup or behavior the primitive cannot support.

package/nuxt-best-practices/rules/architecture-boundaries.md

@@ -0,0 +1,58 @@
+## Architecture Boundaries
+
+### Rule ID: `arch-secrets-server-only`
+### Rule: Keep secrets and request checks server-side
+### When to apply
+Implementing auth, secret-bearing API calls, or per-request business logic.
+
+### Wrong pattern
+Placing secret usage in shared composables imported by client code.
+
+### Recommended pattern
+Move sensitive logic to `server/api/*` handlers, server utilities, or server plugins.
+
+### Nuxt-specific caveat
+Anything in `runtimeConfig.public` is client-visible.
+
+### Execution checklist
+- [ ] Inputs to inspect: changed files in `server/`, `composables/`, and `runtimeConfig` usage.
+- [ ] Minimal verification: no secret values or token checks in client bundles.
+- [ ] Stop condition: a required server-only check cannot be moved out of client code.
+
+### Rule ID: `arch-request-safe-state`
+### Rule: Use request-safe state boundaries
+### When to apply
+Adding reusable cross-page logic with state.
+
+### Wrong pattern
+Using mutable module-level singletons for request-scoped state.
+
+### Recommended pattern
+Use `useState`/composables for shared state and pass request context explicitly where needed.
+
+### Nuxt-specific caveat
+SSR runs per request; module globals can leak state across requests.
+
+### Execution checklist
+- [ ] Inputs to inspect: shared state in module scope and composable state factories.
+- [ ] Minimal verification: request-specific data is not shared globally.
+- [ ] Stop condition: solution depends on mutable globals without explicit isolation.
+
+### Rule ID: `arch-server-entrypoint-for-sensitive-io`
+### Rule: Keep sensitive I/O behind server entrypoints
+### When to apply
+Calling third-party APIs, databases, or internal services with credentials.
+
+### Wrong pattern
+Making direct browser fetches to privileged upstream services with forwarded sensitive headers.
+
+### Recommended pattern
+Expose a constrained `server/api/*` boundary and call it from client/UI code.
+
+### Nuxt-specific caveat
+`useFetch('/api/*')` on server uses request-aware fetch behavior; external APIs require explicit header allowlisting.
+
+### Execution checklist
+- [ ] Inputs to inspect: upstream fetch targets, header forwarding, and token placement.
+- [ ] Minimal verification: browser code only talks to safe internal endpoints.
+- [ ] Stop condition: architecture requires direct client access to privileged credentials.

package/nuxt-best-practices/rules/content-modeling-navigation.md

@@ -0,0 +1,58 @@
+## Content Modeling and Navigation
+
+### Rule ID: `content-data-collections-for-structured-records`
+### Rule: Use data collections for structured JSON or YAML records
+### When to apply
+Working with structured records that are not authored as full content pages.
+
+### Wrong pattern
+Treating JSON or YAML records as page content just because they live in the content tree.
+
+### Recommended pattern
+Model structured records as Nuxt Content data collections when they represent data rather than pages.
+
+### Nuxt-specific caveat
+The right collection type changes the query surface and avoids page-oriented assumptions in navigation and rendering.
+
+### Execution checklist
+- [ ] Inputs to inspect: file formats, collection config, and whether entries represent records or renderable pages.
+- [ ] Minimal verification: collection type matches the underlying content model.
+- [ ] Stop condition: the data is intentionally authored and rendered as page content.
+
+### Rule ID: `content-navigation-from-collections`
+### Rule: Use collection navigation primitives for generated docs navigation
+### When to apply
+Building sidebars, section navigation, or docs trees from content.
+
+### Wrong pattern
+Manually assembling navigation trees when the collection model can generate them.
+
+### Recommended pattern
+Use collection-navigation helpers such as `queryCollectionNavigation` before writing custom navigation assembly.
+
+### Nuxt-specific caveat
+Manual sidebar assembly is a repeated failure mode when Nuxt Content already has a first-class navigation primitive.
+
+### Execution checklist
+- [ ] Inputs to inspect: navigation source, collection schema, and current sidebar code.
+- [ ] Minimal verification: the navigation derives from collection primitives instead of custom tree-building.
+- [ ] Stop condition: the navigation behavior cannot be represented with collection helpers.
+
+### Rule ID: `content-model-before-rendering`
+### Rule: Finalize content modeling before choosing rendering primitives
+### When to apply
+Tasks that mix collection setup, querying, and rendering.
+
+### Wrong pattern
+Choosing the rendering component or sidebar implementation before deciding the collection model.
+
+### Recommended pattern
+Lock the collection type and query surface first, then render from that model.
+
+### Nuxt-specific caveat
+Many content bugs come from modeling mistakes that are then hidden under custom rendering code.
+
+### Execution checklist
+- [ ] Inputs to inspect: collection config, query usage, and rendering components.
+- [ ] Minimal verification: the rendering code follows the collection model rather than compensating for a wrong model.
+- [ ] Stop condition: the collection model is already fixed and correct.

package/nuxt-best-practices/rules/data-fetching-ssr.md

@@ -0,0 +1,115 @@
+## Data Fetching and SSR
+
+### Rule ID: `data-usefetch-or-asyncdata-for-initial`
+### Rule: Use `useFetch`/`useAsyncData` for initial render data
+### When to apply
+Building SSR pages or route-level data loading.
+
+### Wrong pattern
+Using `$fetch` directly in setup for initial render data, causing SSR+CSR duplicate requests.
+
+### Recommended pattern
+Use `useFetch` for HTTP-first fetching and `useAsyncData` for custom async logic or multi-request composition.
+
+### Nuxt-specific caveat
+`$fetch` is ideal for event-driven interactions; initial view data should normally be payload-backed via `useFetch`/`useAsyncData`.
+
+### Execution checklist
+- [ ] Inputs to inspect: setup-time `$fetch` usage and async data composable usage.
+- [ ] Minimal verification: initial render data is transferred via Nuxt payload, without extra hydration fetch.
+- [ ] Stop condition: call is explicitly client-only and non-SEO-critical.
+
+### Rule ID: `data-stable-keys-and-option-consistency`
+### Rule: Keep async-data keys explicit and option-consistent
+### When to apply
+Sharing `useAsyncData` or `useFetch` state across components/composables.
+
+### Wrong pattern
+Relying on autogenerated keys in wrappers or using same key with conflicting `transform`/`pick`/`deep` behavior.
+
+### Recommended pattern
+Use explicit stable keys and keep key-sharing options consistent.
+
+### Nuxt-specific caveat
+Nuxt warns on incompatible shared-key options and can produce confusing state reuse if keys are unstable.
+
+### Execution checklist
+- [ ] Inputs to inspect: key construction and repeated composable calls.
+- [ ] Minimal verification: no key collisions; shared-key options match.
+- [ ] Stop condition: scope truly requires isolated state per call site.
+
+### Rule ID: `data-side-effects-via-callonce`
+### Rule: Keep `useAsyncData` handlers side-effect free
+### When to apply
+Data loaders that also trigger analytics, store mutations, or one-time bootstrapping.
+
+### Wrong pattern
+Running side effects inside the `useAsyncData` handler.
+
+### Recommended pattern
+Return data only from handler; move side effects to `callOnce` or explicit event handlers.
+
+### Nuxt-specific caveat
+`useAsyncData` re-execution paths (`watch`, refresh, navigation) can replay embedded side effects.
+
+### Execution checklist
+- [ ] Inputs to inspect: handler body for side effects, store writes, and non-idempotent calls.
+- [ ] Minimal verification: handler remains pure relative to its inputs.
+- [ ] Stop condition: third-party API requires coupled side effects and cannot be decoupled.
+
+### Rule ID: `data-reactive-url-not-watch-only`
+### Rule: Use reactive URL/options, not `watch` alone, for parameterized fetches
+### When to apply
+Fetching data from reactive route params, filters, or query inputs.
+
+### Wrong pattern
+Passing a static URL string and expecting `watch: [id]` to change endpoint automatically.
+
+### Recommended pattern
+Use computed URL or reactive fetch options (`query`, `params`) and opt out with `watch: false` only intentionally.
+
+### Nuxt-specific caveat
+Reactive fetch options are watched by default; computed URL updates are first-class.
+
+### Execution checklist
+- [ ] Inputs to inspect: URL construction, watch config, and query/params refs.
+- [ ] Minimal verification: endpoint and data refresh when reactive dependencies change.
+- [ ] Stop condition: endpoint must remain static while auxiliary state changes.
+
+### Rule ID: `data-minimize-payload-shape`
+### Rule: Minimize payload transfer for SSR data
+### When to apply
+Fetching large objects/arrays where only a subset is needed for initial render.
+
+### Wrong pattern
+Transferring full backend payload to client when template uses a few fields.
+
+### Recommended pattern
+Use `pick`/`transform` for payload shaping and split non-critical data into lazy client-only fetches when appropriate.
+
+### Nuxt-specific caveat
+`pick`/`transform` reduce payload transfer size, not upstream API response size.
+
+### Execution checklist
+- [ ] Inputs to inspect: fetched object shape vs template usage.
+- [ ] Minimal verification: payload contains only needed fields for first paint.
+- [ ] Stop condition: downstream consumers rely on full object in the same render boundary.
+
+### Rule ID: `data-serialization-boundary-awareness`
+### Rule: Respect serialization differences between payload and API routes
+### When to apply
+Returning non-primitive values (Date, Map, Set, custom classes) through SSR data and server API routes.
+
+### Wrong pattern
+Assuming all Nuxt data transfer paths serialize complex types identically.
+
+### Recommended pattern
+Treat `useAsyncData` payload serialization and server-route JSON serialization as distinct boundaries; normalize API outputs (or custom `toJSON`) when needed.
+
+### Nuxt-specific caveat
+Nuxt payload transfer uses `devalue`, while server route responses are serialized via JSON behavior, which has stricter type limits.
+
+### Execution checklist
+- [ ] Inputs to inspect: returned types across `useAsyncData` handlers and `server/api/*` responses.
+- [ ] Minimal verification: client receives expected shape/types on both transport paths.
+- [ ] Stop condition: upstream contract mandates non-serializable runtime-only values.

package/nuxt-best-practices/rules/error-surfaces-recovery.md

@@ -0,0 +1,39 @@
+## Error Surfaces and Recovery
+
+### Rule ID: `error-check-global-and-local-surfaces`
+### Rule: Check both global and local error surfaces
+### When to apply
+Handling runtime errors, route failures, or fallback UI in Nuxt.
+
+### Wrong pattern
+Fixing only `app/error.vue` or only a local `NuxtErrorBoundary` when the flow requires both.
+
+### Recommended pattern
+Identify whether the issue needs a global error surface, a local boundary, or both, then implement both surfaces explicitly when required.
+
+### Nuxt-specific caveat
+Nuxt error handling is often multi-surface; solving only half the pattern is a recurring failure mode in strong models.
+
+### Execution checklist
+- [ ] Inputs to inspect: where the error originates and whether recovery is route-wide or local to a subtree.
+- [ ] Minimal verification: the intended error surface actually receives and renders the failure.
+- [ ] Stop condition: the issue is intentionally scoped to one surface only.
+
+### Rule ID: `error-use-nuxt-recovery-utilities`
+### Rule: Use Nuxt recovery helpers instead of ad hoc reset logic
+### When to apply
+Recovering from an error state or clearing error UI.
+
+### Wrong pattern
+Resetting local refs or forcing navigation without using Nuxt recovery utilities.
+
+### Recommended pattern
+Use Nuxt error helpers such as `clearError`, `showError`, and framework-supported retry paths.
+
+### Nuxt-specific caveat
+Custom reset logic can leave the app in an inconsistent state if it bypasses Nuxt's error lifecycle.
+
+### Execution checklist
+- [ ] Inputs to inspect: current error state flow and whether Nuxt helpers are already present.
+- [ ] Minimal verification: recovery clears the error surface and restores intended navigation or rendering behavior.
+- [ ] Stop condition: the task explicitly requires a non-standard recovery path.

package/nuxt-best-practices/rules/hydration-consistency.md

@@ -0,0 +1,58 @@
+## Hydration and SSR Consistency
+
+### Rule ID: `hydration-no-browser-apis-in-ssr-path`
+### Rule: Keep browser-only APIs out of SSR execution paths
+### When to apply
+Reading storage, window size, document state, or navigator data in setup/render paths.
+
+### Wrong pattern
+Accessing `window`, `document`, or `localStorage` during server render.
+
+### Recommended pattern
+Use SSR-safe primitives (`useCookie`, server data, request headers) or gate browser-only logic in `ClientOnly`/`onMounted`.
+
+### Nuxt-specific caveat
+Hydration mismatch can force full subtree re-render and break event binding assumptions.
+
+### Execution checklist
+- [ ] Inputs to inspect: setup code for browser globals and conditional rendering paths.
+- [ ] Minimal verification: first SSR HTML and first client render produce matching structure/content.
+- [ ] Stop condition: third-party dependency cannot run without browser APIs before mount.
+
+### Rule ID: `hydration-deterministic-first-render`
+### Rule: Make first render deterministic across server and client
+### When to apply
+Rendering dynamic values such as timestamps, randomness, or locale-sensitive formatting.
+
+### Wrong pattern
+Using `Math.random()`, `new Date()`, or environment-specific formatting directly in template/setup for first paint.
+
+### Recommended pattern
+Seed shared state with `useState`, use `NuxtTime`, or defer non-deterministic values until after mount.
+
+### Nuxt-specific caveat
+Time/randomness differences between SSR and CSR are a common hydration mismatch cause.
+
+### Execution checklist
+- [ ] Inputs to inspect: first-render values derived from time/random/browser environment.
+- [ ] Minimal verification: page hydrates without mismatch warnings.
+- [ ] Stop condition: feature explicitly requires client-personalized first paint with acceptable fallback.
+
+### Rule ID: `hydration-client-only-libraries-after-mount`
+### Rule: Initialize DOM-mutating third-party libraries after hydration
+### When to apply
+Integrating analytics, tag managers, embeds, or widgets that touch DOM directly.
+
+### Wrong pattern
+Running library initialization in universal setup path.
+
+### Recommended pattern
+Load/init libraries in `onMounted` or dedicated client plugins and provide SSR-safe fallback markup.
+
+### Nuxt-specific caveat
+`import.meta.client` guards code path, but DOM writes before hydration completion can still create mismatch risk.
+
+### Execution checklist
+- [ ] Inputs to inspect: library init location and DOM mutation timing.
+- [ ] Minimal verification: no hydration warnings and no visible layout flash from re-render.
+- [ ] Stop condition: library requires synchronous pre-hydration bootstrap with no fallback option.

package/nuxt-best-practices/rules/migrations.md

@@ -0,0 +1,58 @@
+## Migrations and Compatibility
+
+### Rule ID: `migration-reversible-slices`
+### Rule: Perform migrations in reversible slices
+### When to apply
+Nuxt, Nitro, h3, or module major/minor upgrades.
+
+### Wrong pattern
+Large unscoped migration commits with no rollback checkpoints.
+
+### Recommended pattern
+Split migration into small steps with explicit validation after each step.
+
+### Nuxt-specific caveat
+Validate both SSR render path and client hydration path.
+
+### Execution checklist
+- [ ] Inputs to inspect: changed APIs, config keys, and migration commit boundaries.
+- [ ] Minimal verification: each slice can be reverted independently.
+- [ ] Stop condition: migration cannot be tested incrementally.
+
+### Rule ID: `migration-upgrade-touched-deprecations`
+### Rule: Remove deprecated APIs in touched areas
+### When to apply
+Editing files already using deprecated Nuxt/Nitro/h3 patterns.
+
+### Wrong pattern
+Keeping mixed old/new patterns in the same touched code path.
+
+### Recommended pattern
+Upgrade touched deprecated usage while context is active.
+
+### Nuxt-specific caveat
+Prefer official migration mappings over ad-hoc replacements.
+
+### Execution checklist
+- [ ] Inputs to inspect: touched deprecated symbols and replacement mapping.
+- [ ] Minimal verification: no deprecated usage remains in modified files.
+- [ ] Stop condition: required replacement API is not yet stable in target version.
+
+### Rule ID: `migration-verify-ssr-and-hydration`
+### Rule: Verify both server render and hydration behavior after each slice
+### When to apply
+Any migration touching rendering, data fetching, plugins, or runtime config.
+
+### Wrong pattern
+Validating only build success without browser hydration and runtime checks.
+
+### Recommended pattern
+Validate SSR output, hydration warnings, critical data paths, and route navigation on each migration slice.
+
+### Nuxt-specific caveat
+Nuxt migrations can pass type checks while still regressing payload transfer or hydration behavior.
+
+### Execution checklist
+- [ ] Inputs to inspect: browser console hydration warnings, route transitions, and async-data behavior.
+- [ ] Minimal verification: no hydration mismatch warnings and no duplicate initial fetch regressions.
+- [ ] Stop condition: environment lacks a runnable app context for runtime verification.

package/nuxt-best-practices/rules/module-authoring.md

@@ -0,0 +1,77 @@
+## Module Authoring Conventions
+
+### Rule ID: `module-keep-setup-fast-and-defer-heavy-work`
+### Rule: Keep module setup fast and defer heavy work
+### When to apply
+Authoring or updating a Nuxt module with runtime behavior.
+
+### Wrong pattern
+Performing expensive async work directly in module `setup`.
+
+### Recommended pattern
+Keep `setup` lightweight and defer heavier tasks to lifecycle hooks or deferred build/runtime hooks.
+
+### Nuxt-specific caveat
+Nuxt warns when module setup takes too long; slow setup delays dev server and build startup.
+
+### Execution checklist
+- [ ] Inputs to inspect: `defineNuxtModule` setup body and async operations.
+- [ ] Minimal verification: startup-critical path avoids long blocking work.
+- [ ] Stop condition: required initialization must complete before app/module lifecycle proceeds.
+
+### Rule ID: `module-prefix-public-exports`
+### Rule: Prefix public exports and routes
+### When to apply
+Adding module composables, components, plugins, or server routes.
+
+### Wrong pattern
+Publishing generic names like `useData`, `<Button>`, or `/api/auth` from a module.
+
+### Recommended pattern
+Prefix public surface with module identity (`useFooData`, `<FooButton>`, `/api/_foo/*`).
+
+### Nuxt-specific caveat
+Unprefixed module routes/components collide easily with app code and other modules.
+
+### Execution checklist
+- [ ] Inputs to inspect: names of components/composables/runtime API routes.
+- [ ] Minimal verification: exported names are collision-resistant and module-scoped.
+- [ ] Stop condition: backward compatibility policy requires legacy unprefixed aliases.
+
+### Rule ID: `module-public-kit-apis-only`
+### Rule: Prefer documented Nuxt Kit APIs over internals
+### When to apply
+Implementing Nuxt module behavior and code generation logic.
+
+### Wrong pattern
+Relying on private Nuxt internals or undocumented hooks.
+
+### Recommended pattern
+Use stable `@nuxt/kit` APIs, documented hooks, and declared compatibility constraints.
+
+### Nuxt-specific caveat
+Private internals can break across minor/patch updates even when compatibility appears broad.
+
+### Execution checklist
+- [ ] Inputs to inspect: imported kit functions/hooks and internal path imports.
+- [ ] Minimal verification: implementation uses public Nuxt APIs with explicit compatibility.
+- [ ] Stop condition: required behavior has no documented public API yet.
+
+### Rule ID: `module-skill-scope-only`
+### Rule: Scope module skills to module APIs only
+### When to apply
+Publishing `agents.skills` with a module.
+
+### Wrong pattern
+Embedding global Nuxt framework guidance inside module-specific skill docs.
+
+### Recommended pattern
+Document only module APIs, integration points, and module-specific caveats.
+
+### Nuxt-specific caveat
+Module guidance can override Nuxt guidance only inside that module's explicit scope.
+
+### Execution checklist
+- [ ] Inputs to inspect: skill frontmatter, rule language, examples.
+- [ ] Minimal verification: instructions are module-scoped and version-aligned.
+- [ ] Stop condition: module skill introduces global rules unrelated to module behavior.