nuxt-skill-hub 0.0.8 → 0.1.0

package/README.md

@@ -22,10 +22,20 @@
 
 ## Install
 
+For agents:
+
+```bash
+npx skills add https://nuxt-skill.onmax.me/
+```
+
+For Nuxt projects:
+
 ```bash
-npx nuxt module add nuxt-skill-hub
+npx nuxi module add nuxt-skill-hub
 ```
 
+Use [Doctor](https://vite-doctor.onmax.me/) to check AI-written Nuxt changes for Nuxt, Vue, Nitro, and Vite issues before review.
+
 ## License
 
 MIT

package/dist/module.d.mts

@@ -3,14 +3,52 @@ import * as _nuxt_schema from '@nuxt/schema';
 type SkillHubTarget = string;
 
 type SkillSourceKind = 'dist' | 'github' | 'wellKnown' | 'generated';
-type SkillResolverKind = 'agentsField' | 'githubHeuristic' | 'wellKnownV2' | 'metadataRouter';
+type SkillResolverKind = 'agentsField' | 'githubHeuristic' | 'wellKnownV2' | 'wellKnownSkills' | 'metadataRouter';
 
 type SkillHubGenerationMode = 'prepare' | 'manual';
+interface SkillHubRemoteOptions {
+    enabled?: boolean;
+    timeoutMs?: number;
+    concurrency?: number;
+    refresh?: boolean;
+    cacheTtlMs?: number;
+    githubHeuristics?: boolean;
+    timings?: boolean;
+    maxFiles?: number;
+    maxBytes?: number;
+    maxFileBytes?: number;
+}
+interface SkillHubResolveStartContext {
+    skillName: string;
+    packageCount: number;
+    concurrency: number;
+    remoteEnabled: boolean;
+    githubHeuristics: boolean;
+}
+interface SkillHubResolvePackageContext {
+    skillName: string;
+    packageName: string;
+    packageIndex: number;
+    packageCount: number;
+    durationMs: number;
+    resolver?: SkillResolverKind;
+    sourceKind?: SkillSourceKind;
+    contributionCount: number;
+    skippedCount: number;
+}
+interface SkillHubResolveDoneContext extends SkillHubResolveStartContext {
+    durationMs: number;
+    contributionCount: number;
+    skippedCount: number;
+    issueCount: number;
+    resolverCounts: Partial<Record<SkillResolverKind, number>>;
+}
 interface ModuleOptions {
     skillName?: string;
     targets?: SkillHubTarget[];
     moduleAuthoring?: boolean;
     generationMode?: SkillHubGenerationMode;
+    remote?: boolean | SkillHubRemoteOptions;
     /**
      * Auto-register ESLint rule to remove redundant imports when @nuxt/eslint is installed.
      * @default true
@@ -42,6 +80,9 @@ declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, fa
 declare module '@nuxt/schema' {
     interface NuxtHooks {
         'skill-hub:contribute': (ctx: SkillHubContributionContext) => void | Promise<void>;
+        'skill-hub:resolve:start': (ctx: SkillHubResolveStartContext) => void | Promise<void>;
+        'skill-hub:resolve:package': (ctx: SkillHubResolvePackageContext) => void | Promise<void>;
+        'skill-hub:resolve:done': (ctx: SkillHubResolveDoneContext) => void | Promise<void>;
     }
 }
 

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-skill-hub",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "configKey": "skillHub",
   "compatibility": {
     "nuxt": ">=4.3.0"

package/dist/module.mjs

@@ -1,6 +1,7 @@
 import { useLogger, defineNuxtModule } from '@nuxt/kit';
 import { isAgent, agent, isCI, isTest } from 'std-env';
 import { promises, existsSync, lstatSync, writeFileSync, readFileSync } from 'node:fs';
+import { performance } from 'node:perf_hooks';
 import { join, basename, resolve, dirname, relative, isAbsolute } from 'pathe';
 import { fileURLToPath } from 'mlly';
 import { homedir } from 'node:os';
@@ -17,7 +18,7 @@ import { glob } from 'tinyglobby';
 import { createConsola } from 'consola';
 import { colorize } from 'consola/utils';
 
-const version = "0.0.8";
+const version = "0.1.0";
 const packageJson = {
 	version: version};
 
@@ -178,14 +179,14 @@ function resolveMetadataRouterSkillName(packageName) {
 }
 function createMetadataRouterSkillFiles(input) {
   const description = input.description?.trim() || `Metadata-routed module skill for ${input.packageName}. Use it to reach the official docs and upstream source.`;
-  const linkLines = createCompactMetadataRouterContent(input).trim();
+  const body = createMetadataRouterContent(input).trim();
   return {
     "SKILL.md": `---
 name: ${yamlString(input.skillName)}
 description: ${yamlString(description)}
 ---
 
-${linkLines || "Docs: unavailable\nSource code: unavailable"}
+${body}
 `
   };
 }
@@ -245,6 +246,43 @@ function renderSkippedEntries(skipped) {
 ${lines.join("\n")}
 `;
 }
+function renderModuleSummary(entries, skipped) {
+  if (!hasModuleGuidance(entries, skipped)) {
+    return "";
+  }
+  const grouped = groupModuleEntries(entries);
+  const counts = [
+    ["installed", grouped.officialUpstream.length],
+    ["resolved", grouped.githubResolved.length],
+    ["docs-discovered", grouped.wellKnownResolved.length],
+    ["metadata-routed", grouped.metadataRouted.length],
+    ["skipped", skipped.length]
+  ];
+  const coverage = counts.filter(([, count]) => count > 0).map(([label, count]) => `${count} ${label}`).join(", ");
+  return `## Module guides
+Module guidance exists for installed packages. Keep it scoped to module-owned APIs, config, runtime behavior, plugins, composables, components, hooks, and owned files.
+
+- Inventory: [Module guide index](./references/modules/index.md)
+- Coverage: ${coverage || "none"}`;
+}
+function createModuleIndex(entries, skipped = []) {
+  if (!hasModuleGuidance(entries, skipped)) {
+    return "";
+  }
+  const grouped = groupModuleEntries(entries);
+  const moduleSections = [
+    renderModuleGroup("Official upstream skills", grouped.officialUpstream, "./"),
+    renderModuleGroup("Resolved module skills", grouped.githubResolved, "./"),
+    renderModuleGroup("Docs-discovered skills", grouped.wellKnownResolved, "./"),
+    renderModuleGroup("Metadata-routed skills", grouped.metadataRouted, "./"),
+    renderSkippedEntries(skipped)
+  ].filter(Boolean);
+  return `# Module Guide Index
+
+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.
+
+${moduleSections.join("\n")}`;
+}
 function findPack(metadata, id) {
   return metadata.packs.find((pack) => pack.id === id) || metadata.packs[0];
 }
@@ -329,25 +367,12 @@ function createRoutingExamples(metadata, includeModuleAuthoring = false) {
 ${lines.join("\n")}`;
 }
 function createSkillMapSections(metadata, entries, skipped = [], includeModuleAuthoring = false) {
-  const includeModuleSections = hasModuleGuidance(entries, skipped);
-  const grouped = groupModuleEntries(entries);
-  const moduleSections = [
-    renderModuleGroup("Official upstream skills", grouped.officialUpstream, "./references/modules/"),
-    renderModuleGroup("Resolved module skills", grouped.githubResolved, "./references/modules/"),
-    renderModuleGroup("Docs-discovered skills", grouped.wellKnownResolved, "./references/modules/"),
-    renderModuleGroup("Metadata-routed skills", grouped.metadataRouted, "./references/modules/"),
-    renderSkippedEntries(skipped)
-  ].filter(Boolean);
-  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.
-
-${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
+    renderModuleSummary(entries, skipped)
   ].filter(Boolean).join("\n\n");
 }
 function createSkillEntrypoint(skillName, metadata, monorepoScopePath, includeModuleAuthoring = false, entries = [], skipped = []) {
@@ -426,6 +451,23 @@ function createCompactMetadataRouterContent(entry) {
   })}
 `;
 }
+function createMetadataRouterContent(entry) {
+  const links = createCompactMetadataRouterContent(entry).trim();
+  const sourceSection = links || "Docs: unavailable\n\nSource code: unavailable";
+  return `# ${entry.packageName} Module Router
+
+Use this module router only when the task directly involves \`${entry.packageName}\` APIs, config, runtime behavior, plugins, composables, components, hooks, or owned files.
+
+## Source of truth
+${sourceSection}
+
+## Context rules
+1. Start with the relevant route in the parent Nuxt skill before using this module router.
+2. Use the docs link for exact APIs, options, and examples instead of guessing from generic Nuxt or Vue patterns.
+3. Use the source link when behavior is version-sensitive or the docs are ambiguous.
+4. Keep this module guidance scoped to \`${entry.packageName}\`; do not replace broader Nuxt rules outside module-owned surfaces.
+`;
+}
 
 async function loadSkillFilesFromDir(dir, skip) {
   const skipSet = skip ? new Set(skip) : void 0;
@@ -739,6 +781,22 @@ function readRepositoryUrl(repository) {
   if (repository && typeof repository.url === "string") return repository.url;
   return void 0;
 }
+function readUrlValues(value) {
+  if (Array.isArray(value)) {
+    return value.flatMap(readUrlValues);
+  }
+  if (typeof value === "string" && value.trim()) {
+    return [value.trim()];
+  }
+  if (value && typeof value === "object" && "url" in value) {
+    const url = value.url;
+    return typeof url === "string" && url.trim() ? [url.trim()] : [];
+  }
+  return [];
+}
+function dedupe$1(values) {
+  return [...new Set(values.filter((value) => Boolean(value)))];
+}
 async function discoverInstalledPackageFromSpecifier(specifier, rootDir) {
   if (!isPackageSpecifier(specifier)) {
     return null;
@@ -778,6 +836,11 @@ async function collectInstalledModulePackages(modules, rootDir) {
 }
 async function readInstalledPackageMetadata(packageJsonPath, fallbackSpecifier) {
   const pkg = await readPackageJSON(packageJsonPath);
+  const docsUrls = dedupe$1([
+    ...readUrlValues(pkg.docs),
+    ...readUrlValues(pkg.documentation),
+    ...readUrlValues(pkg.homepage)
+  ]);
   return {
     packageName: pkg.name || (fallbackSpecifier ? packageNameFromSpecifier(fallbackSpecifier) : basename(dirname(packageJsonPath))),
     version: pkg.version,
@@ -785,6 +848,7 @@ async function readInstalledPackageMetadata(packageJsonPath, fallbackSpecifier)
     packageRoot: dirname(packageJsonPath),
     repository: readRepositoryUrl(pkg.repository),
     homepage: pkg.homepage,
+    docsUrls,
     packageData: pkg
   };
 }
@@ -1287,8 +1351,54 @@ async function fetchUrlBytes(url, timeoutMs) {
   });
 }
 
+const DEFAULT_SKILL_HUB_GENERATION_MODE = "prepare";
+const DEFAULT_REMOTE_TIMEOUT_MS = 1500;
+const DEFAULT_REMOTE_CACHE_TTL_MS = 1e3 * 60 * 60 * 24;
+const DEFAULT_REMOTE_CONCURRENCY = 8;
+const DEFAULT_WELL_KNOWN_MAX_FILES = 40;
+const DEFAULT_WELL_KNOWN_MAX_BYTES = 512 * 1024;
+const DEFAULT_WELL_KNOWN_MAX_FILE_BYTES = 128 * 1024;
+function normalizeGenerationMode(value) {
+  return value === "manual" ? "manual" : DEFAULT_SKILL_HUB_GENERATION_MODE;
+}
+function positiveNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function nonNegativeNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function positiveInteger(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+function normalizeRemoteOptions(value) {
+  const options = typeof value === "object" && value ? value : {};
+  const enabled = typeof value === "boolean" ? value : options.enabled !== false;
+  return {
+    enabled,
+    timeoutMs: positiveNumber(options.timeoutMs, DEFAULT_REMOTE_TIMEOUT_MS),
+    concurrency: positiveInteger(options.concurrency, DEFAULT_REMOTE_CONCURRENCY),
+    refresh: options.refresh === true,
+    cacheTtlMs: nonNegativeNumber(options.cacheTtlMs, DEFAULT_REMOTE_CACHE_TTL_MS),
+    githubHeuristics: options.githubHeuristics === true,
+    timings: options.timings === true,
+    maxFiles: positiveNumber(options.maxFiles, DEFAULT_WELL_KNOWN_MAX_FILES),
+    maxBytes: positiveNumber(options.maxBytes, DEFAULT_WELL_KNOWN_MAX_BYTES),
+    maxFileBytes: positiveNumber(options.maxFileBytes, DEFAULT_WELL_KNOWN_MAX_FILE_BYTES)
+  };
+}
+
 const WELL_KNOWN_DISCOVERY_V2_SCHEMA = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
 const WELL_KNOWN_DISCOVERY_V2_INDEX_PATH = "/.well-known/agent-skills/index.json";
+const WELL_KNOWN_SKILLS_INDEX_PATH = "/.well-known/skills/index.json";
+const WELL_KNOWN_ENTRY_CONCURRENCY = 4;
+const WELL_KNOWN_FILE_CONCURRENCY = 8;
+function normalizeLimits(limits = {}) {
+  return {
+    maxFiles: typeof limits.maxFiles === "number" && Number.isFinite(limits.maxFiles) && limits.maxFiles > 0 ? limits.maxFiles : DEFAULT_WELL_KNOWN_MAX_FILES,
+    maxBytes: typeof limits.maxBytes === "number" && Number.isFinite(limits.maxBytes) && limits.maxBytes > 0 ? limits.maxBytes : DEFAULT_WELL_KNOWN_MAX_BYTES,
+    maxFileBytes: typeof limits.maxFileBytes === "number" && Number.isFinite(limits.maxFileBytes) && limits.maxFileBytes > 0 ? limits.maxFileBytes : DEFAULT_WELL_KNOWN_MAX_FILE_BYTES
+  };
+}
 function makeSkip$1(packageName, skillName, reason) {
   return {
     packageName,
@@ -1387,6 +1497,7 @@ function docsBaseCandidates(packageInfo) {
   const override = findPackageOverride(packageInfo.packageName);
   const candidates = [
     ...override?.docsUrls || [],
+    ...packageInfo.docsUrls || [],
     packageInfo.homepage || ""
   ];
   return [...new Set(candidates.map(normalizeHttpUrl$1).filter((url) => Boolean(url)).filter(isPublicDiscoveryBase))];
@@ -1401,6 +1512,23 @@ function normalizeDigest(value) {
 function sha256(bytes) {
   return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
 }
+function normalizeSkillFilePath(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim().replaceAll("\\", "/");
+  if (!trimmed || trimmed.startsWith("/") || trimmed.includes("\0")) {
+    return null;
+  }
+  const segments = trimmed.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+    return null;
+  }
+  return trimmed;
+}
+function isSupportedSkillContextFile(path) {
+  return path === "SKILL.md" || path.endsWith(".md") || path.endsWith(".json");
+}
 async function writeSkillFile(root, relativePath, bytes) {
   const destination = join(root, relativePath);
   await ensureDir(dirname(destination));
@@ -1411,6 +1539,7 @@ function contributionFor(input) {
   return normalizeContribution({
     packageName: input.packageInfo.packageName,
     version: input.packageInfo.version,
+    sourceDir: input.targetDir,
     skillName: input.skillName,
     description: input.description,
     sourceKind: "wellKnown",
@@ -1423,6 +1552,90 @@ function contributionFor(input) {
     forceIncludeScripts: true
   }, input.targetDir, join(input.targetDir, ".."));
 }
+async function materializeSkillsIndexEntry(input) {
+  const skillName = typeof input.entry.name === "string" ? input.entry.name.trim() : "";
+  if (!isValidSkillName(skillName)) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName || "entry", "well-known skill name is invalid") };
+  }
+  const description = typeof input.entry.description === "string" ? input.entry.description.trim() : "";
+  if (!description) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill is missing a description") };
+  }
+  if (!Array.isArray(input.entry.files)) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill is missing a files array") };
+  }
+  const files = [...new Set(input.entry.files.map(normalizeSkillFilePath).filter((file) => Boolean(file)))];
+  if (!files.includes("SKILL.md")) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill must list SKILL.md") };
+  }
+  if (files.length !== input.entry.files.length) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill includes an unsafe file path") };
+  }
+  if (files.some((file) => !isSupportedSkillContextFile(file))) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill includes a non-context file; only .md and .json files are supported") };
+  }
+  if (files.length > input.limits.maxFiles) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `well-known skill lists ${files.length} files, exceeding the limit of ${input.limits.maxFiles}`) };
+  }
+  const origin = new URL(input.docsUrl).origin;
+  const targetDir = join(
+    input.cacheRoot,
+    "well-known",
+    "skills",
+    sanitizeSegment(origin),
+    sanitizeSegment(input.packageInfo.packageName),
+    sanitizeSegment(input.packageInfo.version || "unknown"),
+    sanitizeSegment(skillName)
+  );
+  const fileUrls = files.map((file) => {
+    const fileUrl = resolveSameOriginUrl(`${skillName}/${file}`, new URL("./", input.indexUrl).toString());
+    if (!fileUrl) {
+      return null;
+    }
+    return { file, fileUrl };
+  });
+  if (fileUrls.includes(null)) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill file URL must stay on the discovery origin") };
+  }
+  const fetchedFiles = [];
+  let totalBytes = 0;
+  const responses = await mapWithConcurrency(
+    fileUrls,
+    WELL_KNOWN_FILE_CONCURRENCY,
+    async ({ file, fileUrl }) => ({
+      file,
+      response: await fetchUrlBytes(fileUrl, input.timeoutMs)
+    })
+  );
+  for (const { file, response } of responses) {
+    if (!response.ok || !response.data) {
+      return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `failed to fetch well-known skill file ${file}`) };
+    }
+    if (response.data.byteLength > input.limits.maxFileBytes) {
+      return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `well-known skill file ${file} exceeds the per-file limit of ${input.limits.maxFileBytes} bytes`) };
+    }
+    totalBytes += response.data.byteLength;
+    if (totalBytes > input.limits.maxBytes) {
+      return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `well-known skill files exceed the total limit of ${input.limits.maxBytes} bytes`) };
+    }
+    fetchedFiles.push({ path: file, bytes: response.data });
+  }
+  await emptyDir(targetDir);
+  for (const file of fetchedFiles) {
+    await writeSkillFile(targetDir, file.path, file.bytes);
+  }
+  return {
+    contribution: contributionFor({
+      packageInfo: input.packageInfo,
+      targetDir,
+      skillName,
+      description,
+      docsUrl: input.docsUrl,
+      resolver: "wellKnownSkills",
+      indexUrl: input.indexUrl
+    })
+  };
+}
 async function materializeV2Skill(input) {
   const skillName = typeof input.entry.name === "string" ? input.entry.name.trim() : "";
   if (!isValidSkillName(skillName)) {
@@ -1457,6 +1670,9 @@ async function materializeV2Skill(input) {
   if (sha256(response.data) !== digest) {
     return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill digest mismatch") };
   }
+  if (response.data.byteLength > input.limits.maxFileBytes || response.data.byteLength > input.limits.maxBytes) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `well-known v2 skill exceeds the file size limit of ${Math.min(input.limits.maxFileBytes, input.limits.maxBytes)} bytes`) };
+  }
   const origin = new URL(input.docsUrl).origin;
   const targetDir = join(
     input.cacheRoot,
@@ -1481,6 +1697,44 @@ async function materializeV2Skill(input) {
     })
   };
 }
+async function resolveSkillsIndex(input) {
+  const skipped = [];
+  const contributions = [];
+  if (!Array.isArray(input.index.skills)) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known skills index is missing a skills array")]
+    };
+  }
+  const materializedEntries = await mapWithConcurrency(
+    input.index.skills,
+    WELL_KNOWN_ENTRY_CONCURRENCY,
+    async (rawEntry) => {
+      if (!rawEntry || typeof rawEntry !== "object") {
+        return { skipped: makeSkip$1(input.packageInfo.packageName, "entry", "well-known skill entry must be an object") };
+      }
+      return await materializeSkillsIndexEntry({
+        packageInfo: input.packageInfo,
+        entry: rawEntry,
+        indexUrl: input.indexUrl,
+        docsUrl: input.docsUrl,
+        cacheRoot: input.cacheRoot,
+        timeoutMs: input.timeoutMs,
+        limits: input.limits
+      });
+    }
+  );
+  for (const materialized of materializedEntries) {
+    if (materialized?.contribution) {
+      contributions.push(materialized.contribution);
+    }
+    if (materialized?.skipped) {
+      skipped.push(materialized.skipped);
+    }
+  }
+  return { contributions, issues: [], skipped };
+}
 async function resolveV2Index(input) {
   const skipped = [];
   const contributions = [];
@@ -1491,19 +1745,25 @@ async function resolveV2Index(input) {
       skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known v2 index is missing a skills array")]
     };
   }
-  for (const rawEntry of input.index.skills) {
-    if (!rawEntry || typeof rawEntry !== "object") {
-      skipped.push(makeSkip$1(input.packageInfo.packageName, "entry", "well-known v2 skill entry must be an object"));
-      continue;
+  const materializedEntries = await mapWithConcurrency(
+    input.index.skills,
+    WELL_KNOWN_ENTRY_CONCURRENCY,
+    async (rawEntry) => {
+      if (!rawEntry || typeof rawEntry !== "object") {
+        return { skipped: makeSkip$1(input.packageInfo.packageName, "entry", "well-known v2 skill entry must be an object") };
+      }
+      return await materializeV2Skill({
+        packageInfo: input.packageInfo,
+        entry: rawEntry,
+        indexUrl: input.indexUrl,
+        docsUrl: input.docsUrl,
+        cacheRoot: input.cacheRoot,
+        timeoutMs: input.timeoutMs,
+        limits: input.limits
+      });
     }
-    const materialized = await materializeV2Skill({
-      packageInfo: input.packageInfo,
-      entry: rawEntry,
-      indexUrl: input.indexUrl,
-      docsUrl: input.docsUrl,
-      cacheRoot: input.cacheRoot,
-      timeoutMs: input.timeoutMs
-    });
+  );
+  for (const materialized of materializedEntries) {
     if (materialized?.contribution) {
       contributions.push(materialized.contribution);
     }
@@ -1539,6 +1799,12 @@ async function resolveIndex(input) {
       index
     });
   }
+  if (new URL(input.indexUrl).pathname === WELL_KNOWN_SKILLS_INDEX_PATH && !index.$schema) {
+    return await resolveSkillsIndex({
+      ...input,
+      index
+    });
+  }
   if (typeof index.$schema === "string" && index.$schema) {
     return {
       contributions: [],
@@ -1552,19 +1818,30 @@ async function resolveIndex(input) {
     skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known index is missing the v2 schema")]
   };
 }
-async function resolveViaWellKnown(packageInfo, cacheRoot, timeoutMs) {
+async function resolveViaWellKnown(packageInfo, cacheRoot, timeoutMs, rawLimits) {
   const bases = docsBaseCandidates(packageInfo);
   const skipped = [];
   const issues = [];
-  for (const docsUrl of bases) {
-    const indexUrl = new URL(WELL_KNOWN_DISCOVERY_V2_INDEX_PATH, docsUrl).toString();
-    const result = await resolveIndex({
-      packageInfo,
-      indexUrl,
-      docsUrl,
-      cacheRoot,
-      timeoutMs
-    });
+  const limits = normalizeLimits(rawLimits);
+  const attempts = bases.flatMap((docsUrl) => {
+    return [
+      new URL(WELL_KNOWN_DISCOVERY_V2_INDEX_PATH, docsUrl).toString(),
+      new URL(WELL_KNOWN_SKILLS_INDEX_PATH, docsUrl).toString()
+    ].map((indexUrl) => ({ docsUrl, indexUrl }));
+  });
+  const results = await Promise.all(
+    attempts.map(async ({ docsUrl, indexUrl }) => ({
+      result: await resolveIndex({
+        packageInfo,
+        indexUrl,
+        docsUrl,
+        cacheRoot,
+        timeoutMs,
+        limits
+      })
+    }))
+  );
+  for (const { result } of results) {
     if (!result) {
       continue;
     }
@@ -1636,7 +1913,8 @@ function normalizeHttpUrl(url) {
 function resolveDocsUrl(packageInfo) {
   const override = findPackageOverride(packageInfo.packageName);
   const overrideDocsUrl = override?.docsUrls?.map(normalizeHttpUrl).find(Boolean);
-  return overrideDocsUrl || normalizeHttpUrl(packageInfo.homepage);
+  const packageDocsUrl = packageInfo.docsUrls?.map(normalizeHttpUrl).find(Boolean);
+  return overrideDocsUrl || packageDocsUrl || normalizeHttpUrl(packageInfo.homepage);
 }
 function resolveRepositoryUrl(packageInfo) {
   const override = findPackageOverride(packageInfo.packageName);
@@ -1952,15 +2230,23 @@ async function resolveViaMetadataRouter(packageInfo, cacheRoot) {
   };
 }
 async function resolveRemoteContributionsForPackage(packageInfo, options) {
-  const githubAgentsResult = options.enableGithubLookup ? await resolveViaGitHubAgents(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
+  const githubAgentsPromise = options.enableGithubLookup ? resolveViaGitHubAgents(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
     contributions: [],
     issues: [],
     skipped: []
   };
+  const wellKnownPromise = options.enableWellKnownLookup === false ? {
+    contributions: [],
+    issues: [],
+    skipped: []
+  } : resolveViaWellKnown(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs, options.wellKnownLimits);
+  const [githubAgentsResult, wellKnownResult] = await Promise.all([
+    githubAgentsPromise,
+    wellKnownPromise
+  ]);
   if (githubAgentsResult.contributions.length) {
     return githubAgentsResult;
   }
-  const wellKnownResult = await resolveViaWellKnown(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs);
   if (wellKnownResult.contributions.length) {
     return {
       contributions: wellKnownResult.contributions,
@@ -1968,7 +2254,7 @@ async function resolveRemoteContributionsForPackage(packageInfo, options) {
       skipped: wellKnownResult.skipped
     };
   }
-  const githubHeuristicResult = options.enableGithubLookup ? await resolveViaGitHubHeuristics(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
+  const githubHeuristicResult = options.enableGithubLookup && options.enableGithubHeuristics ? await resolveViaGitHubHeuristics(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
     contributions: [],
     issues: [],
     skipped: []
@@ -1995,11 +2281,6 @@ async function resolveRemoteContributionsForPackage(packageInfo, options) {
   };
 }
 
-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 {
@@ -2036,7 +2317,8 @@ async function createGenerationFingerprint(input) {
       skillName: input.options.skillName?.trim() || null,
       targets: [...input.options.targets || []].sort(),
       moduleAuthoring: Boolean(input.options.moduleAuthoring),
-      generationMode: normalizeGenerationMode(input.options.generationMode)
+      generationMode: normalizeGenerationMode(input.options.generationMode),
+      remote: normalizeRemoteOptions(input.options.remote)
     }
   });
 }
@@ -2150,16 +2432,29 @@ async function writeGenerationState(generatedSkillRoot, fingerprint) {
   await writeFileIfChanged(getGenerationStatePath(generatedSkillRoot), `${JSON.stringify(state, null, 2)}
 `);
 }
-async function isGeneratedSkillFresh(generatedSkillRoot, fingerprint) {
+async function isGeneratedSkillFreshWithOptions(generatedSkillRoot, fingerprint, options = {}) {
+  if (options.refresh) {
+    return false;
+  }
   const [state, entryExists] = await Promise.all([
     readGenerationState(generatedSkillRoot),
     pathExists(join(generatedSkillRoot, "SKILL.md"))
   ]);
-  return Boolean(entryExists && state?.fingerprint === fingerprint);
+  if (!entryExists || state?.fingerprint !== fingerprint) {
+    return false;
+  }
+  if (typeof options.cacheTtlMs === "number" && Number.isFinite(options.cacheTtlMs)) {
+    if (options.cacheTtlMs <= 0) {
+      return false;
+    }
+    const generatedAt = Date.parse(state.generatedAt);
+    if (!Number.isFinite(generatedAt) || Date.now() - generatedAt > options.cacheTtlMs) {
+      return false;
+    }
+  }
+  return true;
 }
 
-const GITHUB_LOOKUP_TIMEOUT_MS = 1500;
-const REMOTE_RESOLUTION_CONCURRENCY = 4;
 function resolveStableSkillBuildDir(rootDir, buildDir) {
   const rel = relative(resolve(rootDir), resolve(buildDir)).replaceAll("\\", "/");
   if (rel === ".nuxt" || rel.startsWith(".nuxt/")) {
@@ -2183,6 +2478,31 @@ function getPersistentCacheRoot(exportRoot) {
 function getCachedGeneratedSkillRoot(cacheRoot, skillName) {
   return join(cacheRoot, "generated", skillName);
 }
+function roundMs(value) {
+  return Math.round(value * 10) / 10;
+}
+function formatMs(value) {
+  return value >= 1e3 ? `${(value / 1e3).toFixed(1)}s` : `${Math.round(value)}ms`;
+}
+function shouldLogTimings(nuxt, explicit) {
+  return explicit || Boolean(nuxt.options.debug);
+}
+function startPerfPhase(nuxt, name) {
+  nuxt._perf?.startPhase(name);
+}
+function endPerfPhase(nuxt, name) {
+  nuxt._perf?.endPhase(name);
+}
+function countResolvers(contributions) {
+  const counts = {};
+  for (const contribution of contributions) {
+    counts[contribution.resolver] = (counts[contribution.resolver] || 0) + 1;
+  }
+  return counts;
+}
+function formatResolverCounts(counts) {
+  return Object.entries(counts).map(([resolver, count]) => `${count} ${resolver}`).join(", ");
+}
 function mergeSkipped(entries, keyFn) {
   const byKey = /* @__PURE__ */ new Map();
   for (const entry of entries) {
@@ -2198,6 +2518,10 @@ function mergeSkipped(entries, keyFn) {
   }
   return Array.from(byKey.values()).sort((a, b) => `${a.packageName}::${a.skillName}`.localeCompare(`${b.packageName}::${b.skillName}`));
 }
+function filterResolvedSkipped(entries, contributions) {
+  const resolvedKeys = new Set(contributions.map((contribution) => `${contribution.packageName}::${contribution.skillName}`));
+  return entries.filter((entry) => !resolvedKeys.has(`${entry.packageName}::${entry.skillName}`));
+}
 async function removeLegacyRootArtifacts(skillRoot) {
   await Promise.all([
     promises.rm(join(skillRoot, "references"), { recursive: true, force: true }),
@@ -2264,6 +2588,7 @@ async function generateSkillTree(input) {
   const modulesRoot = join(referencesRoot, "modules");
   const monorepoScopePath = resolveMonorepoScopePath(nuxt.options.rootDir, exportRoot);
   const manualContributions = [];
+  const remoteOptions = normalizeRemoteOptions(options.remote);
   const contributionContext = {
     add: (contribution) => {
       manualContributions.push(contribution);
@@ -2271,6 +2596,9 @@ async function generateSkillTree(input) {
   };
   const callSkillContributeHook = nuxt.callHook;
   await callSkillContributeHook("skill-hub:contribute", contributionContext);
+  const callResolveStartHook = nuxt.callHook;
+  const callResolvePackageHook = nuxt.callHook;
+  const callResolveDoneHook = nuxt.callHook;
   const { discoveries, installedPackages } = await collectInstalledPackages(nuxt);
   const discoveredContributions = await resolveContributions(discoveries);
   const workspaceDiscoverySources = collectWorkspaceDiscoverySources(nuxt.options.rootDir, discoveries);
@@ -2290,7 +2618,10 @@ async function generateSkillTree(input) {
       ...sortAndDedupeContributions(resolvedManual)
     ])
   });
-  if (generationMode === "prepare" && await isGeneratedSkillFresh(cachedGeneratedSkillRoot, fingerprint)) {
+  if (generationMode === "prepare" && await isGeneratedSkillFreshWithOptions(cachedGeneratedSkillRoot, fingerprint, {
+    refresh: remoteOptions.refresh,
+    cacheTtlMs: remoteOptions.cacheTtlMs
+  })) {
     await copySkillTree(cachedGeneratedSkillRoot, generatedSkillRoot, true);
     logger.info(`Restored cached ${skillName} skill from ${cachedGeneratedSkillRoot}`);
     return;
@@ -2303,23 +2634,89 @@ async function generateSkillTree(input) {
   await ensureDir(remoteCacheRoot);
   const packagesToResolve = installedPackages.filter((pkg) => pkg.packageName !== "nuxt-skill-hub" && !distResolvedPackages.has(pkg.packageName));
   const totalToResolve = packagesToResolve.length;
-  const remoteResults = await mapWithConcurrency(
-    packagesToResolve,
-    REMOTE_RESOLUTION_CONCURRENCY,
-    async (pkg, index) => {
-      logger.start(`Resolving skills for ${pkg.packageName} (${index + 1}/${totalToResolve})...`);
-      return await resolveRemoteContributionsForPackage(pkg, {
-        cacheRoot: remoteCacheRoot,
-        githubLookupTimeoutMs: GITHUB_LOOKUP_TIMEOUT_MS,
-        enableGithubLookup: true
-      });
+  const remoteStart = performance.now();
+  const logTimings = shouldLogTimings(nuxt, remoteOptions.timings);
+  await callResolveStartHook("skill-hub:resolve:start", {
+    skillName,
+    packageCount: totalToResolve,
+    concurrency: remoteOptions.concurrency,
+    remoteEnabled: remoteOptions.enabled,
+    githubHeuristics: remoteOptions.githubHeuristics
+  });
+  startPerfPhase(nuxt, "skill-hub:resolve");
+  const remoteResults = await (async () => {
+    try {
+      return await mapWithConcurrency(
+        packagesToResolve,
+        remoteOptions.concurrency,
+        async (pkg, index) => {
+          logger.start(`Resolving skills for ${pkg.packageName} (${index + 1}/${totalToResolve})...`);
+          const packageStart = performance.now();
+          const phaseName = `skill-hub:resolve:${pkg.packageName}`;
+          startPerfPhase(nuxt, phaseName);
+          try {
+            const result = await resolveRemoteContributionsForPackage(pkg, {
+              cacheRoot: remoteCacheRoot,
+              githubLookupTimeoutMs: remoteOptions.timeoutMs,
+              enableGithubLookup: remoteOptions.enabled,
+              enableWellKnownLookup: remoteOptions.enabled,
+              enableGithubHeuristics: remoteOptions.enabled && remoteOptions.githubHeuristics,
+              wellKnownLimits: {
+                maxFiles: remoteOptions.maxFiles,
+                maxBytes: remoteOptions.maxBytes,
+                maxFileBytes: remoteOptions.maxFileBytes
+              }
+            });
+            const durationMs = roundMs(performance.now() - packageStart);
+            const firstContribution = result.contributions[0];
+            await callResolvePackageHook("skill-hub:resolve:package", {
+              skillName,
+              packageName: pkg.packageName,
+              packageIndex: index,
+              packageCount: totalToResolve,
+              durationMs,
+              resolver: firstContribution?.resolver,
+              sourceKind: firstContribution?.sourceKind,
+              contributionCount: result.contributions.length,
+              skippedCount: result.skipped.length
+            });
+            if (logTimings) {
+              const outcome = firstContribution ? `${firstContribution.resolver}/${firstContribution.sourceKind}` : "unresolved";
+              logger.info(`Resolved ${pkg.packageName} via ${outcome} in ${formatMs(durationMs)}`);
+            }
+            return result;
+          } finally {
+            endPerfPhase(nuxt, phaseName);
+          }
+        }
+      );
+    } finally {
+      endPerfPhase(nuxt, "skill-hub:resolve");
     }
-  );
+  })();
   for (const remote of remoteResults) {
     remoteIssues.push(...remote.issues);
     remoteSkipped.push(...remote.skipped);
     remoteContributions.push(...remote.contributions);
   }
+  const remoteDurationMs = roundMs(performance.now() - remoteStart);
+  const resolverCounts = countResolvers(remoteContributions);
+  await callResolveDoneHook("skill-hub:resolve:done", {
+    skillName,
+    packageCount: totalToResolve,
+    concurrency: remoteOptions.concurrency,
+    remoteEnabled: remoteOptions.enabled,
+    githubHeuristics: remoteOptions.githubHeuristics,
+    durationMs: remoteDurationMs,
+    contributionCount: remoteContributions.length,
+    skippedCount: remoteSkipped.length,
+    issueCount: remoteIssues.length,
+    resolverCounts
+  });
+  if (totalToResolve) {
+    const summary = formatResolverCounts(resolverCounts);
+    logger.info(`Resolved ${totalToResolve} module skill sources in ${formatMs(remoteDurationMs)}${summary ? ` (${summary})` : ""}.`);
+  }
   const validatedRemote = await validateResolvedContributions(sortAndDedupeContributions(remoteContributions));
   const validatedManual = await validateResolvedContributions(sortAndDedupeContributions(resolvedManual));
   const contributions = sortAndDedupeContributions([
@@ -2337,10 +2734,10 @@ async function generateSkillTree(input) {
     validationIssues.map((issue) => ({ packageName: issue.packageName, skillName: issue.skillName, reason: issue.reason, sourceKind: issue.sourceKind })),
     (entry) => `${entry.packageName}::${entry.skillName}`
   );
-  const skipped = mergeSkipped(
+  const skipped = filterResolvedSkipped(mergeSkipped(
     [...issuesToSkipped, ...remoteSkipped],
     (entry) => `${entry.packageName}::${entry.skillName}::${entry.sourceKind || ""}`
-  );
+  ), contributions);
   for (const issue of validationIssues) {
     logger.warn(`[validation] ${issue.packageName}/${issue.skillName}: ${issue.reason}`);
   }
@@ -2388,6 +2785,10 @@ async function generateSkillTree(input) {
       resolver: contribution.resolver
     });
   }
+  const moduleIndex = createModuleIndex(generatedEntries, skipped);
+  if (moduleIndex) {
+    await writeFileIfChanged(join(modulesRoot, "index.md"), moduleIndex);
+  }
   const nuxtMetadata = await loadNuxtMetadata();
   await writeFileIfChanged(join(generatedSkillRoot, "SKILL.md"), createSkillEntrypoint(
     skillName,
@@ -2405,7 +2806,19 @@ async function generateSkillTree(input) {
 function isCancelled(value) {
   return value === null || typeof value === "symbol";
 }
-function buildAIGuidance(currentTarget, detectedAgent) {
+function normalizeTargetSelection(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((entry) => {
+    if (typeof entry === "string") return entry;
+    if (entry && typeof entry === "object" && typeof entry.value === "string") {
+      return entry.value;
+    }
+    return "";
+  }).filter(Boolean);
+}
+function buildAIGuidance(currentTarget, detectedAgent, skillName = "nuxt") {
   const agentTargetMap = {
     codex: "codex",
     claude: "claude-code",
@@ -2414,6 +2827,10 @@ function buildAIGuidance(currentTarget, detectedAgent) {
   };
   const target = currentTarget || (detectedAgent ? agentTargetMap[detectedAgent] : void 0);
   const sourceLabel = detectedAgent ? ` (${detectedAgent})` : "";
+  const hintFile = target === "claude-code" ? "CLAUDE.md" : "AGENTS.md";
+  const hint = `${MANAGED_HINT_START}
+Use the \`${skillName}\` skill as the Nuxt router/entrypoint for tasks in this repository.
+${MANAGED_HINT_END}`;
   const snippetLines = [
     "export default defineNuxtConfig({",
     "  skillHub: {",
@@ -2425,17 +2842,25 @@ function buildAIGuidance(currentTarget, detectedAgent) {
   return {
     intro: `Install wizard skipped because nuxt-skill-hub was installed by an AI agent${sourceLabel}. Add this to your nuxt.config.ts:`,
     snippet: snippetLines.join("\n"),
+    hintFile,
+    hint,
+    nextStep: `Add the managed hint to ${hintFile}, then run \`npx nuxi prepare\` to generate the Nuxt skill tree.`,
     optionalFlags: target ? "Optional flags: set `skillHub.skillName`, enable `skillHub.moduleAuthoring`, or switch to `skillHub.generationMode: 'manual'` if needed." : "Optional flags: add `skillHub.targets` to pin an agent target, set `skillHub.skillName`, enable `skillHub.moduleAuthoring`, or switch to `skillHub.generationMode: 'manual'` if needed."
   };
 }
 async function runInstallWizard(nuxt) {
   const logger = useLogger("nuxt-skill-hub");
   if (isAgent) {
-    const guidance = buildAIGuidance(detectCurrentTarget(), agent);
+    const guidance = buildAIGuidance(detectCurrentTarget(), agent, await deriveSkillName(nuxt.options.rootDir));
     logger.info(guidance.intro);
     logger.info(`\`\`\`ts
 ${guidance.snippet}
 \`\`\``);
+    logger.info(`Add this to ${guidance.hintFile}:
+\`\`\`md
+${guidance.hint}
+\`\`\``);
+    logger.info(guidance.nextStep);
     logger.info(guidance.optionalFlags);
     return;
   }
@@ -2467,6 +2892,20 @@ Let's configure AI agent skills for your Nuxt project.`
     }
     consola.info(`Detected agents: ${detectedTargets.length ? detectedTargets.join(", ") : "none"}`);
     selectedTargets = detectedTargets;
+    if (!selectedTargets.length) {
+      const chosen = await consola.prompt("Select agents to generate skills for:", {
+        type: "multiselect",
+        options: allTargets.map((t) => ({ label: t, value: t })),
+        initial: allTargets.includes("codex") ? ["codex"] : allTargets.slice(0, 1),
+        required: true,
+        cancel: "null"
+      });
+      if (isCancelled(chosen)) {
+        consola.info("Setup cancelled.");
+        return;
+      }
+      selectedTargets = normalizeTargetSelection(chosen);
+    }
     if (detectedTargets.length > 1) {
       const keepAll = await consola.prompt("Generate skills for all detected agents?", {
         type: "confirm",
@@ -2489,7 +2928,7 @@ Let's configure AI agent skills for your Nuxt project.`
           consola.info("Setup cancelled.");
           return;
         }
-        selectedTargets = chosen.map((c) => c.value);
+        selectedTargets = normalizeTargetSelection(chosen);
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-skill-hub",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "description": "Teach your AI agent the Nuxt way with best practices and module guidance.",
   "repository": {
     "type": "git",
@@ -24,37 +24,36 @@
     "nuxt-best-practices"
   ],
   "dependencies": {
-    "@nuxt/kit": "^4.3.1",
+    "@nuxt/kit": "^4.4.6",
     "automd": "^0.4.3",
-    "consola": "^3.4.0",
-    "giget": "^3.1.2",
+    "consola": "^3.4.2",
+    "giget": "^3.2.0",
     "gray-matter": "^4.0.3",
-    "mlly": "^1.8.1",
-    "ofetch": "^1.5.0",
+    "mlly": "^1.8.2",
+    "ofetch": "^1.5.1",
     "ohash": "^2.0.11",
-    "pathe": "^2.0.0",
-    "pkg-types": "^2.3.0",
-    "std-env": "^4.0.0",
-    "tinyglobby": "^0.2.15",
+    "pathe": "^2.0.3",
+    "pkg-types": "^2.3.1",
+    "std-env": "^4.1.0",
+    "tinyglobby": "^0.2.17",
     "unagent": "^0.0.8"
   },
   "devDependencies": {
-    "@nuxt/devtools": "^3.2.1",
-    "@nuxt/eslint-config": "^1.15.1",
+    "@nuxt/devtools": "^3.2.4",
+    "@nuxt/eslint-config": "^1.15.2",
     "@nuxt/module-builder": "^1.0.2",
-    "@nuxt/schema": "^4.3.1",
-    "@nuxt/test-utils": "^4.0.0",
-    "@nuxtjs/mdc": "^0.20.2",
-    "@types/node": "latest",
-    "@vue/test-utils": "^2.4.6",
-    "bumpp": "^10.4.1",
-    "eslint": "^10.0.1",
-    "happy-dom": "^20.7.0",
-    "nuxt": "^4.3.1",
+    "@nuxt/schema": "^4.4.6",
+    "@nuxt/test-utils": "^4.0.3",
+    "@types/node": "^25.9.1",
+    "@vue/test-utils": "^2.4.10",
+    "bumpp": "^11.1.0",
+    "eslint": "^10.4.1",
+    "happy-dom": "^20.9.0",
+    "nuxt": "^4.4.6",
     "typescript": "~5.9.3",
-    "vitest": "^4.0.18",
-    "vue": "^3.5.29",
-    "vue-tsc": "^3.2.5"
+    "vitest": "^4.1.7",
+    "vue": "^3.5.35",
+    "vue-tsc": "^3.3.3"
   },
   "scripts": {
     "dev": "pnpm --dir docs dev",