nuxt-skill-hub 0.0.6 → 0.0.8

package/dist/module.mjs

@@ -1,5 +1,5 @@
 import { useLogger, defineNuxtModule } from '@nuxt/kit';
-import { isCI, isTest } from 'std-env';
+import { isAgent, agent, isCI, isTest } from 'std-env';
 import { promises, existsSync, lstatSync, writeFileSync, readFileSync } from 'node:fs';
 import { join, basename, resolve, dirname, relative, isAbsolute } from 'pathe';
 import { fileURLToPath } from 'mlly';
@@ -8,15 +8,16 @@ import matter from 'gray-matter';
 import { readPackageJSON, findWorkspaceDir, resolvePackageJSON, resolveLockfile } from 'pkg-types';
 import { transform } from 'automd';
 import { downloadTemplate } from 'giget';
-import { detectInstalledAgents, expandPath, detectCurrentAgent, getAgentIds, getAgentConfig } from 'unagent/env';
+import { getAgentConfig, detectInstalledAgents, expandPath, detectCurrentAgent, getAgentIds } from 'unagent/env';
 import { ofetch } from 'ofetch';
 import { createHash } from 'node:crypto';
+import { isIP } from 'node:net';
 import { hash } from 'ohash';
 import { glob } from 'tinyglobby';
 import { createConsola } from 'consola';
 import { colorize } from 'consola/utils';
 
-const version = "0.0.6";
+const version = "0.0.8";
 const packageJson = {
 	version: version};
 
@@ -146,6 +147,8 @@ function getSourceLabel(sourceKind) {
       return "Installed package skill";
     case "github":
       return "Resolved module skill";
+    case "wellKnown":
+      return "Docs-discovered skill";
     case "generated":
       return "Metadata-routed skill";
   }
@@ -206,8 +209,9 @@ function relativeModuleLink(entry, prefix) {
 function groupModuleEntries(entries) {
   const officialUpstream = entries.filter((entry) => entry.sourceKind === "dist");
   const githubResolved = entries.filter((entry) => entry.sourceKind === "github");
+  const wellKnownResolved = entries.filter((entry) => entry.sourceKind === "wellKnown");
   const metadataRouted = entries.filter((entry) => entry.sourceKind === "generated");
-  return { officialUpstream, githubResolved, metadataRouted };
+  return { officialUpstream, githubResolved, wellKnownResolved, metadataRouted };
 }
 function hasModuleGuidance(entries, skipped = []) {
   return entries.length > 0 || skipped.length > 0;
@@ -330,6 +334,7 @@ function createSkillMapSections(metadata, entries, skipped = [], includeModuleAu
   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);
@@ -494,24 +499,15 @@ function resolveSkillsDir(target, config) {
   }
   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));
+  return getAgentIds().filter((target) => Boolean(resolveSkillsDir(target, getAgentConfig(target)))).sort((a, b) => a.localeCompare(b));
 }
 function resolveAgentTargetConfig(target) {
-  const normalized = normalizeTarget(target);
+  const normalized = target.trim();
   if (!normalized) {
     return void 0;
   }
-  const config = getRawTargetConfig(normalized);
+  const config = getAgentConfig(normalized);
   const skillsDir = resolveSkillsDir(normalized, config);
   if (!config || !skillsDir) {
     return void 0;
@@ -523,11 +519,11 @@ function resolveAgentTargetConfig(target) {
   };
 }
 function validateTargets(targets) {
-  const uniqueTargets = Array.from(new Set(targets.map(normalizeTarget).filter(Boolean)));
+  const uniqueTargets = Array.from(new Set(targets.map((target) => target.trim()).filter(Boolean)));
   const valid = [];
   const invalid = [];
   for (const target of uniqueTargets) {
-    const config = getRawTargetConfig(target);
+    const config = getAgentConfig(target);
     if (!config) {
       invalid.push({
         target,
@@ -562,6 +558,24 @@ const MANAGED_HINT_START = "<!-- nuxt-skill-hub:start -->";
 const MANAGED_HINT_END = "<!-- nuxt-skill-hub:end -->";
 const SKILL_NAME_MAX_LENGTH = 64;
 const SKILL_NAME_PATTERN = /^[a-z0-9-]+$/;
+async function mapWithConcurrency(items, concurrency, mapper) {
+  if (!items.length) {
+    return [];
+  }
+  const results = [];
+  let nextIndex = 0;
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (true) {
+      const index = nextIndex++;
+      if (index >= items.length) {
+        return;
+      }
+      results[index] = await mapper(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
 async function pathExists(path) {
   try {
     await promises.access(path);
@@ -746,6 +760,22 @@ async function discoverInstalledPackageFromDirectory(directory) {
   }
   return readInstalledPackageMetadata(packageJsonPath);
 }
+async function collectInstalledModulePackages(modules, rootDir) {
+  const specifiers = Array.from(new Set(
+    (modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry))
+  ));
+  const resolved = await Promise.all(
+    specifiers.map((specifier) => discoverInstalledPackageFromSpecifier(specifier, rootDir))
+  );
+  const seenPackageRoots = /* @__PURE__ */ new Set();
+  const packages = [];
+  for (const pkg of resolved) {
+    if (!pkg || seenPackageRoots.has(pkg.packageRoot)) continue;
+    seenPackageRoots.add(pkg.packageRoot);
+    packages.push(pkg);
+  }
+  return packages;
+}
 async function readInstalledPackageMetadata(packageJsonPath, fallbackSpecifier) {
   const pkg = await readPackageJSON(packageJsonPath);
   return {
@@ -863,15 +893,15 @@ async function validateContribution(contribution) {
   };
 }
 async function validateResolvedContributions(contributions) {
+  const validations = await Promise.all(contributions.map(validateContribution));
   const valid = [];
   const issues = [];
-  for (const contribution of contributions) {
-    const validation = await validateContribution(contribution);
-    if (!validation.issues.length) {
-      valid.push(validation.contribution);
+  for (const validation of validations) {
+    if (validation.issues.length) {
+      issues.push(...validation.issues);
       continue;
     }
-    issues.push(...validation.issues);
+    valid.push(validation.contribution);
   }
   return {
     contributions: sortAndDedupeContributions(valid),
@@ -1040,7 +1070,7 @@ 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`;
 }
 
-const GITHUB_OVERRIDES = [
+const PACKAGE_OVERRIDES = [
   {
     packageName: "@nuxt/ui",
     repo: "nuxt/ui",
@@ -1054,14 +1084,24 @@ const GITHUB_OVERRIDES = [
     ref: "main",
     path: "skills/vueuse-functions",
     skillName: "vueuse-functions"
+  },
+  {
+    packageName: "docus",
+    repo: "nuxt-content/docus",
+    docsUrls: ["https://docus.dev/"]
   }
 ];
-function findGitHubOverride(packageName) {
-  return GITHUB_OVERRIDES.find((entry) => entry.packageName === packageName);
+function findPackageOverride(packageName) {
+  return PACKAGE_OVERRIDES.find((entry) => entry.packageName === packageName);
 }
 
 const GITHUB_API_BASE = "https://api.github.com";
 const UNGH_API_BASE = "https://ungh.cc";
+const githubDirectoryCache = /* @__PURE__ */ new Map();
+const githubDefaultBranchCache = /* @__PURE__ */ new Map();
+const githubFileTextCache = /* @__PURE__ */ new Map();
+const urlTextCache = /* @__PURE__ */ new Map();
+const urlBytesCache = /* @__PURE__ */ new Map();
 function githubFetchOptions(timeoutMs) {
   return {
     timeout: timeoutMs,
@@ -1071,6 +1111,9 @@ function githubFetchOptions(timeoutMs) {
     }
   };
 }
+function fetchStatus(error) {
+  return typeof error === "object" && error && "status" in error ? Number(error.status) : void 0;
+}
 function encodeGitHubPath(path) {
   return path.split("/").filter(Boolean).map((segment) => encodeURIComponent(segment)).join("/");
 }
@@ -1096,6 +1139,15 @@ function toRepoPath(value) {
   }
   return null;
 }
+function memoize(cache, key, factory) {
+  const cached = cache.get(key);
+  if (cached) {
+    return cached;
+  }
+  const pending = factory();
+  cache.set(key, pending);
+  return pending;
+}
 function parseGitHubRepo(input) {
   if (!input) {
     return null;
@@ -1109,25 +1161,27 @@ async function listGitHubDirectory(repo, ref, dirPath, timeoutMs) {
   }
   const normalizedDirPath = dirPath.replace(/^\/+|\/+$/g, "");
   const prefix = normalizedDirPath ? `${normalizedDirPath}/` : "";
-  try {
-    const data = await ofetch(
-      `${GITHUB_API_BASE}/repos/${repoPath}/git/trees/${encodeURIComponent(ref)}?recursive=1`,
-      githubFetchOptions(timeoutMs)
-    );
-    const entries = /* @__PURE__ */ new Set();
-    for (const entry of data.tree || []) {
-      if (entry.type !== "tree" || !entry.path.startsWith(prefix)) {
-        continue;
-      }
-      const remainder = entry.path.slice(prefix.length);
-      if (remainder && !remainder.includes("/")) {
-        entries.add(remainder);
+  return await memoize(githubDirectoryCache, `${repoPath}::${ref}::${normalizedDirPath}`, async () => {
+    try {
+      const data = await ofetch(
+        `${GITHUB_API_BASE}/repos/${repoPath}/git/trees/${encodeURIComponent(ref)}?recursive=1`,
+        githubFetchOptions(timeoutMs)
+      );
+      const entries = /* @__PURE__ */ new Set();
+      for (const entry of data.tree || []) {
+        if (entry.type !== "tree" || !entry.path.startsWith(prefix)) {
+          continue;
+        }
+        const remainder = entry.path.slice(prefix.length);
+        if (remainder && !remainder.includes("/")) {
+          entries.add(remainder);
+        }
       }
+      return Array.from(entries).sort((a, b) => a.localeCompare(b));
+    } catch {
+      return [];
     }
-    return Array.from(entries).sort((a, b) => a.localeCompare(b));
-  } catch {
-    return [];
-  }
+  });
 }
 async function fetchGitHubDefaultBranch(repo, timeoutMs) {
   const repoPath = toRepoPath(repo);
@@ -1138,39 +1192,405 @@ async function fetchGitHubDefaultBranch(repo, timeoutMs) {
   if (!owner || !name) {
     return null;
   }
-  try {
-    const data = await ofetch(
-      `${UNGH_API_BASE}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`,
-      githubFetchOptions(timeoutMs)
-    );
-    return data.repo?.defaultBranch || null;
-  } catch {
-    return null;
-  }
+  return await memoize(githubDefaultBranchCache, repoPath, async () => {
+    try {
+      const data = await ofetch(
+        `${UNGH_API_BASE}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`,
+        githubFetchOptions(timeoutMs)
+      );
+      return data.repo?.defaultBranch || null;
+    } catch {
+      return null;
+    }
+  });
 }
 async function fetchGitHubFileText(repo, ref, filePath, timeoutMs) {
   const repoPath = toRepoPath(repo);
   if (!repoPath) {
     return { ok: false, error: "Invalid GitHub repository format" };
   }
-  try {
-    const data = await ofetch(
-      `https://raw.githubusercontent.com/${repoPath}/${encodeURIComponent(ref)}/${encodeGitHubPath(filePath)}`,
-      {
+  return await memoize(githubFileTextCache, `${repoPath}::${ref}::${filePath}`, async () => {
+    try {
+      const data = await ofetch(
+        `https://raw.githubusercontent.com/${repoPath}/${encodeURIComponent(ref)}/${encodeGitHubPath(filePath)}`,
+        {
+          ...githubFetchOptions(timeoutMs),
+          responseType: "text"
+        }
+      );
+      return { ok: true, data };
+    } catch (error) {
+      return {
+        ok: false,
+        status: fetchStatus(error),
+        error: error.message
+      };
+    }
+  });
+}
+async function fetchUrlText(url, timeoutMs) {
+  return await memoize(urlTextCache, url, async () => {
+    try {
+      const data = await ofetch(url, {
         ...githubFetchOptions(timeoutMs),
         responseType: "text"
-      }
-    );
-    return { ok: true, data };
+      });
+      return { ok: true, data };
+    } catch (error) {
+      return {
+        ok: false,
+        status: fetchStatus(error),
+        error: error.message
+      };
+    }
+  });
+}
+async function fetchUrlJson(url, timeoutMs) {
+  const text = await fetchUrlText(url, timeoutMs);
+  if (!text.ok) {
+    return {
+      ok: false,
+      status: text.status,
+      error: text.error
+    };
+  }
+  try {
+    return {
+      ok: true,
+      data: JSON.parse(text.data || "")
+    };
   } catch (error) {
-    const status = typeof error === "object" && error && "status" in error ? Number(error.status) : void 0;
     return {
       ok: false,
-      status,
       error: error.message
     };
   }
 }
+async function fetchUrlBytes(url, timeoutMs) {
+  return await memoize(urlBytesCache, url, async () => {
+    try {
+      const data = await ofetch(url, {
+        ...githubFetchOptions(timeoutMs),
+        responseType: "arrayBuffer"
+      });
+      return {
+        ok: true,
+        data: new Uint8Array(data)
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        status: fetchStatus(error),
+        error: error.message
+      };
+    }
+  });
+}
+
+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";
+function makeSkip$1(packageName, skillName, reason) {
+  return {
+    packageName,
+    skillName,
+    reason,
+    sourceKind: "wellKnown"
+  };
+}
+function normalizeHttpUrl$1(url) {
+  const trimmed = url?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.toString() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function normalizeHostname(hostname) {
+  return hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");
+}
+function parseIpv4(hostname) {
+  const parts = hostname.split(".");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const octets = parts.map((part) => {
+    if (!/^\d+$/.test(part)) {
+      return Number.NaN;
+    }
+    return Number(part);
+  });
+  if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+    return null;
+  }
+  return octets;
+}
+function isPrivateIpv4(hostname) {
+  const octets = parseIpv4(normalizeHostname(hostname));
+  if (!octets) {
+    return false;
+  }
+  const [a, b] = octets;
+  return a === 0 || a === 10 || a === 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a >= 224 && a <= 239 || a >= 240;
+}
+function isPrivateIpv6(hostname) {
+  const normalized = normalizeHostname(hostname);
+  return normalized === "::" || normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb");
+}
+function isUnsafeHostname(hostname) {
+  const normalized = normalizeHostname(hostname);
+  if (normalized === "localhost" || normalized.endsWith(".localhost")) {
+    return true;
+  }
+  const ipVersion = isIP(normalized);
+  if (ipVersion === 4) {
+    return isPrivateIpv4(normalized);
+  }
+  if (ipVersion === 6) {
+    return isPrivateIpv6(normalized);
+  }
+  return false;
+}
+function isPublicDiscoveryBase(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.hostname === "github.com" || parseGitHubRepo(url) || isUnsafeHostname(parsed.hostname)) {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isSameOriginUrl(url, baseUrl) {
+  return new URL(url).origin === new URL(baseUrl).origin;
+}
+function resolveSameOriginUrl(rawUrl, baseUrl) {
+  const trimmed = rawUrl.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    const resolved = new URL(trimmed, baseUrl);
+    if (!isSameOriginUrl(resolved.toString(), baseUrl) || isUnsafeHostname(resolved.hostname)) {
+      return null;
+    }
+    return resolved.toString();
+  } catch {
+    return null;
+  }
+}
+function docsBaseCandidates(packageInfo) {
+  const override = findPackageOverride(packageInfo.packageName);
+  const candidates = [
+    ...override?.docsUrls || [],
+    packageInfo.homepage || ""
+  ];
+  return [...new Set(candidates.map(normalizeHttpUrl$1).filter((url) => Boolean(url)).filter(isPublicDiscoveryBase))];
+}
+function normalizeDigest(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return /^sha256:[a-f0-9]{64}$/.test(trimmed) ? trimmed : null;
+}
+function sha256(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+async function writeSkillFile(root, relativePath, bytes) {
+  const destination = join(root, relativePath);
+  await ensureDir(dirname(destination));
+  await promises.writeFile(destination, bytes);
+}
+function contributionFor(input) {
+  const sourceRepo = parseGitHubRepo(input.packageInfo.repository);
+  return normalizeContribution({
+    packageName: input.packageInfo.packageName,
+    version: input.packageInfo.version,
+    skillName: input.skillName,
+    description: input.description,
+    sourceKind: "wellKnown",
+    sourceRepo: sourceRepo || void 0,
+    sourcePath: input.indexUrl,
+    repoUrl: sourceRepo ? `https://github.com/${sourceRepo}` : void 0,
+    docsUrl: input.docsUrl,
+    official: true,
+    resolver: input.resolver,
+    forceIncludeScripts: true
+  }, input.targetDir, join(input.targetDir, ".."));
+}
+async function materializeV2Skill(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 v2 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 v2 skill is missing a description") };
+  }
+  const type = typeof input.entry.type === "string" ? input.entry.type.trim() : "";
+  if (type === "archive") {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "archive artifacts are not supported yet") };
+  }
+  if (type !== "skill-md") {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `unsupported well-known v2 skill type "${type || "unknown"}"`) };
+  }
+  if (typeof input.entry.url !== "string" || !input.entry.url.trim()) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill is missing a URL") };
+  }
+  const digest = normalizeDigest(input.entry.digest);
+  if (!digest) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill is missing a valid sha256 digest") };
+  }
+  const skillUrl = resolveSameOriginUrl(input.entry.url, input.indexUrl);
+  if (!skillUrl) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill URL must stay on the discovery origin") };
+  }
+  const response = await fetchUrlBytes(skillUrl, input.timeoutMs);
+  if (!response.ok || !response.data) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "failed to fetch well-known v2 skill artifact") };
+  }
+  if (sha256(response.data) !== digest) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill digest mismatch") };
+  }
+  const origin = new URL(input.docsUrl).origin;
+  const targetDir = join(
+    input.cacheRoot,
+    "well-known",
+    "rfc",
+    sanitizeSegment(origin),
+    sanitizeSegment(input.packageInfo.packageName),
+    sanitizeSegment(input.packageInfo.version || "unknown"),
+    sanitizeSegment(skillName)
+  );
+  await emptyDir(targetDir);
+  await writeSkillFile(targetDir, "SKILL.md", response.data);
+  return {
+    contribution: contributionFor({
+      packageInfo: input.packageInfo,
+      targetDir,
+      skillName,
+      description,
+      docsUrl: input.docsUrl,
+      resolver: "wellKnownV2",
+      indexUrl: input.indexUrl
+    })
+  };
+}
+async function resolveV2Index(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 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 materialized = await materializeV2Skill({
+      packageInfo: input.packageInfo,
+      entry: rawEntry,
+      indexUrl: input.indexUrl,
+      docsUrl: input.docsUrl,
+      cacheRoot: input.cacheRoot,
+      timeoutMs: input.timeoutMs
+    });
+    if (materialized?.contribution) {
+      contributions.push(materialized.contribution);
+    }
+    if (materialized?.skipped) {
+      skipped.push(materialized.skipped);
+    }
+  }
+  return { contributions, issues: [], skipped };
+}
+async function resolveIndex(input) {
+  const response = await fetchUrlJson(input.indexUrl, input.timeoutMs);
+  if (!response.ok) {
+    if (response.status === 404) {
+      return null;
+    }
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, `failed to fetch well-known index ${input.indexUrl}`)]
+    };
+  }
+  const index = response.data;
+  if (!index || typeof index !== "object") {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known index must be an object")]
+    };
+  }
+  if (index.$schema === WELL_KNOWN_DISCOVERY_V2_SCHEMA) {
+    return await resolveV2Index({
+      ...input,
+      index
+    });
+  }
+  if (typeof index.$schema === "string" && index.$schema) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, `unsupported well-known schema "${index.$schema}"`)]
+    };
+  }
+  return {
+    contributions: [],
+    issues: [],
+    skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known index is missing the v2 schema")]
+  };
+}
+async function resolveViaWellKnown(packageInfo, cacheRoot, timeoutMs) {
+  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
+    });
+    if (!result) {
+      continue;
+    }
+    issues.push(...result.issues);
+    skipped.push(...result.skipped);
+    if (result.contributions.length) {
+      return {
+        contributions: result.contributions,
+        issues,
+        skipped
+      };
+    }
+  }
+  if (!bases.length) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: []
+    };
+  }
+  return {
+    contributions: [],
+    issues,
+    skipped
+  };
+}
 
 function makeSkip(packageName, skillName, reason, sourceKind) {
   return {
@@ -1213,8 +1633,14 @@ function normalizeHttpUrl(url) {
     return void 0;
   }
 }
+function resolveDocsUrl(packageInfo) {
+  const override = findPackageOverride(packageInfo.packageName);
+  const overrideDocsUrl = override?.docsUrls?.map(normalizeHttpUrl).find(Boolean);
+  return overrideDocsUrl || normalizeHttpUrl(packageInfo.homepage);
+}
 function resolveRepositoryUrl(packageInfo) {
-  const sourceRepo = parseGitHubRepo(packageInfo.repository) || parseGitHubRepo(packageInfo.homepage);
+  const override = findPackageOverride(packageInfo.packageName);
+  const sourceRepo = override?.repo || parseGitHubRepo(packageInfo.repository) || parseGitHubRepo(packageInfo.homepage);
   if (sourceRepo) {
     return {
       sourceRepo,
@@ -1225,6 +1651,15 @@ function resolveRepositoryUrl(packageInfo) {
     repoUrl: normalizeHttpUrl(packageInfo.repository)
   };
 }
+function isImmutableRef(ref, version) {
+  if (!ref) {
+    return false;
+  }
+  if (version && (ref === version || ref === `v${version}`)) {
+    return true;
+  }
+  return /^[a-f0-9]{7,40}$/i.test(ref);
+}
 async function materializeCandidate(packageInfo, candidate, cacheRoot) {
   const targetDir = join(
     cacheRoot,
@@ -1232,8 +1667,24 @@ async function materializeCandidate(packageInfo, candidate, cacheRoot) {
     sanitizeSegment(candidate.sourceRepo),
     sanitizeSegment(candidate.sourceRef),
     sanitizeSegment(packageInfo.packageName),
+    sanitizeSegment(packageInfo.version || "unknown"),
     sanitizeSegment(candidate.skillName)
   );
+  const skillFilePath = join(targetDir, "SKILL.md");
+  if (isImmutableRef(candidate.sourceRef, packageInfo.version) && await pathExists(skillFilePath)) {
+    return normalizeContribution({
+      packageName: packageInfo.packageName,
+      version: packageInfo.version,
+      skillName: candidate.skillName,
+      sourceKind: candidate.sourceKind,
+      sourceRepo: candidate.sourceRepo,
+      sourceRef: candidate.sourceRef,
+      sourcePath: candidate.sourcePath,
+      official: candidate.official,
+      resolver: candidate.resolver,
+      forceIncludeScripts: true
+    }, targetDir, join(targetDir, ".."));
+  }
   try {
     await downloadTemplate(`gh:${candidate.sourceRepo}/${candidate.sourcePath}#${candidate.sourceRef}`, {
       dir: targetDir,
@@ -1245,7 +1696,7 @@ async function materializeCandidate(packageInfo, candidate, cacheRoot) {
   } catch {
     return null;
   }
-  if (!await pathExists(join(targetDir, "SKILL.md"))) {
+  if (!await pathExists(skillFilePath)) {
     return null;
   }
   return normalizeContribution({
@@ -1261,25 +1712,13 @@ async function materializeCandidate(packageInfo, candidate, cacheRoot) {
     forceIncludeScripts: true
   }, targetDir, join(targetDir, ".."));
 }
-async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
-  const issues = [];
-  const skipped = [];
-  const override = findGitHubOverride(packageInfo.packageName);
+function createGitHubResolveContext(packageInfo) {
+  const override = findPackageOverride(packageInfo.packageName);
   const repo = override?.repo || parseGitHubRepo(packageInfo.repository) || parseGitHubRepo(packageInfo.homepage);
-  if (!repo) {
-    return {
-      contributions: [],
-      issues,
-      skipped: [makeSkip(packageInfo.packageName, override?.skillName || packageInfo.packageName, "No GitHub repository metadata found", "github")]
-    };
-  }
   const refs = dedupe([
     override?.ref || "",
     packageInfo.version ? `v${packageInfo.version}` : "",
-    packageInfo.version || "",
-    await fetchGitHubDefaultBranch(repo, timeoutMs) || "",
-    "main",
-    "master"
+    packageInfo.version || ""
   ]);
   const candidates = dedupe([
     override?.skillName || "",
@@ -1295,32 +1734,89 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
       ];
     })
   ]);
-  for (const ref of refs) {
-    const packageJson = await fetchGitHubFileText(repo, ref, "package.json", timeoutMs);
-    if (packageJson.ok && packageJson.data) {
-      try {
-        const parsed = JSON.parse(packageJson.data);
-        const remoteSkills = parseAgentSkillDeclarations(parsed, packageInfo.packageName, "github");
-        issues.push(...remoteSkills.issues);
-        for (const skill of remoteSkills.skills) {
-          const resolved = await materializeCandidate(packageInfo, {
-            skillName: skill.name,
-            sourcePath: skill.path,
-            sourceKind: "github",
-            sourceRepo: repo,
-            sourceRef: ref,
-            official: true,
-            resolver: "agentsField"
-          }, cacheRoot);
-          if (resolved) {
-            return { contributions: [resolved], issues, skipped };
-          }
-        }
-      } catch {
-        issues.push(createValidationIssue(packageInfo.packageName, packageInfo.packageName, "Failed to parse remote package.json", "github"));
+  return {
+    issues: [],
+    skipped: [],
+    override,
+    repo: repo || void 0,
+    refs,
+    pathCandidates
+  };
+}
+async function resolveAgentSkillsForRef(packageInfo, context, ref, cacheRoot, timeoutMs) {
+  if (!context.repo) {
+    return null;
+  }
+  const packageJson = await fetchGitHubFileText(context.repo, ref, "package.json", timeoutMs);
+  if (!packageJson.ok || !packageJson.data) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(packageJson.data);
+    const remoteSkills = parseAgentSkillDeclarations(parsed, packageInfo.packageName, "github");
+    context.issues.push(...remoteSkills.issues);
+    for (const skill of remoteSkills.skills) {
+      const resolved = await materializeCandidate(packageInfo, {
+        skillName: skill.name,
+        sourcePath: skill.path,
+        sourceKind: "github",
+        sourceRepo: context.repo,
+        sourceRef: ref,
+        official: true,
+        resolver: "agentsField"
+      }, cacheRoot);
+      if (resolved) {
+        return [resolved];
       }
     }
-    const skillsDirs = await listGitHubDirectory(repo, ref, "skills", timeoutMs);
+  } catch {
+    context.issues.push(createValidationIssue(packageInfo.packageName, packageInfo.packageName, "Failed to parse remote package.json", "github"));
+  }
+  return null;
+}
+async function resolveViaGitHubAgents(packageInfo, cacheRoot, timeoutMs) {
+  const context = createGitHubResolveContext(packageInfo);
+  if (!context.repo) {
+    return {
+      contributions: [],
+      issues: context.issues,
+      skipped: []
+    };
+  }
+  for (const ref of context.refs) {
+    const resolved = await resolveAgentSkillsForRef(packageInfo, context, ref, cacheRoot, timeoutMs);
+    if (resolved?.length) {
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
+    }
+  }
+  const fallbackRefs = dedupe([
+    await fetchGitHubDefaultBranch(context.repo, timeoutMs) || "",
+    "main",
+    "master"
+  ]);
+  for (const ref of fallbackRefs) {
+    const resolved = await resolveAgentSkillsForRef(packageInfo, context, ref, cacheRoot, timeoutMs);
+    if (resolved?.length) {
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
+    }
+  }
+  return {
+    contributions: [],
+    issues: context.issues,
+    skipped: context.skipped
+  };
+}
+async function resolveViaGitHubHeuristics(packageInfo, cacheRoot, timeoutMs) {
+  const context = createGitHubResolveContext(packageInfo);
+  if (!context.repo) {
+    return {
+      contributions: [],
+      issues: context.issues,
+      skipped: [makeSkip(packageInfo.packageName, context.override?.skillName || packageInfo.packageName, "No GitHub repository metadata found", "github")]
+    };
+  }
+  const tryResolveForRef = async (ref, allowTreeLookup) => {
+    const skillsDirs = await listGitHubDirectory(context.repo, ref, "skills", timeoutMs) ;
     if (skillsDirs.length) {
       const contributions = [];
       for (const skillName of skillsDirs) {
@@ -1328,7 +1824,7 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
           skillName,
           sourcePath: `skills/${skillName}`,
           sourceKind: "github",
-          sourceRepo: repo,
+          sourceRepo: context.repo,
           sourceRef: ref,
           official: true,
           resolver: "githubHeuristic"
@@ -1338,35 +1834,53 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
         }
       }
       if (contributions.length) {
-        return { contributions, issues, skipped };
+        return contributions;
       }
     }
-    for (const path of pathCandidates) {
-      const candidateSkillName = override?.path && path === override.path ? override.skillName || path.split("/").pop() || packageInfo.packageName : path.split("/").pop() || packageInfo.packageName;
+    for (const path of context.pathCandidates) {
+      const candidateSkillName = context.override?.path && path === context.override.path ? context.override.skillName || path.split("/").pop() || packageInfo.packageName : path.split("/").pop() || packageInfo.packageName;
       const resolved = await materializeCandidate(packageInfo, {
         skillName: candidateSkillName,
         sourcePath: path,
         sourceKind: "github",
-        sourceRepo: repo,
+        sourceRepo: context.repo,
         sourceRef: ref,
         official: true,
         resolver: "githubHeuristic"
       }, cacheRoot);
       if (resolved) {
-        return { contributions: [resolved], issues, skipped };
+        return [resolved];
       }
     }
+    return null;
+  };
+  const fallbackRefs = dedupe([
+    await fetchGitHubDefaultBranch(context.repo, timeoutMs) || "",
+    "main",
+    "master"
+  ]);
+  for (const ref of fallbackRefs) {
+    const resolved = await tryResolveForRef(ref);
+    if (resolved?.length) {
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
+    }
+  }
+  for (const ref of context.refs) {
+    const resolved = await tryResolveForRef(ref);
+    if (resolved?.length) {
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
+    }
   }
-  skipped.push(makeSkip(packageInfo.packageName, override?.skillName || packageInfo.packageName, "No GitHub skill found using configured refs and path heuristics", "github"));
+  context.skipped.push(makeSkip(packageInfo.packageName, context.override?.skillName || packageInfo.packageName, "No GitHub skill found using configured refs and path heuristics", "github"));
   return {
     contributions: [],
-    issues,
-    skipped
+    issues: context.issues,
+    skipped: context.skipped
   };
 }
 async function resolveViaMetadataRouter(packageInfo, cacheRoot) {
   const { repoUrl, sourceRepo } = resolveRepositoryUrl(packageInfo);
-  const docsUrl = normalizeHttpUrl(packageInfo.homepage);
+  const docsUrl = resolveDocsUrl(packageInfo);
   if (!repoUrl && !docsUrl) {
     return {
       contributions: [],
@@ -1380,8 +1894,31 @@ async function resolveViaMetadataRouter(packageInfo, cacheRoot) {
     "generated",
     "metadata-router",
     sanitizeSegment(packageInfo.packageName),
+    sanitizeSegment(packageInfo.version || "unknown"),
     sanitizeSegment(skillName)
   );
+  const skillFilePath = join(targetDir, "SKILL.md");
+  if (await pathExists(skillFilePath)) {
+    return {
+      contributions: [
+        normalizeContribution({
+          packageName: packageInfo.packageName,
+          version: packageInfo.version,
+          skillName,
+          description: packageInfo.description,
+          sourceKind: "generated",
+          sourceRepo,
+          repoUrl,
+          docsUrl,
+          official: true,
+          resolver: "metadataRouter",
+          forceIncludeScripts: false
+        }, targetDir, join(targetDir, ".."))
+      ],
+      issues: [],
+      skipped: []
+    };
+  }
   const files = createMetadataRouterSkillFiles({
     packageName: packageInfo.packageName,
     skillName,
@@ -1415,26 +1952,46 @@ async function resolveViaMetadataRouter(packageInfo, cacheRoot) {
   };
 }
 async function resolveRemoteContributionsForPackage(packageInfo, options) {
-  const githubResult = options.enableGithubLookup ? await resolveViaGitHub(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
+  const githubAgentsResult = options.enableGithubLookup ? await resolveViaGitHubAgents(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
     contributions: [],
     issues: [],
     skipped: []
   };
-  if (githubResult.contributions.length) {
-    return githubResult;
+  if (githubAgentsResult.contributions.length) {
+    return githubAgentsResult;
+  }
+  const wellKnownResult = await resolveViaWellKnown(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs);
+  if (wellKnownResult.contributions.length) {
+    return {
+      contributions: wellKnownResult.contributions,
+      issues: [...githubAgentsResult.issues, ...wellKnownResult.issues],
+      skipped: wellKnownResult.skipped
+    };
+  }
+  const githubHeuristicResult = options.enableGithubLookup ? await resolveViaGitHubHeuristics(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
+    contributions: [],
+    issues: [],
+    skipped: []
+  };
+  if (githubHeuristicResult.contributions.length) {
+    return {
+      contributions: githubHeuristicResult.contributions,
+      issues: [...githubAgentsResult.issues, ...wellKnownResult.issues, ...githubHeuristicResult.issues],
+      skipped: wellKnownResult.skipped
+    };
   }
   const generatedResult = await resolveViaMetadataRouter(packageInfo, options.cacheRoot);
   if (generatedResult.contributions.length) {
     return {
       contributions: generatedResult.contributions,
-      issues: [...githubResult.issues, ...generatedResult.issues],
-      skipped: generatedResult.skipped
+      issues: [...githubAgentsResult.issues, ...wellKnownResult.issues, ...githubHeuristicResult.issues, ...generatedResult.issues],
+      skipped: [...wellKnownResult.skipped, ...generatedResult.skipped]
     };
   }
   return {
     contributions: [],
-    issues: [...githubResult.issues, ...generatedResult.issues],
-    skipped: [...githubResult.skipped, ...generatedResult.skipped]
+    issues: [...githubAgentsResult.issues, ...wellKnownResult.issues, ...githubHeuristicResult.issues, ...generatedResult.issues],
+    skipped: [...wellKnownResult.skipped, ...githubHeuristicResult.skipped, ...generatedResult.skipped]
   };
 }
 
@@ -1492,6 +2049,7 @@ async function hashFileIfExists(path) {
   }
 }
 
+const HASH_READ_CONCURRENCY = 16;
 async function resolveManualContribution(rootDir, contribution) {
   const sourceDir = isAbsolute(contribution.sourceDir) ? contribution.sourceDir : resolve(rootDir, contribution.sourceDir);
   return normalizeContribution(contribution, sourceDir, sourceDir);
@@ -1543,8 +2101,6 @@ async function hashDirectoryTreeIfExists(rootPath) {
   if (!rootStat.isDirectory()) {
     return null;
   }
-  const hash = createHash("sha256");
-  hash.update("dir:.\n");
   const entries = await glob("**/*", {
     cwd: rootPath,
     dot: true,
@@ -1553,30 +2109,20 @@ async function hashDirectoryTreeIfExists(rootPath) {
     onlyFiles: false
   });
   entries.sort((a, b) => a.localeCompare(b));
-  for (const entry of entries) {
+  const chunkGroups = await mapWithConcurrency(entries, HASH_READ_CONCURRENCY, async (entry) => {
     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}
-`);
-  }
+    const rel = relative(rootPath, currentPath).replaceAll("\\", "/");
+    if (stat.isSymbolicLink()) return [`symlink:${rel}:`, await promises.readlink(currentPath), "\n"];
+    if (stat.isDirectory()) return [`dir:${rel}
+`];
+    if (stat.isFile()) return [`file:${rel}:`, await promises.readFile(currentPath), "\n"];
+    return [`other:${rel}:${stat.mode}
+`];
+  });
+  const hash = createHash("sha256");
+  hash.update("dir:.\n");
+  for (const chunks of chunkGroups) for (const chunk of chunks) hash.update(chunk);
   return hash.digest("hex");
 }
 
@@ -1613,6 +2159,7 @@ async function isGeneratedSkillFresh(generatedSkillRoot, fingerprint) {
 }
 
 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/")) {
@@ -1630,6 +2177,12 @@ function normalizeRelativePath(from, to) {
 function getGeneratedSkillRoot(buildDir, skillName) {
   return join(buildDir, "skill-hub", skillName);
 }
+function getPersistentCacheRoot(exportRoot) {
+  return join(exportRoot, "node_modules", ".cache", "nuxt-skill-hub");
+}
+function getCachedGeneratedSkillRoot(cacheRoot, skillName) {
+  return join(cacheRoot, "generated", skillName);
+}
 function mergeSkipped(entries, keyFn) {
   const byKey = /* @__PURE__ */ new Map();
   for (const entry of entries) {
@@ -1666,17 +2219,13 @@ async function collectInstalledPackages(nuxt) {
       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 modulePackages = await collectInstalledModulePackages(nuxt.options.modules, nuxt.options.rootDir);
+  for (const pkg of modulePackages) addInstalledPackage(pkg);
   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 layerPackages = await Promise.all(layerDirectories.map((dir) => discoverInstalledPackageFromDirectory(dir)));
+  for (const pkg of layerPackages) addInstalledPackage(pkg);
   const localPackageSkills = await discoverLocalPackageSkills(nuxt.options.rootDir);
   if (localPackageSkills) {
     discoveries.push(localPackageSkills);
@@ -1706,6 +2255,8 @@ async function ensureStableSkillWrappers(input) {
 async function generateSkillTree(input) {
   const { nuxt, logger, options, skillName, exportRoot, generationMode } = input;
   const stableBuildDir = resolveStableSkillBuildDir(nuxt.options.rootDir, nuxt.options.buildDir);
+  const persistentCacheRoot = getPersistentCacheRoot(exportRoot);
+  const cachedGeneratedSkillRoot = getCachedGeneratedSkillRoot(persistentCacheRoot, skillName);
   const generatedSkillRoot = getGeneratedSkillRoot(stableBuildDir, skillName);
   const referencesRoot = join(generatedSkillRoot, "references");
   const nuxtRoot = join(referencesRoot, "nuxt");
@@ -1739,26 +2290,32 @@ async function generateSkillTree(input) {
       ...sortAndDedupeContributions(resolvedManual)
     ])
   });
-  if (generationMode === "prepare" && await isGeneratedSkillFresh(generatedSkillRoot, fingerprint)) {
-    logger.info(`Generated ${skillName} skill is already up to date at ${generatedSkillRoot}`);
+  if (generationMode === "prepare" && await isGeneratedSkillFresh(cachedGeneratedSkillRoot, fingerprint)) {
+    await copySkillTree(cachedGeneratedSkillRoot, generatedSkillRoot, true);
+    logger.info(`Restored cached ${skillName} skill from ${cachedGeneratedSkillRoot}`);
     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 remoteCacheRoot = join(persistentCacheRoot, "remote");
+  await ensureDir(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
-    });
+  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
+      });
+    }
+  );
+  for (const remote of remoteResults) {
     remoteIssues.push(...remote.issues);
     remoteSkipped.push(...remote.skipped);
     remoteContributions.push(...remote.contributions);
@@ -1841,14 +2398,47 @@ async function generateSkillTree(input) {
     skipped
   ));
   await writeGenerationState(generatedSkillRoot, fingerprint);
+  await copySkillTree(generatedSkillRoot, cachedGeneratedSkillRoot, true);
   logger.success(`Generated ${skillName} skill at ${generatedSkillRoot}`);
 }
 
 function isCancelled(value) {
   return value === null || typeof value === "symbol";
 }
+function buildAIGuidance(currentTarget, detectedAgent) {
+  const agentTargetMap = {
+    codex: "codex",
+    claude: "claude-code",
+    gemini: "gemini-code-assist",
+    replit: "replit-agent"
+  };
+  const target = currentTarget || (detectedAgent ? agentTargetMap[detectedAgent] : void 0);
+  const sourceLabel = detectedAgent ? ` (${detectedAgent})` : "";
+  const snippetLines = [
+    "export default defineNuxtConfig({",
+    "  skillHub: {",
+    ...target ? [`    targets: ['${target}'],`] : [],
+    `    generationMode: 'prepare',`,
+    "  },",
+    "})"
+  ];
+  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"),
+    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);
+    logger.info(guidance.intro);
+    logger.info(`\`\`\`ts
+${guidance.snippet}
+\`\`\``);
+    logger.info(guidance.optionalFlags);
+    return;
+  }
   if (process.env.CI || !process.stdout.isTTY) {
     logger.info("Non-interactive environment detected, skipping install wizard.");
     return;
@@ -1903,15 +2493,7 @@ Let's configure AI agent skills for your Nuxt project.`
       }
     }
   }
-  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);
-  }
+  const installedModulePackages = (await collectInstalledModulePackages(nuxt.options.modules, rootDir)).map((pkg) => pkg.packageName).filter((name) => name !== "nuxt-skill-hub");
   if (installedModulePackages.length) {
     consola.info(`Detected ${installedModulePackages.length} installed module package(s):`);
     for (const packageName of installedModulePackages) {
@@ -2005,6 +2587,49 @@ Configure \`skillHub.skillName\`, \`skillHub.targets\`, or set \`skillHub.genera
   );
 }
 
+function createAutoImportAddon(nuxt) {
+  let unimport;
+  let nitroUnimport;
+  const hook = nuxt.hook;
+  hook("imports:context", (context) => {
+    unimport = context;
+  });
+  hook("nitro:init", (nitro) => {
+    nitroUnimport = nitro.unimport;
+  });
+  hook("eslint:config:addons", (addons) => {
+    addons.push({
+      name: "skill-hub:no-redundant-import",
+      async getConfigs() {
+        const imports = [
+          ...await unimport?.getImports() || [],
+          ...await nitroUnimport?.getImports() || []
+        ];
+        const seen = /* @__PURE__ */ new Set();
+        const entries = imports.filter((i) => {
+          const key = `${i.as || i.name}:${i.from}:${i.type ? "type" : "value"}`;
+          if (seen.has(key)) return false;
+          seen.add(key);
+          return true;
+        }).map((i) => ({ name: i.name, ...i.as && i.as !== i.name ? { as: i.as } : {}, from: i.from, ...i.type ? { type: true } : {} })).sort((a, b) => a.from.localeCompare(b.from) || a.name.localeCompare(b.name));
+        return {
+          imports: [{ from: "nuxt-skill-hub/eslint-plugin", name: "default", as: "skillHubPlugin" }],
+          configs: [
+            [
+              "{",
+              `  name: 'skill-hub/no-redundant-import',`,
+              `  plugins: { 'skill-hub': skillHubPlugin },`,
+              `  settings: { 'skill-hub/autoImports': ${JSON.stringify(entries)} },`,
+              `  rules: { 'skill-hub/no-redundant-import': 'warn' },`,
+              "}"
+            ].join("\n")
+          ]
+        };
+      }
+    });
+  });
+}
+
 const module$1 = defineNuxtModule({
   meta: {
     name: "nuxt-skill-hub",
@@ -2025,6 +2650,8 @@ const module$1 = defineNuxtModule({
   },
   async setup(options, nuxt) {
     const logger = useLogger("nuxt-skill-hub");
+    if (options.eslint !== false)
+      createAutoImportAddon(nuxt);
     if (isCI && !isTest) {
       logger.info("Skipping skill generation in CI");
       return;