nuxt-skill-hub 0.0.3 → 0.0.5

package/dist/module.mjs

@@ -1,98 +1,28 @@
-import { promises, existsSync, lstatSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, basename, resolve, dirname, relative, isAbsolute } from 'pathe';
 import { useLogger, defineNuxtModule } from '@nuxt/kit';
 import { isCI, isTest } from 'std-env';
-import { createConsola } from 'consola';
-import { colorize } from 'consola/utils';
-import { detectInstalledAgents, expandPath, detectCurrentAgent, getAgentIds, getAgentConfig } from 'unagent/env';
+import { promises, existsSync, lstatSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, basename, resolve, dirname, relative, isAbsolute } from 'pathe';
+import { fileURLToPath } from 'mlly';
 import { homedir } from 'node:os';
 import matter from 'gray-matter';
-import { readPackageJSON, resolvePackageJSON } from 'pkg-types';
+import { readPackageJSON, findWorkspaceDir, resolvePackageJSON, resolveLockfile } from 'pkg-types';
 import { transform } from 'automd';
-import { fileURLToPath } from 'mlly';
 import { downloadTemplate } from 'giget';
+import { detectInstalledAgents, expandPath, detectCurrentAgent, getAgentIds, getAgentConfig } from 'unagent/env';
 import { ofetch } from 'ofetch';
+import { createHash } from 'node:crypto';
+import { hash } from 'ohash';
+import { glob } from 'tinyglobby';
+import { createConsola } from 'consola';
+import { colorize } from 'consola/utils';
 
-const version = "0.0.3";
+const version = "0.0.5";
 const packageJson = {
 	version: version};
 
 const metadata = packageJson;
 const PACKAGE_VERSION = metadata.version;
 
-function resolveSkillsDir(target, config) {
-  if (config?.skillsDir) {
-    return config.skillsDir;
-  }
-  if (target === "codex") {
-    return "skills";
-  }
-  return void 0;
-}
-function normalizeTarget(target) {
-  return target.trim();
-}
-function getRawTargetConfig(target) {
-  return getAgentConfig(target);
-}
-function getSupportedTargets() {
-  return getAgentIds().filter((target) => {
-    const config = getRawTargetConfig(target);
-    return Boolean(resolveSkillsDir(target, config));
-  }).sort((a, b) => a.localeCompare(b));
-}
-function resolveAgentTargetConfig(target) {
-  const normalized = normalizeTarget(target);
-  if (!normalized) {
-    return void 0;
-  }
-  const config = getRawTargetConfig(normalized);
-  const skillsDir = resolveSkillsDir(normalized, config);
-  if (!config || !skillsDir) {
-    return void 0;
-  }
-  return {
-    target: normalized,
-    configDir: expandPath(config.configDir),
-    skillsDir
-  };
-}
-function validateTargets(targets) {
-  const uniqueTargets = Array.from(new Set(targets.map(normalizeTarget).filter(Boolean)));
-  const valid = [];
-  const invalid = [];
-  for (const target of uniqueTargets) {
-    const config = getRawTargetConfig(target);
-    if (!config) {
-      invalid.push({
-        target,
-        reason: "unknown-target"
-      });
-      continue;
-    }
-    if (!resolveSkillsDir(target, config)) {
-      invalid.push({
-        target,
-        reason: "missing-skills-dir"
-      });
-      continue;
-    }
-    valid.push(target);
-  }
-  return { valid, invalid };
-}
-function detectCurrentTarget() {
-  const current = detectCurrentAgent();
-  if (!current) return void 0;
-  const skillsDir = resolveSkillsDir(current.id, current.config);
-  return skillsDir ? current.id : void 0;
-}
-function detectInstalledTargets() {
-  return Array.from(new Set(
-    detectInstalledAgents().filter((agent) => agent.detected === "config" && resolveSkillsDir(agent.id, agent.config)).map((agent) => agent.id)
-  )).sort((a, b) => a.localeCompare(b));
-}
-
 const DEFAULT_NUXT_CONTENT_METADATA = {
   id: "nuxt-best-practices",
   version: PACKAGE_VERSION,
@@ -207,7 +137,6 @@ const DEFAULT_NUXT_CONTENT_METADATA = {
     }
   ]
 };
-const EMPTY_MODULE_GUIDANCE_MARKDOWN = "_No module skills discovered. Use Nuxt guidance plus official module docs when module-specific guidance is missing._";
 function yamlString(value) {
   return JSON.stringify(value);
 }
@@ -315,107 +244,85 @@ ${lines.join("\n")}
 function findPack(metadata, id) {
   return metadata.packs.find((pack) => pack.id === id) || metadata.packs[0];
 }
-function createPackSummary(metadata, packIds) {
-  return packIds.map((packId) => `\`${findPack(metadata, packId).title}\``).join(", ");
-}
-function getSkillRenderProfile(includeModuleAuthoring = false) {
-  if (includeModuleAuthoring) {
-    return {
-      includeModuleAuthoring,
-      packSummaryIds: [
-        "module-authoring",
-        "plugins",
-        "architecture-boundaries",
-        "nitro-h3-patterns",
-        "migrations"
-      ]
-    };
-  }
-  return {
-    includeModuleAuthoring: false,
-    packSummaryIds: [
-      "abstraction-disambiguation",
-      "page-meta-head-layout",
-      "error-surfaces-recovery",
-      "verification-finish",
-      "data-fetching-ssr"
-    ]
-  };
-}
 function packLink(metadata, id) {
   const pack = findPack(metadata, id);
   return `[${pack.title}](./references/nuxt/${pack.relativePath})`;
 }
 function createRoutingTable(metadata, includeModuleAuthoring = false) {
   const rows = [
-    ...includeModuleAuthoring ? [{
-      symptom: "Writing, refactoring, or publishing a Nuxt module",
-      packId: "module-authoring",
-      why: "Start with Nuxt Kit-safe authoring patterns, lifecycle hooks, prefixed public APIs, and skill scope boundaries."
-    }] : [],
-    {
-      symptom: "SSR, initial page load, route params, or hydration-sensitive data",
-      packId: "data-fetching-ssr",
-      why: "Prefer `useFetch` or `useAsyncData` over setup-time `$fetch` or `onMounted` fetches."
-    },
-    {
-      symptom: "Page options, route middleware, layout selection, title, meta tags, or OG data",
-      packId: "page-meta-head-layout",
-      why: "Separate page behavior from document metadata and layout structure before editing."
-    },
-    {
-      symptom: "A generic Vue fix or raw HTML implementation looks tempting",
-      packId: "abstraction-disambiguation",
-      why: "Check whether Nuxt, Nuxt Content, or Nuxt UI already owns the abstraction."
-    },
-    {
-      symptom: "The remaining work is mostly `.vue` components, composables, reactivity, or SFC structure",
-      link: "[Vue Best Practices](./references/vue/SKILL.md)",
-      why: "Switch to Vue-specific guidance after the Nuxt ownership and routing decisions are already settled."
-    },
-    {
-      symptom: "Global errors, local fallback UI, `clearError`, `showError`, or recovery flows",
-      packId: "error-surfaces-recovery",
-      why: "Nuxt error handling often needs both global and local surfaces to be correct."
-    },
-    {
-      symptom: "Secrets, runtime config, privileged API calls, or server/client boundary confusion",
-      packId: "architecture-boundaries",
-      why: "Move sensitive logic server-side first, then pair with config and route rules as needed."
-    },
-    {
-      symptom: "Before finishing a fix that spans multiple files or surfaces",
-      packId: "verification-finish",
-      why: "Re-check paired surfaces and verify framework behavior, not only the visible output."
-    }
+    ...includeModuleAuthoring ? [[
+      "Writing or refactoring a Nuxt module (`defineNuxtModule`, hooks, public APIs)",
+      packLink(metadata, "module-authoring")
+    ]] : [],
+    [
+      "SSR, initial page load, route params, or data fetched for first render",
+      packLink(metadata, "data-fetching-ssr")
+    ],
+    [
+      "Hydration warnings, `ClientOnly`, browser-only APIs, time/randomness, or SSR/CSR mismatch",
+      packLink(metadata, "hydration-consistency")
+    ],
+    [
+      "Page options, middleware, layout selection, title, meta tags, canonical URLs, or OG data",
+      packLink(metadata, "page-meta-head-layout")
+    ],
+    [
+      "`nuxt.config.*`, `runtimeConfig`, env wiring, or public/private config exposure",
+      packLink(metadata, "server-routes-runtime-config")
+    ],
+    [
+      "`server/api/**`, `server/routes/**`, `defineEventHandler`, route rules, caching, or Nitro plugins",
+      packLink(metadata, "nitro-h3-patterns")
+    ],
+    [
+      "Plugins, injections, app boot logic, or global runtime initialization",
+      packLink(metadata, "plugins")
+    ],
+    [
+      "Secrets, privileged API calls, request isolation, or server/client boundary confusion",
+      packLink(metadata, "architecture-boundaries")
+    ],
+    [
+      "Performance regressions, rendering strategy, lazy loading, or payload/bundle cost",
+      packLink(metadata, "performance-rendering")
+    ],
+    [
+      "Upgrades, deprecations, compatibility fixes, or version-boundary work",
+      packLink(metadata, "migrations")
+    ],
+    [
+      "A generic Vue or raw HTML fix looks plausible",
+      packLink(metadata, "abstraction-disambiguation")
+    ],
+    [
+      "The remaining work is mostly components, composables, reactivity, props/emits, or SFC structure",
+      "[Vue Best Practices](./references/vue/SKILL.md)"
+    ],
+    [
+      "Global/local errors, `clearError`, `showError`, or recovery flows",
+      packLink(metadata, "error-surfaces-recovery")
+    ]
   ];
   return [
-    "| Task shape or symptom | Load first | Why |",
-    "| --- | --- | --- |",
-    ...rows.map((row) => `| ${row.symptom} | ${"link" in row ? row.link : packLink(metadata, row.packId)} | ${row.why} |`)
-  ].join("\n");
-}
-function createNuxtPackTable(metadata) {
-  const rows = metadata.packs.map(
-    (pack) => `| [${pack.title}](./references/nuxt/${pack.relativePath}) | ${pack.focus} | ${pack.triggers.join("<br>")} |`
-  );
-  return [
-    "| Pack | Focus | Typical triggers |",
-    "| --- | --- | --- |",
-    ...rows
+    "| Task shape or symptom | Open first |",
+    "| --- | --- |",
+    ...rows.map(([symptom, target]) => `| ${symptom} | ${target} |`)
   ].join("\n");
 }
-function createVueGuidanceSection() {
-  return `## Vue guidance
-
-Use [Vue Best Practices](./references/vue/SKILL.md) when the task is mainly Vue component, composable, reactivity, props/emits, or SFC work and Nuxt no longer owns the abstraction.
-
-Start with these must-read Vue references:
-- [reactivity](./references/vue/references/reactivity.md)
-- [sfc](./references/vue/references/sfc.md)
-- [component-data-flow](./references/vue/references/component-data-flow.md)
-- [composables](./references/vue/references/composables.md)
-`;
+function createRoutingExamples(metadata, includeModuleAuthoring = false) {
+  const lines = [
+    `- "This page fetches twice on first load" \u2192 ${packLink(metadata, "data-fetching-ssr")}`,
+    `- "Why do I get a hydration mismatch from Date.now()?" \u2192 ${packLink(metadata, "hydration-consistency")}`,
+    `- "Change canonical URL and OG tags" \u2192 ${packLink(metadata, "page-meta-head-layout")}`,
+    `- "Expose only the public runtimeConfig key" \u2192 ${packLink(metadata, "server-routes-runtime-config")}`,
+    `- "This server/api handler cache or route rule is wrong" \u2192 ${packLink(metadata, "nitro-h3-patterns")}`,
+    `- "This modal/table/dropdown was hand-built in raw HTML" \u2192 ${packLink(metadata, "abstraction-disambiguation")}`,
+    `- "\`clearError\` is not behaving as expected" \u2192 ${packLink(metadata, "error-surfaces-recovery")}`,
+    `- "Should this secret live in runtime config or client code?" \u2192 ${packLink(metadata, "architecture-boundaries")}`,
+    ...includeModuleAuthoring ? [`- "Add a Nuxt module option, hook, or runtime extension" \u2192 ${packLink(metadata, "module-authoring")}`] : []
+  ];
+  return `## Routing examples
+${lines.join("\n")}`;
 }
 function createSkillMapSections(metadata, entries, skipped = [], includeModuleAuthoring = false) {
   const includeModuleSections = hasModuleGuidance(entries, skipped);
@@ -426,137 +333,85 @@ function createSkillMapSections(metadata, entries, skipped = [], includeModuleAu
     renderModuleGroup("Metadata-routed skills", grouped.metadataRouted, "./references/modules/"),
     renderSkippedEntries(skipped)
   ].filter(Boolean);
-  const moduleGuideContent = moduleSections.join("\n");
-  const audienceGuide = includeModuleAuthoring ? `
-## Module author focus
-
-This skill includes extra guidance for Nuxt module authors on top of the default app-oriented Nuxt packs.
-If the task touches \`defineNuxtModule\`, Nuxt Kit hooks, generated runtime files, prefixed public APIs, or release compatibility, start with ${packLink(metadata, "module-authoring")} before branching into the broader app-oriented packs.
-` : "";
-  const moduleWorkflowSteps = includeModuleSections ? `
-5. If an installed module is involved, open its entry under \`references/modules\`.
-6. Copied skills go straight to their \`SKILL.md\`; metadata-routed modules only expose docs and source links.` : "";
-  const moduleGuidesSection = includeModuleSections ? `
-## Module guides
+  const moduleGuidesSection = includeModuleSections ? `## Module guides
+Use a module entry only when an installed module owns the surface. Module guidance is delta-only and should not replace broad Nuxt rules outside that module.
 
-Open the linked module entry first. Copied skills link straight to their \`SKILL.md\`; metadata-routed modules use a small docs/source router when no copied skill exists.
+${moduleSections.join("\n")}` : "";
+  return [
+    "## Routing",
+    "Load one matching guide first. Open more guides only when the first guide points you there or the task clearly crosses boundaries.",
+    createRoutingTable(metadata, includeModuleAuthoring),
+    createRoutingExamples(metadata, includeModuleAuthoring),
+    moduleGuidesSection
+  ].filter(Boolean).join("\n\n");
+}
+function createSkillEntrypoint(skillName, metadata, monorepoScopePath, includeModuleAuthoring = false, entries = [], skipped = []) {
+  const description = "Routes Nuxt work to the smallest relevant guide. Use for `useFetch`/`useAsyncData`, SSR, hydration mismatches, `definePageMeta`, `useHead`/`useSeoMeta`, `runtimeConfig`, Nitro/h3 server routes, plugins, Nuxt UI, Nuxt Content, or Nuxt module authoring.";
+  const monorepoScopeSection = monorepoScopePath ? `## Monorepo scope
+This skill applies only to \`${monorepoScopePath}\`. Treat files and tasks outside that subtree as out of scope unless the user explicitly redirects you there.` : "";
+  return `---
+name: ${yamlString(skillName)}
+description: ${yamlString(description)}
+---
 
-${moduleGuideContent}
-` : `
-## Module guides
+# Nuxt Skill Router
 
-${EMPTY_MODULE_GUIDANCE_MARKDOWN}
-`;
-  return `## How to use this skill map
-1. Explore the current surface first: page, layout, component, server handler, content collection, or module-owned file.
-2. Load the first matching Nuxt pack from the routing table below.
-3. If the remaining work is mainly Vue component or composable implementation, switch to [Vue Best Practices](./references/vue/SKILL.md).
-4. Open deeper Nuxt packs only when the first pack points you there.
-${moduleWorkflowSteps}
-${audienceGuide}
+Use this skill to make the Nuxt ownership decision first, then route to the smallest relevant Nuxt, Vue, or module guide.
+${monorepoScopeSection ? `
+${monorepoScopeSection}
+` : "\n"}## Loading rules
+1. Repository-global instructions and required workflows win first.
+2. Inspect the exact owned surface first: page, layout, component, server handler, collection, config file, or module-owned file.
+3. Load one matching guide from the routing table below.
+4. Switch to [Vue Best Practices](./references/vue/SKILL.md) only when Nuxt no longer owns the abstraction.
+5. Use module entries only inside module-owned APIs, config, runtime behavior, and files.
+6. Open additional guides only when the first guide points you there or the task clearly crosses boundaries.
 
-## Common forks in the road
+${createSkillMapSections(metadata, entries, skipped, includeModuleAuthoring)}
 
-${createRoutingTable(metadata, includeModuleAuthoring)}
+## Finish
+For multi-surface changes or final verification, open ${packLink(metadata, "verification-finish")}.
 
-${createVueGuidanceSection()}
+- Verify paired surfaces when relevant: page/head, server/client, global/local.
+- Verify framework behavior, not only visible output.
+- Keep module guidance scoped to the owning module.
 
-## All Nuxt packs
+---
 
-${createNuxtPackTable(metadata)}
-${moduleGuidesSection}
+_Generated by nuxt-skill-hub. Do not edit this file manually._
 `;
 }
-function createSkillEntrypoint(skillName, metadata, monorepoScopePath, includeModuleAuthoring = false, entries = [], skipped = []) {
-  const profile = getSkillRenderProfile(includeModuleAuthoring);
-  const includeModuleSections = hasModuleGuidance(entries, skipped);
-  const description = "Always-on Nuxt disambiguation layer for this project. Use it to choose the right Nuxt pack first, then switch to Vue or module guidance only when Nuxt no longer owns the abstraction.";
-  const monorepoScopeSection = monorepoScopePath ? `
-## Monorepo Scope
-This skill applies only to the \`${monorepoScopePath}\` subtree of this monorepo.
-Treat files and tasks outside \`${monorepoScopePath}\` as out of scope unless the user explicitly redirects you there.
-` : "";
-  const audienceSection = profile.includeModuleAuthoring ? `
-
-## Module Author Focus
-This skill keeps the default Nuxt app guidance and adds an authoring layer for repositories that build Nuxt modules.
-Start with [Module Authoring Conventions](./references/nuxt/rules/module-authoring.md) for \`defineNuxtModule\`, lifecycle hooks, prefixed public APIs, and module-scoped skill boundaries, then fall back to the broader app packs when the task crosses into runtime behavior.
-` : "";
-  const activationFlow = `1. Explore the project first: inspect the real page, component, route, server handler, collection, or module surface you are changing.
-2. Use the routing sections in this file and load the smallest matching Nuxt pack.
-3. If the remaining work is mainly Vue component, composable, reactivity, or SFC work, open [Vue Best Practices](./references/vue/SKILL.md).
-4. If module authoring is part of the task, load [Module Authoring Conventions](./references/nuxt/rules/module-authoring.md) before changing \`defineNuxtModule\`, runtime extensions, hooks, or release scaffolding.${includeModuleSections ? `
-5. If an installed module owns the problem, open its entry under [references/modules](./references/modules).
-6. Apply module guidance as delta-only rules inside that module's APIs, config, runtime behavior, and owned files.` : ""}`;
-  const frequencyBullets = profile.includeModuleAuthoring ? `- If the task changes module boot or heavy setup work, prefer lightweight \`setup\` plus lifecycle hooks before adding blocking async work.
-- If the module exposes routes, composables, components, or config, prefix public surfaces with module identity before shipping generic names.
-- If the implementation relies on undocumented Nuxt internals, confirm there is not a public \`@nuxt/kit\` API or documented hook first.
-- If the task adds or edits a bundled module skill, keep it strictly scoped to the module's APIs, integration points, and caveats.
-- If runtime config, server handlers, or generated files are involved, pair module-author guidance with the relevant server, Nitro, plugin, or migration pack instead of improvising cross-boundary behavior.
-- If the work is version-sensitive, check compatibility constraints and migration boundaries before expanding the module surface.
-- If the task touches SSR, initial page load, or route-driven data, prefer \`useFetch\` or \`useAsyncData\` before \`onMounted\` plus \`$fetch\`.
-- If the task changes page options, layout selection, route middleware, or page-level behavior, check \`definePageMeta\` before adding ad hoc wiring.
-- If the task changes title, meta tags, canonical URLs, or OG data, check \`useHead\` or \`useSeoMeta\` before page-meta or template markup.
-- If content lives in JSON or YAML records, or the UI needs generated docs navigation, choose data collections and collection-navigation primitives before manual assembly.
-- If the UI surface is page chrome, a table, a form, a modal, a command palette, or a dropdown, prefer a Nuxt UI primitive before raw HTML or custom listeners.
-- If runtime config, tokens, secrets, or privileged API calls are involved, keep them server-side and expose only a server route or the minimum public config.
-- If hydration, browser-only APIs, time, randomness, or cookies are involved, use SSR-safe primitives first and isolate browser-only work behind \`ClientOnly\` or \`onMounted\`.
-- If the fix touches errors, fallback UI, or recovery flow, check both global and local surfaces before concluding the work is complete.
-- If the solution looks correct but uses generic Vue or hand-rolled HTML, confirm Nuxt, Nuxt Content, or Nuxt UI does not already own that abstraction.${includeModuleSections ? `
-- If the task is module-specific, use the module entry and keep module guidance scoped; do not replace broad Nuxt rules with module-specific rules.` : ""}` : `- If the task touches SSR, initial page load, or route-driven data, prefer \`useFetch\` or \`useAsyncData\` before \`onMounted\` plus \`$fetch\`.
-- If the task changes page options, layout selection, route middleware, or page-level behavior, check \`definePageMeta\` before adding ad hoc wiring.
-- If the task changes title, meta tags, canonical URLs, or OG data, check \`useHead\` or \`useSeoMeta\` before page-meta or template markup.
-- If content lives in JSON or YAML records, or the UI needs generated docs navigation, choose data collections and collection-navigation primitives before manual assembly.
-- If the UI surface is page chrome, a table, a form, a modal, a command palette, or a dropdown, prefer a Nuxt UI primitive before raw HTML or custom listeners.
-- If runtime config, tokens, secrets, or privileged API calls are involved, keep them server-side and expose only a server route or the minimum public config.
-- If hydration, browser-only APIs, time, randomness, or cookies are involved, use SSR-safe primitives first and isolate browser-only work behind \`ClientOnly\` or \`onMounted\`.
-- If the fix touches errors, fallback UI, or recovery flow, check both global and local surfaces before concluding the work is complete.
-- If the solution looks correct but uses generic Vue or hand-rolled HTML, confirm Nuxt, Nuxt Content, or Nuxt UI does not already own that abstraction.${includeModuleSections ? `
-- If the task is module-specific, use the module entry and keep module guidance scoped; do not replace broad Nuxt rules with module-specific rules.` : ""}`;
-  const beforeCompletion = profile.includeModuleAuthoring ? `- Did I start from Nuxt Kit and documented lifecycle hooks before reaching for private internals?
-- Did I keep public APIs collision-resistant and module-scoped?
-- Did I keep module skill guidance as a delta on top of Nuxt guidance instead of restating framework-global rules?
-- Did I verify compatibility, install/setup cost, and cross-boundary behavior before concluding the work is complete?
-- Did I still verify the relevant app/runtime surfaces when the module work crossed into SSR, Nitro, plugins, config, or UI behavior?` : `- Did I choose a Nuxt primitive where a generic Vue or raw HTML solution would be tempting?
-- Did I check whether the fix needs a second surface such as global or local, or server or client?
-- Did I choose the right concept pair: page meta vs head, data collection vs page collection, component primitive vs custom markup?
-- Did I verify the framework behavior that matters, not just the visible output?`;
+function createStableSkillWrapper(skillName, generatedEntryPath, generatedRootPath, generationMode) {
+  const description = "Stable entrypoint for generated Nuxt guidance in this repository. Use for Nuxt SSR, hydration, pages, `runtimeConfig`, Nitro/h3, plugins, Nuxt UI, Nuxt Content, or Nuxt module work. If generated content is missing, regenerate it with `nuxt prepare`.";
+  const recoveryInstructions = generationMode === "manual" ? [
+    "Automatic skill generation is currently disabled by `skillHub.generationMode: 'manual'`.",
+    "Ask the user to switch `skillHub.generationMode` to `'prepare'`, then run `nuxt prepare`."
+  ].join("\n") : [
+    "Run `nuxt prepare` from this project before continuing.",
+    "That regenerates the Nuxt build directory, refreshes types, and writes the generated Nuxt skill content."
+  ].join("\n");
   return `---
 name: ${yamlString(skillName)}
 description: ${yamlString(description)}
 ---
 
-# Nuxt Skill Index
-
-This file keeps the highest-frequency Nuxt decisions in context.
-Use it to avoid generic Vue fallbacks, then route into the right Nuxt pack, Vue guidance, or module delta skill.
-${monorepoScopeSection}
-${audienceSection}
-
-## Activation Flow
-${activationFlow}
-
-## High-Frequency Nuxt Decisions
-${frequencyBullets}
-
-## Precedence
-- Repository-global instructions and required workflows win first.
-- This file keeps the common Nuxt forks in context.
-- Nuxt packs provide deeper framework guidance.
-- Vue guidance covers component, composable, and SFC patterns after the Nuxt decision is settled.
-${includeModuleSections ? "- Module entries add delta-only guidance inside explicit module scope." : ""}
-
-${createSkillMapSections(metadata, entries, skipped, includeModuleAuthoring)}
+# Nuxt Skill Wrapper
 
-## Before Completion
-${beforeCompletion}
+This is the stable entrypoint for Nuxt guidance in this repository.
+The full generated skill tree lives in the Nuxt build directory so the checked-in skill surface stays small.
 
-## Primary Packs
-Start with ${createPackSummary(metadata, profile.packSummaryIds)} when the task matches one of those common routes.
+## Generated content
+- Entry: [${generatedEntryPath}](${generatedEntryPath})
+- Root: [${generatedRootPath}](${generatedRootPath})
 
----
+## Required workflow
+1. Check whether the generated entry exists.
+2. If it exists, open it and follow that generated skill instead of extending this wrapper.
+3. If it does not exist, ${recoveryInstructions}
 
-_Generated by nuxt-skill-hub. Do not edit this file manually._
+## Notes
+- Generated content is ephemeral and may be refreshed by Nuxt.
+- This wrapper is the stable file that should remain in version control.
 `;
 }
 function createCompactMetadataRouterContent(entry) {
@@ -630,6 +485,79 @@ async function loadVueSkillFiles(cacheRoot) {
   return loadVueSkillFilesFromDir(dir);
 }
 
+function resolveSkillsDir(target, config) {
+  if (config?.skillsDir) {
+    return config.skillsDir;
+  }
+  if (target === "codex") {
+    return "skills";
+  }
+  return void 0;
+}
+function normalizeTarget(target) {
+  return target.trim();
+}
+function getRawTargetConfig(target) {
+  return getAgentConfig(target);
+}
+function getSupportedTargets() {
+  return getAgentIds().filter((target) => {
+    const config = getRawTargetConfig(target);
+    return Boolean(resolveSkillsDir(target, config));
+  }).sort((a, b) => a.localeCompare(b));
+}
+function resolveAgentTargetConfig(target) {
+  const normalized = normalizeTarget(target);
+  if (!normalized) {
+    return void 0;
+  }
+  const config = getRawTargetConfig(normalized);
+  const skillsDir = resolveSkillsDir(normalized, config);
+  if (!config || !skillsDir) {
+    return void 0;
+  }
+  return {
+    target: normalized,
+    configDir: expandPath(config.configDir),
+    skillsDir
+  };
+}
+function validateTargets(targets) {
+  const uniqueTargets = Array.from(new Set(targets.map(normalizeTarget).filter(Boolean)));
+  const valid = [];
+  const invalid = [];
+  for (const target of uniqueTargets) {
+    const config = getRawTargetConfig(target);
+    if (!config) {
+      invalid.push({
+        target,
+        reason: "unknown-target"
+      });
+      continue;
+    }
+    if (!resolveSkillsDir(target, config)) {
+      invalid.push({
+        target,
+        reason: "missing-skills-dir"
+      });
+      continue;
+    }
+    valid.push(target);
+  }
+  return { valid, invalid };
+}
+function detectCurrentTarget() {
+  const current = detectCurrentAgent();
+  if (!current) return void 0;
+  const skillsDir = resolveSkillsDir(current.id, current.config);
+  return skillsDir ? current.id : void 0;
+}
+function detectInstalledTargets() {
+  return Array.from(new Set(
+    detectInstalledAgents().filter((agent) => agent.detected === "config" && resolveSkillsDir(agent.id, agent.config)).map((agent) => agent.id)
+  )).sort((a, b) => a.localeCompare(b));
+}
+
 const MANAGED_HINT_START = "<!-- nuxt-skill-hub:start -->";
 const MANAGED_HINT_END = "<!-- nuxt-skill-hub:end -->";
 const SKILL_NAME_MAX_LENGTH = 64;
@@ -683,11 +611,19 @@ async function hasWorkspacePackageConfig(path) {
 }
 async function resolveExportRoot(rootDir) {
   const appRoot = resolve(rootDir);
+  const workspaceDir = await findWorkspaceDir(appRoot).catch(() => null);
+  if (!workspaceDir) {
+    return appRoot;
+  }
+  const resolvedWorkspaceDir = resolve(workspaceDir);
   let current = appRoot;
   while (true) {
     if (await pathExists(join(current, "pnpm-workspace.yaml")) || await hasWorkspacePackageConfig(current)) {
       return current;
     }
+    if (current === resolvedWorkspaceDir) {
+      return appRoot;
+    }
     const parent = dirname(current);
     if (parent === current) {
       return appRoot;
@@ -1104,217 +1040,20 @@ function formatConflictWarning(conflict) {
   return `Found ${conflict.skillNames.length} standalone skill(s) that may conflict with nuxt-skill-hub: ${conflict.skillNames.join(", ")} (global: ${conflict.globalDir}). Remove with: npx skills remove --global`;
 }
 
-function isCancelled(value) {
-  return value === null || typeof value === "symbol";
-}
-async function runInstallWizard(nuxt) {
-  const logger = useLogger("nuxt-skill-hub");
-  if (process.env.CI || !process.stdout.isTTY) {
-    logger.info("Non-interactive environment detected, skipping install wizard.");
-    return;
-  }
-  const consola = createConsola();
-  const rootDir = nuxt.options.rootDir;
-  const exportRoot = await resolveExportRoot(rootDir);
-  const skillName = await deriveSkillName(rootDir);
-  const pendingWrites = [];
-  consola.box(
-    `nuxt-skill-hub \u2014 First-time setup
-Let's configure AI agent skills for your Nuxt project.`
-  );
-  const currentTarget = detectCurrentTarget();
-  let selectedTargets;
-  if (currentTarget) {
-    consola.info(`Running inside ${currentTarget}, auto-selecting it.`);
-    selectedTargets = [currentTarget];
-  } else {
-    const detectedTargets = detectInstalledTargets();
-    const allTargets = getSupportedTargets();
-    if (!detectedTargets.length && !allTargets.length) {
-      consola.warn("No AI agents detected. Skills will be generated when an agent is detected.");
-      consola.info("Supported agents are sourced from unagent.");
-      return;
-    }
-    consola.info(`Detected agents: ${detectedTargets.length ? detectedTargets.join(", ") : "none"}`);
-    selectedTargets = detectedTargets;
-    if (detectedTargets.length > 1) {
-      const keepAll = await consola.prompt("Generate skills for all detected agents?", {
-        type: "confirm",
-        initial: true,
-        cancel: "null"
-      });
-      if (isCancelled(keepAll)) {
-        consola.info("Setup cancelled.");
-        return;
-      }
-      if (!keepAll) {
-        const chosen = await consola.prompt("Select agents to generate skills for:", {
-          type: "multiselect",
-          options: detectedTargets.map((t) => ({ label: t, value: t })),
-          initial: detectedTargets,
-          required: true,
-          cancel: "null"
-        });
-        if (isCancelled(chosen)) {
-          consola.info("Setup cancelled.");
-          return;
-        }
-        selectedTargets = chosen.map((c) => c.value);
-      }
-    }
-  }
-  const moduleSpecifiers = (nuxt.options.modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry));
-  const uniqueSpecifiers = Array.from(new Set(moduleSpecifiers));
-  const installedModulePackages = [];
-  for (const specifier of uniqueSpecifiers) {
-    const pkg = await discoverInstalledPackageFromSpecifier(specifier, rootDir);
-    if (!pkg || pkg.packageName === "nuxt-skill-hub")
-      continue;
-    installedModulePackages.push(pkg.packageName);
-  }
-  if (installedModulePackages.length) {
-    consola.info(`Detected ${installedModulePackages.length} installed module package(s):`);
-    for (const packageName of installedModulePackages) {
-      consola.log(`  ${packageName}`);
-    }
-    consola.info("Module skills and metadata routers are resolved automatically at build time.");
-  } else {
-    consola.info("No installed module entries were discovered.");
-  }
-  for (const conflict of detectConflictingSkills(selectedTargets, skillName)) {
-    consola.warn(formatConflictWarning(conflict));
-  }
-  const gitignorePath = join(exportRoot, ".gitignore");
-  const gitignoreExists = existsSync(gitignorePath);
-  const currentGitignore = gitignoreExists ? readFileSync(gitignorePath, "utf8") : "";
-  const missingPatterns = [];
-  for (const target of selectedTargets) {
-    const { skillRoot } = getTargetSkillRoot(exportRoot, target, skillName);
-    const pattern = relative(exportRoot, skillRoot).replace(/\/?$/, "/");
-    if (!currentGitignore.includes(pattern)) {
-      missingPatterns.push(pattern);
-    }
-  }
-  if (missingPatterns.length) {
-    const addGitignore = await consola.prompt(
-      `Add generated skill directories to .gitignore?
-${missingPatterns.map((p) => `  ${p}`).join("\n")}`,
-      { type: "confirm", initial: true, cancel: "null" }
-    );
-    if (isCancelled(addGitignore)) {
-      consola.info("Setup cancelled.");
-      return;
-    }
-    if (addGitignore) {
-      const block = `
-# nuxt-skill-hub (generated skills)
-${missingPatterns.join("\n")}
-`;
-      const newContent = currentGitignore.trimEnd() + "\n" + block;
-      pendingWrites.push({
-        file: ".gitignore",
-        absPath: gitignorePath,
-        preview: missingPatterns.map((p) => `+ ${p}`).join("\n"),
-        content: newContent,
-        action: gitignoreExists ? "modify" : "create"
-      });
-    }
-  }
-  const hintBlock = `${MANAGED_HINT_START}
-Use the \`${skillName}\` skill as the first entrypoint for Nuxt tasks in this repository.
-${MANAGED_HINT_END}`;
-  const hintFileChoice = await consola.prompt("Add a skill hint to help agents discover the skill?", {
-    type: "select",
-    options: [
-      { label: "CLAUDE.md", value: "claude", hint: "Claude Code project instructions" },
-      { label: "AGENTS.md", value: "agents", hint: "Universal agent instructions" },
-      { label: "Both", value: "both" },
-      { label: "Skip", value: "skip" }
-    ],
-    cancel: "null"
-  });
-  if (isCancelled(hintFileChoice)) {
-    consola.info("Setup cancelled.");
-    return;
-  }
-  const addToFile = async (filename) => {
-    const filePath = join(exportRoot, filename);
-    const exists = await pathExists(filePath);
-    const current = exists ? readFileSync(filePath, "utf8") : "";
-    const regex = new RegExp(`${MANAGED_HINT_START}[\\s\\S]*?${MANAGED_HINT_END}`);
-    let newContent;
-    if (regex.test(current)) {
-      newContent = current.replace(regex, hintBlock);
-    } else if (current) {
-      newContent = `${current.trimEnd()}
-
-${hintBlock}
-`;
-    } else {
-      newContent = `${hintBlock}
-`;
-    }
-    pendingWrites.push({
-      file: filename,
-      absPath: filePath,
-      preview: `+ Use the \`${skillName}\` skill as the first entrypoint for Nuxt tasks in this repository.`,
-      content: newContent,
-      action: exists ? "modify" : "create"
-    });
-  };
-  if (hintFileChoice === "claude" || hintFileChoice === "both") {
-    await addToFile("CLAUDE.md");
-  }
-  if (hintFileChoice === "agents" || hintFileChoice === "both") {
-    await addToFile("AGENTS.md");
-  }
-  if (!pendingWrites.length) {
-    consola.success("No file changes needed. Setup complete!");
-    consola.info("Run `nuxt dev` or `nuxt prepare` to generate skills.");
-    return;
-  }
-  consola.log("");
-  consola.info("Planned changes:");
-  for (const write of pendingWrites) {
-    consola.box({ title: write.file, message: colorize("green", write.preview), style: { borderColor: "green" } });
-  }
-  const confirm = await consola.prompt("Apply these changes?", {
-    type: "confirm",
-    initial: true,
-    cancel: "null"
-  });
-  if (isCancelled(confirm) || !confirm) {
-    consola.info("Setup cancelled. No files were modified.");
-    return;
-  }
-  for (const write of pendingWrites) {
-    writeFileSync(write.absPath, write.content, "utf8");
-    const verb = write.action === "create" ? "Created" : "Updated";
-    consola.success(`${verb} ${write.file}`);
-  }
-  consola.log("");
-  consola.box(
-    `Setup complete!
-
-Run \`nuxt dev\` or \`nuxt prepare\` to generate skills.
-Configure \`skillHub.skillName\` or \`skillHub.targets\` in nuxt.config.ts if needed.`
-  );
-}
-
-const GITHUB_OVERRIDES = [
-  {
-    packageName: "@nuxt/ui",
-    repo: "nuxt/ui",
-    ref: "v4",
-    path: "skills/nuxt-ui",
-    skillName: "nuxt-ui"
-  },
-  {
-    packageName: "@vueuse/core",
-    repo: "vueuse/vueuse",
-    ref: "main",
-    path: "skills/vueuse-functions",
-    skillName: "vueuse-functions"
+const GITHUB_OVERRIDES = [
+  {
+    packageName: "@nuxt/ui",
+    repo: "nuxt/ui",
+    ref: "v4",
+    path: "skills/nuxt-ui",
+    skillName: "nuxt-ui"
+  },
+  {
+    packageName: "@vueuse/core",
+    repo: "vueuse/vueuse",
+    ref: "main",
+    path: "skills/vueuse-functions",
+    skillName: "vueuse-functions"
   }
 ];
 function findGitHubOverride(packageName) {
@@ -1699,11 +1438,198 @@ async function resolveRemoteContributionsForPackage(packageInfo, options) {
   };
 }
 
-const GITHUB_LOOKUP_TIMEOUT_MS = 1500;
+const DEFAULT_SKILL_HUB_GENERATION_MODE = "prepare";
+function normalizeGenerationMode(value) {
+  return value === "manual" ? "manual" : DEFAULT_SKILL_HUB_GENERATION_MODE;
+}
+
+async function resolveLockfileInfo(exportRoot) {
+  let lockfilePath;
+  try {
+    lockfilePath = await resolveLockfile(exportRoot);
+  } catch {
+    return null;
+  }
+  const contents = await promises.readFile(lockfilePath);
+  const hash = createHash("sha256").update(contents).digest("hex");
+  return {
+    path: relative(exportRoot, lockfilePath).replaceAll("\\", "/"),
+    hash
+  };
+}
+async function createGenerationFingerprint(input) {
+  const rootPackageHash = await hashFileIfExists(join(input.rootDir, "package.json"));
+  const lockfile = await resolveLockfileInfo(input.exportRoot);
+  const modules = [...input.installedPackages].filter((pkg) => pkg.packageName !== "nuxt-skill-hub").map((pkg) => ({ name: pkg.packageName, version: pkg.version || null })).sort((a, b) => a.name.localeCompare(b.name));
+  const localSources = [...input.localSources].sort((a, b) => {
+    const left = `${a.packageName}::${a.skillName}::${a.sourceDir}`;
+    const right = `${b.packageName}::${b.skillName}::${b.sourceDir}`;
+    return left.localeCompare(right);
+  });
+  return hash({
+    packageVersion: input.packageVersion,
+    skillName: input.skillName,
+    rootDir: input.rootDir,
+    buildDir: input.buildDir,
+    rootPackageHash,
+    lockfile,
+    modules,
+    localSources,
+    skillHub: {
+      skillName: input.options.skillName?.trim() || null,
+      targets: [...input.options.targets || []].sort(),
+      moduleAuthoring: Boolean(input.options.moduleAuthoring),
+      generationMode: normalizeGenerationMode(input.options.generationMode)
+    }
+  });
+}
+async function hashFileIfExists(path) {
+  try {
+    const contents = await promises.readFile(path);
+    return createHash("sha256").update(contents).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
 async function resolveManualContribution(rootDir, contribution) {
   const sourceDir = isAbsolute(contribution.sourceDir) ? contribution.sourceDir : resolve(rootDir, contribution.sourceDir);
   return normalizeContribution(contribution, sourceDir, sourceDir);
 }
+function collectWorkspaceDiscoverySources(_rootDir, discoveries) {
+  const contributions = [];
+  for (const discovery of discoveries) {
+    if (!isLocalDiscoveryRoot(discovery.packageRoot)) {
+      continue;
+    }
+    for (const skill of discovery.skills) {
+      const sourceDir = resolve(discovery.packageRoot, skill.path);
+      contributions.push(normalizeContribution({
+        packageName: discovery.packageName,
+        version: discovery.version,
+        skillName: skill.name
+      }, sourceDir, discovery.packageRoot));
+    }
+  }
+  return sortAndDedupeContributions(contributions);
+}
+function isLocalDiscoveryRoot(packageRoot) {
+  const normalizedRoot = resolve(packageRoot).replaceAll("\\", "/");
+  return !/(?:^|\/)node_modules(?:\/|$)/.test(normalizedRoot);
+}
+async function createLocalSourceFingerprints(contributions) {
+  const fingerprints = await Promise.all(contributions.map(async (contribution) => ({
+    packageName: contribution.packageName,
+    skillName: contribution.skillName,
+    sourceDir: resolve(contribution.sourceDir).replaceAll("\\", "/"),
+    sourceRoot: resolve(contribution.sourceRoot).replaceAll("\\", "/"),
+    sourceKind: contribution.sourceKind,
+    forceIncludeScripts: contribution.forceIncludeScripts,
+    hash: await hashDirectoryTreeIfExists(contribution.sourceDir)
+  })));
+  return fingerprints.sort((a, b) => {
+    const left = `${a.packageName}::${a.skillName}::${a.sourceDir}`;
+    const right = `${b.packageName}::${b.skillName}::${b.sourceDir}`;
+    return left.localeCompare(right);
+  });
+}
+async function hashDirectoryTreeIfExists(rootPath) {
+  let rootStat;
+  try {
+    rootStat = await promises.lstat(rootPath);
+  } catch {
+    return null;
+  }
+  if (!rootStat.isDirectory()) {
+    return null;
+  }
+  const hash = createHash("sha256");
+  hash.update("dir:.\n");
+  const entries = await glob("**/*", {
+    cwd: rootPath,
+    dot: true,
+    expandDirectories: false,
+    followSymbolicLinks: false,
+    onlyFiles: false
+  });
+  entries.sort((a, b) => a.localeCompare(b));
+  for (const entry of entries) {
+    const currentPath = join(rootPath, entry);
+    const stat = await promises.lstat(currentPath);
+    const relativePath = relative(rootPath, currentPath).replaceAll("\\", "/");
+    if (stat.isSymbolicLink()) {
+      hash.update(`symlink:${relativePath}:`);
+      hash.update(await promises.readlink(currentPath));
+      hash.update("\n");
+      continue;
+    }
+    if (stat.isDirectory()) {
+      hash.update(`dir:${relativePath}
+`);
+      continue;
+    }
+    if (stat.isFile()) {
+      hash.update(`file:${relativePath}:`);
+      hash.update(await promises.readFile(currentPath));
+      hash.update("\n");
+      continue;
+    }
+    hash.update(`other:${relativePath}:${stat.mode}
+`);
+  }
+  return hash.digest("hex");
+}
+
+const GENERATION_STATE_FILE = ".state.json";
+function getGenerationStatePath(generatedSkillRoot) {
+  return join(generatedSkillRoot, GENERATION_STATE_FILE);
+}
+async function readGenerationState(generatedSkillRoot) {
+  const statePath = getGenerationStatePath(generatedSkillRoot);
+  if (!await pathExists(statePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(await promises.readFile(statePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function writeGenerationState(generatedSkillRoot, fingerprint) {
+  const state = {
+    fingerprint,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    packageVersion: PACKAGE_VERSION
+  };
+  await writeFileIfChanged(getGenerationStatePath(generatedSkillRoot), `${JSON.stringify(state, null, 2)}
+`);
+}
+async function isGeneratedSkillFresh(generatedSkillRoot, fingerprint) {
+  const [state, entryExists] = await Promise.all([
+    readGenerationState(generatedSkillRoot),
+    pathExists(join(generatedSkillRoot, "SKILL.md"))
+  ]);
+  return Boolean(entryExists && state?.fingerprint === fingerprint);
+}
+
+const GITHUB_LOOKUP_TIMEOUT_MS = 1500;
+function resolveStableSkillBuildDir(rootDir, buildDir) {
+  const rel = relative(resolve(rootDir), resolve(buildDir)).replaceAll("\\", "/");
+  if (rel === ".nuxt" || rel.startsWith(".nuxt/")) {
+    return join(resolve(rootDir), ".nuxt");
+  }
+  return buildDir;
+}
+function normalizeRelativePath(from, to) {
+  const rel = relative(from, to).replaceAll("\\", "/");
+  if (!rel || rel === ".") {
+    return "./";
+  }
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function getGeneratedSkillRoot(buildDir, skillName) {
+  return join(buildDir, "skill-hub", skillName);
+}
 function mergeSkipped(entries, keyFn) {
   const byKey = /* @__PURE__ */ new Map();
   for (const entry of entries) {
@@ -1719,6 +1645,366 @@ function mergeSkipped(entries, keyFn) {
   }
   return Array.from(byKey.values()).sort((a, b) => `${a.packageName}::${a.skillName}`.localeCompare(`${b.packageName}::${b.skillName}`));
 }
+async function removeLegacyRootArtifacts(skillRoot) {
+  await Promise.all([
+    promises.rm(join(skillRoot, "references"), { recursive: true, force: true }),
+    promises.rm(join(skillRoot, "manifest.json"), { force: true })
+  ]);
+}
+async function collectInstalledPackages(nuxt) {
+  const discoveries = [];
+  const installedPackages = [];
+  const seenPackageRoots = /* @__PURE__ */ new Set();
+  const addInstalledPackage = (installedPackage) => {
+    if (!installedPackage || seenPackageRoots.has(installedPackage.packageRoot)) {
+      return;
+    }
+    seenPackageRoots.add(installedPackage.packageRoot);
+    installedPackages.push(installedPackage);
+    const discovered = discoverPackageSkillsFromInstalledPackage(installedPackage, "dist");
+    if (discovered) {
+      discoveries.push(discovered);
+    }
+  };
+  const moduleSpecifiers = (nuxt.options.modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry));
+  const seenSpecifiers = Array.from(new Set(moduleSpecifiers));
+  for (const specifier of seenSpecifiers) {
+    addInstalledPackage(await discoverInstalledPackageFromSpecifier(specifier, nuxt.options.rootDir));
+  }
+  const layerDirectories = Array.from(new Set(
+    nuxt.options._layers.map((layer) => resolve(layer.cwd || layer.config.rootDir || "")).filter((layerDir) => layerDir && layerDir !== resolve(nuxt.options.rootDir))
+  ));
+  for (const layerDirectory of layerDirectories) {
+    addInstalledPackage(await discoverInstalledPackageFromDirectory(layerDirectory));
+  }
+  const localPackageSkills = await discoverLocalPackageSkills(nuxt.options.rootDir);
+  if (localPackageSkills) {
+    discoveries.push(localPackageSkills);
+  }
+  return {
+    discoveries,
+    installedPackages
+  };
+}
+async function ensureStableSkillWrappers(input) {
+  const stableBuildDir = resolveStableSkillBuildDir(input.rootDir, input.buildDir);
+  const generatedSkillRoot = getGeneratedSkillRoot(stableBuildDir, input.skillName);
+  const generatedEntryPath = join(generatedSkillRoot, "SKILL.md");
+  for (const target of input.targets) {
+    const { skillRoot } = getTargetSkillRoot(input.exportRoot, target, input.skillName);
+    await ensureDir(skillRoot);
+    await removeLegacyRootArtifacts(skillRoot);
+    const wrapper = createStableSkillWrapper(
+      input.skillName,
+      normalizeRelativePath(skillRoot, generatedEntryPath),
+      normalizeRelativePath(skillRoot, generatedSkillRoot),
+      input.generationMode
+    );
+    await writeFileIfChanged(join(skillRoot, "SKILL.md"), wrapper);
+  }
+}
+async function generateSkillTree(input) {
+  const { nuxt, logger, options, skillName, exportRoot, generationMode } = input;
+  const stableBuildDir = resolveStableSkillBuildDir(nuxt.options.rootDir, nuxt.options.buildDir);
+  const generatedSkillRoot = getGeneratedSkillRoot(stableBuildDir, skillName);
+  const referencesRoot = join(generatedSkillRoot, "references");
+  const nuxtRoot = join(referencesRoot, "nuxt");
+  const vueRoot = join(referencesRoot, "vue");
+  const modulesRoot = join(referencesRoot, "modules");
+  const monorepoScopePath = resolveMonorepoScopePath(nuxt.options.rootDir, exportRoot);
+  const manualContributions = [];
+  const contributionContext = {
+    add: (contribution) => {
+      manualContributions.push(contribution);
+    }
+  };
+  const callSkillContributeHook = nuxt.callHook;
+  await callSkillContributeHook("skill-hub:contribute", contributionContext);
+  const { discoveries, installedPackages } = await collectInstalledPackages(nuxt);
+  const discoveredContributions = await resolveContributions(discoveries);
+  const workspaceDiscoverySources = collectWorkspaceDiscoverySources(nuxt.options.rootDir, discoveries);
+  const resolvedManual = await Promise.all(
+    manualContributions.map((contribution) => resolveManualContribution(nuxt.options.rootDir, contribution))
+  );
+  const fingerprint = await createGenerationFingerprint({
+    packageVersion: PACKAGE_VERSION,
+    rootDir: nuxt.options.rootDir,
+    buildDir: nuxt.options.buildDir,
+    exportRoot,
+    skillName,
+    options,
+    installedPackages,
+    localSources: await createLocalSourceFingerprints([
+      ...workspaceDiscoverySources,
+      ...sortAndDedupeContributions(resolvedManual)
+    ])
+  });
+  if (generationMode === "prepare" && await isGeneratedSkillFresh(generatedSkillRoot, fingerprint)) {
+    logger.info(`Generated ${skillName} skill is already up to date at ${generatedSkillRoot}`);
+    return;
+  }
+  const distResolvedPackages = new Set(discoveredContributions.contributions.map((item) => item.packageName));
+  const remoteIssues = [];
+  const remoteSkipped = [];
+  const remoteContributions = [];
+  const remoteCacheRoot = join(stableBuildDir, "skill-hub-cache");
+  await emptyDir(remoteCacheRoot);
+  const packagesToResolve = installedPackages.filter((pkg) => pkg.packageName !== "nuxt-skill-hub" && !distResolvedPackages.has(pkg.packageName));
+  const totalToResolve = packagesToResolve.length;
+  for (let i = 0; i < packagesToResolve.length; i++) {
+    const pkg = packagesToResolve[i];
+    logger.start(`[${i + 1}/${totalToResolve}] Resolving skills for ${pkg.packageName}...`);
+    const remote = await resolveRemoteContributionsForPackage(pkg, {
+      cacheRoot: remoteCacheRoot,
+      githubLookupTimeoutMs: GITHUB_LOOKUP_TIMEOUT_MS,
+      enableGithubLookup: true
+    });
+    remoteIssues.push(...remote.issues);
+    remoteSkipped.push(...remote.skipped);
+    remoteContributions.push(...remote.contributions);
+  }
+  const validatedRemote = await validateResolvedContributions(sortAndDedupeContributions(remoteContributions));
+  const validatedManual = await validateResolvedContributions(sortAndDedupeContributions(resolvedManual));
+  const contributions = sortAndDedupeContributions([
+    ...discoveredContributions.contributions,
+    ...validatedRemote.contributions,
+    ...validatedManual.contributions
+  ]);
+  const validationIssues = [
+    ...discoveredContributions.issues,
+    ...remoteIssues,
+    ...validatedRemote.issues,
+    ...validatedManual.issues
+  ];
+  const issuesToSkipped = mergeSkipped(
+    validationIssues.map((issue) => ({ packageName: issue.packageName, skillName: issue.skillName, reason: issue.reason, sourceKind: issue.sourceKind })),
+    (entry) => `${entry.packageName}::${entry.skillName}`
+  );
+  const skipped = mergeSkipped(
+    [...issuesToSkipped, ...remoteSkipped],
+    (entry) => `${entry.packageName}::${entry.skillName}::${entry.sourceKind || ""}`
+  );
+  for (const issue of validationIssues) {
+    logger.warn(`[validation] ${issue.packageName}/${issue.skillName}: ${issue.reason}`);
+  }
+  await emptyDir(generatedSkillRoot);
+  await ensureDir(nuxtRoot);
+  await ensureDir(vueRoot);
+  await ensureDir(modulesRoot);
+  const nuxtTemplateFiles = await buildNuxtTemplateFiles(nuxtRoot);
+  for (const file of nuxtTemplateFiles) {
+    await writeFileIfChanged(file.path, file.contents);
+  }
+  const nuxtIndexTemplatePath = join(nuxtRoot, "index.template.md");
+  const nuxtIndexTemplate = await pathExists(nuxtIndexTemplatePath) ? await promises.readFile(nuxtIndexTemplatePath, "utf8") : "";
+  const nuxtIndexContent = await renderAutomdTemplate(nuxtIndexTemplate, nuxtRoot);
+  await writeFileIfChanged(join(nuxtRoot, "index.md"), nuxtIndexContent);
+  logger.start("Fetching Vue best-practices content...");
+  const vueTemplateFiles = await buildVueTemplateFiles(vueRoot, remoteCacheRoot);
+  for (const file of vueTemplateFiles) {
+    await writeFileIfChanged(file.path, file.contents);
+  }
+  const generatedEntries = [];
+  for (const contribution of contributions) {
+    const includeScripts = contribution.forceIncludeScripts;
+    const destination = createModuleDestination(modulesRoot, contribution);
+    await copySkillTree(contribution.sourceDir, destination, includeScripts);
+    const entryPath = relative(generatedSkillRoot, join(destination, "SKILL.md")).replaceAll("\\", "/");
+    generatedEntries.push({
+      packageName: contribution.packageName,
+      version: contribution.version,
+      skillName: contribution.skillName,
+      entryPath,
+      sourceDir: contribution.sourceDir,
+      destination: relative(generatedSkillRoot, destination).replaceAll("\\", "/"),
+      scriptsIncluded: includeScripts,
+      description: contribution.description,
+      sourceKind: contribution.sourceKind,
+      sourceLabel: getSourceLabel(contribution.sourceKind),
+      sourceRepo: contribution.sourceRepo,
+      sourceRef: contribution.sourceRef,
+      sourcePath: contribution.sourcePath,
+      repoUrl: contribution.repoUrl,
+      docsUrl: contribution.docsUrl,
+      official: contribution.official,
+      trustLevel: getTrustLevel(contribution.official),
+      resolver: contribution.resolver
+    });
+  }
+  const nuxtMetadata = await loadNuxtMetadata();
+  await writeFileIfChanged(join(generatedSkillRoot, "SKILL.md"), createSkillEntrypoint(
+    skillName,
+    nuxtMetadata,
+    monorepoScopePath,
+    Boolean(options.moduleAuthoring),
+    generatedEntries,
+    skipped
+  ));
+  await writeGenerationState(generatedSkillRoot, fingerprint);
+  logger.success(`Generated ${skillName} skill at ${generatedSkillRoot}`);
+}
+
+function isCancelled(value) {
+  return value === null || typeof value === "symbol";
+}
+async function runInstallWizard(nuxt) {
+  const logger = useLogger("nuxt-skill-hub");
+  if (process.env.CI || !process.stdout.isTTY) {
+    logger.info("Non-interactive environment detected, skipping install wizard.");
+    return;
+  }
+  const consola = createConsola();
+  const rootDir = nuxt.options.rootDir;
+  const exportRoot = await resolveExportRoot(rootDir);
+  const skillName = await deriveSkillName(rootDir);
+  const pendingWrites = [];
+  consola.box(
+    `nuxt-skill-hub \u2014 First-time setup
+Let's configure AI agent skills for your Nuxt project.`
+  );
+  const currentTarget = detectCurrentTarget();
+  let selectedTargets;
+  if (currentTarget) {
+    consola.info(`Running inside ${currentTarget}, auto-selecting it.`);
+    selectedTargets = [currentTarget];
+  } else {
+    const detectedTargets = detectInstalledTargets();
+    const allTargets = getSupportedTargets();
+    if (!detectedTargets.length && !allTargets.length) {
+      consola.warn("No AI agents detected. Skills will be generated when an agent is detected.");
+      consola.info("Supported agents are sourced from unagent.");
+      return;
+    }
+    consola.info(`Detected agents: ${detectedTargets.length ? detectedTargets.join(", ") : "none"}`);
+    selectedTargets = detectedTargets;
+    if (detectedTargets.length > 1) {
+      const keepAll = await consola.prompt("Generate skills for all detected agents?", {
+        type: "confirm",
+        initial: true,
+        cancel: "null"
+      });
+      if (isCancelled(keepAll)) {
+        consola.info("Setup cancelled.");
+        return;
+      }
+      if (!keepAll) {
+        const chosen = await consola.prompt("Select agents to generate skills for:", {
+          type: "multiselect",
+          options: detectedTargets.map((t) => ({ label: t, value: t })),
+          initial: detectedTargets,
+          required: true,
+          cancel: "null"
+        });
+        if (isCancelled(chosen)) {
+          consola.info("Setup cancelled.");
+          return;
+        }
+        selectedTargets = chosen.map((c) => c.value);
+      }
+    }
+  }
+  const moduleSpecifiers = (nuxt.options.modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry));
+  const uniqueSpecifiers = Array.from(new Set(moduleSpecifiers));
+  const installedModulePackages = [];
+  for (const specifier of uniqueSpecifiers) {
+    const pkg = await discoverInstalledPackageFromSpecifier(specifier, rootDir);
+    if (!pkg || pkg.packageName === "nuxt-skill-hub")
+      continue;
+    installedModulePackages.push(pkg.packageName);
+  }
+  if (installedModulePackages.length) {
+    consola.info(`Detected ${installedModulePackages.length} installed module package(s):`);
+    for (const packageName of installedModulePackages) {
+      consola.log(`  ${packageName}`);
+    }
+    consola.info("Module skills and metadata routers are resolved automatically at build time.");
+  } else {
+    consola.info("No installed module entries were discovered.");
+  }
+  for (const conflict of detectConflictingSkills(selectedTargets, skillName)) {
+    consola.warn(formatConflictWarning(conflict));
+  }
+  const hintBlock = `${MANAGED_HINT_START}
+Use the \`${skillName}\` skill as the Nuxt router/entrypoint for tasks in this repository.
+${MANAGED_HINT_END}`;
+  const hintFileChoice = await consola.prompt("Add a skill hint to help agents discover the skill?", {
+    type: "select",
+    options: [
+      { label: "CLAUDE.md", value: "claude", hint: "Claude Code project instructions" },
+      { label: "AGENTS.md", value: "agents", hint: "Universal agent instructions" },
+      { label: "Both", value: "both" },
+      { label: "Skip", value: "skip" }
+    ],
+    cancel: "null"
+  });
+  if (isCancelled(hintFileChoice)) {
+    consola.info("Setup cancelled.");
+    return;
+  }
+  const addToFile = async (filename) => {
+    const filePath = join(exportRoot, filename);
+    const exists = await pathExists(filePath);
+    const current = exists ? readFileSync(filePath, "utf8") : "";
+    const regex = new RegExp(`${MANAGED_HINT_START}[\\s\\S]*?${MANAGED_HINT_END}`);
+    let newContent;
+    if (regex.test(current)) {
+      newContent = current.replace(regex, hintBlock);
+    } else if (current) {
+      newContent = `${current.trimEnd()}
+
+${hintBlock}
+`;
+    } else {
+      newContent = `${hintBlock}
+`;
+    }
+    pendingWrites.push({
+      file: filename,
+      absPath: filePath,
+      preview: `+ Use the \`${skillName}\` skill as the Nuxt router/entrypoint for tasks in this repository.`,
+      content: newContent,
+      action: exists ? "modify" : "create"
+    });
+  };
+  if (hintFileChoice === "claude" || hintFileChoice === "both") {
+    await addToFile("CLAUDE.md");
+  }
+  if (hintFileChoice === "agents" || hintFileChoice === "both") {
+    await addToFile("AGENTS.md");
+  }
+  if (!pendingWrites.length) {
+    consola.success("No file changes needed. Setup complete!");
+    consola.info("Run `nuxt prepare` to generate the build-dir skill output.");
+    return;
+  }
+  consola.log("");
+  consola.info("Planned changes:");
+  for (const write of pendingWrites) {
+    consola.box({ title: write.file, message: colorize("green", write.preview), style: { borderColor: "green" } });
+  }
+  const confirm = await consola.prompt("Apply these changes?", {
+    type: "confirm",
+    initial: true,
+    cancel: "null"
+  });
+  if (isCancelled(confirm) || !confirm) {
+    consola.info("Setup cancelled. No files were modified.");
+    return;
+  }
+  for (const write of pendingWrites) {
+    writeFileSync(write.absPath, write.content, "utf8");
+    const verb = write.action === "create" ? "Created" : "Updated";
+    consola.success(`${verb} ${write.file}`);
+  }
+  consola.log("");
+  consola.box(
+    `Setup complete!
+
+Run \`nuxt prepare\` to generate the build-dir skill output.
+Configure \`skillHub.skillName\`, \`skillHub.targets\`, or set \`skillHub.generationMode: 'manual'\` in nuxt.config.ts if needed.`
+  );
+}
+
 const module$1 = defineNuxtModule({
   meta: {
     name: "nuxt-skill-hub",
@@ -1734,7 +2020,8 @@ const module$1 = defineNuxtModule({
   defaults: {
     skillName: "",
     targets: [],
-    moduleAuthoring: false
+    moduleAuthoring: false,
+    generationMode: DEFAULT_SKILL_HUB_GENERATION_MODE
   },
   async setup(options, nuxt) {
     const logger = useLogger("nuxt-skill-hub");
@@ -1752,173 +2039,52 @@ const module$1 = defineNuxtModule({
       }
       resolvedSkillName = await deriveSkillName(nuxt.options.rootDir);
     }
-    nuxt.hook("modules:done", async () => {
-      const exportRoot = await resolveExportRoot(nuxt.options.rootDir);
-      const monorepoScopePath = resolveMonorepoScopePath(nuxt.options.rootDir, exportRoot);
-      const manualContributions = [];
-      const contributionContext = {
-        add: (contribution) => {
-          manualContributions.push(contribution);
-        }
-      };
-      const callSkillContributeHook = nuxt.callHook;
-      await callSkillContributeHook("skill-hub:contribute", contributionContext);
-      const discoveries = [];
-      const installedPackages = [];
-      const seenPackageRoots = /* @__PURE__ */ new Set();
-      const addInstalledPackage = (installedPackage) => {
-        if (!installedPackage || seenPackageRoots.has(installedPackage.packageRoot)) {
-          return;
-        }
-        seenPackageRoots.add(installedPackage.packageRoot);
-        installedPackages.push(installedPackage);
-        const discovered = discoverPackageSkillsFromInstalledPackage(installedPackage, "dist");
-        if (discovered) {
-          discoveries.push(discovered);
-        }
-      };
-      const moduleSpecifiers = (nuxt.options.modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry));
-      const seenSpecifiers = Array.from(new Set(moduleSpecifiers));
-      for (const specifier of seenSpecifiers) {
-        addInstalledPackage(await discoverInstalledPackageFromSpecifier(specifier, nuxt.options.rootDir));
-      }
-      const layerDirectories = Array.from(new Set(
-        nuxt.options._layers.map((layer) => resolve(layer.cwd || layer.config.rootDir || "")).filter((layerDir) => layerDir && layerDir !== resolve(nuxt.options.rootDir))
-      ));
-      for (const layerDirectory of layerDirectories) {
-        addInstalledPackage(await discoverInstalledPackageFromDirectory(layerDirectory));
-      }
-      const localPackageSkills = await discoverLocalPackageSkills(nuxt.options.rootDir);
-      if (localPackageSkills) {
-        discoveries.push(localPackageSkills);
-      }
-      const discoveredContributions = await resolveContributions(discoveries);
-      const distResolvedPackages = new Set(discoveredContributions.contributions.map((item) => item.packageName));
-      const remoteIssues = [];
-      const remoteSkipped = [];
-      const remoteContributions = [];
-      const remoteCacheRoot = join(nuxt.options.rootDir, ".nuxt", "skill-hub-cache");
-      await emptyDir(remoteCacheRoot);
-      const packagesToResolve = installedPackages.filter((pkg) => pkg.packageName !== "nuxt-skill-hub" && !distResolvedPackages.has(pkg.packageName));
-      const totalToResolve = packagesToResolve.length;
-      for (let i = 0; i < packagesToResolve.length; i++) {
-        const pkg = packagesToResolve[i];
-        logger.start(`[${i + 1}/${totalToResolve}] Resolving skills for ${pkg.packageName}...`);
-        const remote = await resolveRemoteContributionsForPackage(pkg, {
-          cacheRoot: remoteCacheRoot,
-          githubLookupTimeoutMs: GITHUB_LOOKUP_TIMEOUT_MS,
-          enableGithubLookup: true
-        });
-        remoteIssues.push(...remote.issues);
-        remoteSkipped.push(...remote.skipped);
-        remoteContributions.push(...remote.contributions);
-      }
-      const validatedRemote = await validateResolvedContributions(sortAndDedupeContributions(remoteContributions));
-      const resolvedManual = await Promise.all(
-        manualContributions.map((contribution) => resolveManualContribution(nuxt.options.rootDir, contribution))
-      );
-      const validatedManual = await validateResolvedContributions(sortAndDedupeContributions(resolvedManual));
-      const contributions = sortAndDedupeContributions([
-        ...discoveredContributions.contributions,
-        ...validatedRemote.contributions,
-        ...validatedManual.contributions
-      ]);
-      const validationIssues = [
-        ...discoveredContributions.issues,
-        ...remoteIssues,
-        ...validatedRemote.issues,
-        ...validatedManual.issues
-      ];
-      const issuesToSkipped = mergeSkipped(
-        validationIssues.map((i) => ({ packageName: i.packageName, skillName: i.skillName, reason: i.reason, sourceKind: i.sourceKind })),
-        (e) => `${e.packageName}::${e.skillName}`
-      );
-      const skipped = mergeSkipped(
-        [...issuesToSkipped, ...remoteSkipped],
-        (e) => `${e.packageName}::${e.skillName}::${e.sourceKind || ""}`
-      );
-      for (const issue of validationIssues) {
-        logger.warn(`[validation] ${issue.packageName}/${issue.skillName}: ${issue.reason}`);
-      }
-      const { targets, invalidTargets } = resolveTargets(options.targets || []);
-      for (const invalidTarget of invalidTargets) {
-        if (invalidTarget.reason === "unknown-target") {
-          logger.warn(`Target "${invalidTarget.target}" is unknown in unagent and was skipped.`);
-          continue;
-        }
-        logger.warn(`Target "${invalidTarget.target}" has no skillsDir in unagent and was skipped.`);
-      }
-      if (!targets.length) {
-        logger.warn("No detected targets. Set skillHub.targets to force generation for specific agents.");
-        return;
-      }
-      for (const conflict of detectConflictingSkills(targets, resolvedSkillName)) {
-        logger.warn(formatConflictWarning(conflict));
-      }
-      const nuxtMetadata = await loadNuxtMetadata();
-      for (let targetIdx = 0; targetIdx < targets.length; targetIdx++) {
-        const target = targets[targetIdx];
-        const { skillRoot } = getTargetSkillRoot(exportRoot, target, resolvedSkillName);
-        const referencesRoot = join(skillRoot, "references");
-        const nuxtRoot = join(referencesRoot, "nuxt");
-        const vueRoot = join(referencesRoot, "vue");
-        const modulesRoot = join(referencesRoot, "modules");
-        await emptyDir(skillRoot);
-        await ensureDir(nuxtRoot);
-        await ensureDir(vueRoot);
-        await ensureDir(modulesRoot);
-        const nuxtTemplateFiles = await buildNuxtTemplateFiles(nuxtRoot);
-        for (const file of nuxtTemplateFiles) {
-          await writeFileIfChanged(file.path, file.contents);
-        }
-        const nuxtIndexTemplatePath = join(nuxtRoot, "index.template.md");
-        const nuxtIndexTemplate = await pathExists(nuxtIndexTemplatePath) ? await promises.readFile(nuxtIndexTemplatePath, "utf8") : "";
-        const nuxtIndexContent = await renderAutomdTemplate(nuxtIndexTemplate, nuxtRoot);
-        await writeFileIfChanged(join(nuxtRoot, "index.md"), nuxtIndexContent);
-        if (targetIdx === 0)
-          logger.start("Fetching Vue best-practices content...");
-        const vueTemplateFiles = await buildVueTemplateFiles(vueRoot, remoteCacheRoot);
-        for (const file of vueTemplateFiles) {
-          await writeFileIfChanged(file.path, file.contents);
-        }
-        const generatedEntries = [];
-        for (const contribution of contributions) {
-          const includeScripts = contribution.forceIncludeScripts;
-          const destination = createModuleDestination(modulesRoot, contribution);
-          await copySkillTree(contribution.sourceDir, destination, includeScripts);
-          const entryPath = relative(skillRoot, join(destination, "SKILL.md"));
-          generatedEntries.push({
-            packageName: contribution.packageName,
-            version: contribution.version,
-            skillName: contribution.skillName,
-            entryPath,
-            sourceDir: contribution.sourceDir,
-            destination: relative(skillRoot, destination),
-            scriptsIncluded: includeScripts,
-            description: contribution.description,
-            sourceKind: contribution.sourceKind,
-            sourceLabel: getSourceLabel(contribution.sourceKind),
-            sourceRepo: contribution.sourceRepo,
-            sourceRef: contribution.sourceRef,
-            sourcePath: contribution.sourcePath,
-            repoUrl: contribution.repoUrl,
-            docsUrl: contribution.docsUrl,
-            official: contribution.official,
-            trustLevel: getTrustLevel(contribution.official),
-            resolver: contribution.resolver
-          });
-        }
-        await writeFileIfChanged(join(skillRoot, "SKILL.md"), createSkillEntrypoint(
-          resolvedSkillName,
-          nuxtMetadata,
-          monorepoScopePath,
-          Boolean(options.moduleAuthoring),
-          generatedEntries,
-          skipped
-        ));
-        logger.success(`Generated ${resolvedSkillName} skill at ${skillRoot}`);
+    const exportRoot = await resolveExportRoot(nuxt.options.rootDir);
+    const rawGenerationMode = options.generationMode;
+    const generationMode = normalizeGenerationMode(rawGenerationMode);
+    const { targets, invalidTargets } = resolveTargets(options.targets || []);
+    if (rawGenerationMode && rawGenerationMode !== generationMode) {
+      logger.warn(`Invalid skillHub.generationMode "${rawGenerationMode}". Falling back to "prepare".`);
+    }
+    for (const invalidTarget of invalidTargets) {
+      if (invalidTarget.reason === "unknown-target") {
+        logger.warn(`Target "${invalidTarget.target}" is unknown in unagent and was skipped.`);
+        continue;
       }
+      logger.warn(`Target "${invalidTarget.target}" has no skillsDir in unagent and was skipped.`);
+    }
+    if (!targets.length) {
+      logger.warn("No detected targets. Set skillHub.targets to force generation for specific agents.");
+      return;
+    }
+    await ensureStableSkillWrappers({
+      rootDir: nuxt.options.rootDir,
+      exportRoot,
+      buildDir: nuxt.options.buildDir,
+      skillName: resolvedSkillName,
+      targets,
+      generationMode
     });
+    for (const conflict of detectConflictingSkills(targets, resolvedSkillName)) {
+      logger.warn(formatConflictWarning(conflict));
+    }
+    if (generationMode === "manual") {
+      return;
+    }
+    const runGeneration = async () => {
+      await generateSkillTree({
+        nuxt,
+        logger,
+        options,
+        skillName: resolvedSkillName,
+        exportRoot,
+        generationMode
+      });
+    };
+    if (generationMode !== "prepare" || !nuxt.options._prepare) {
+      return;
+    }
+    nuxt.hook("prepare:types", runGeneration);
   }
 });