@hasna/skills 0.6.0 → 0.6.2

package/bin/index.js

@@ -47,6 +47,14 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
+// src/cli/output.ts
+async function writeCliOutput(text, newline = true) {
+  await new Promise((resolve, reject) => {
+    process.stdout.write(newline ? `${text}
+` : text, (error) => error ? reject(error) : resolve());
+  });
+}
+
 // ../../node_modules/.bun/react@18.3.1/node_modules/react/cjs/react.development.js
 var require_react_development = __commonJS((exports, module) => {
   if (true) {
@@ -36860,7 +36868,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.6.0",
+    version: "0.6.2",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -42998,7 +43006,7 @@ var require_cli_spinners = __commonJS((exports, module) => {
 
 // src/lib/agent-integration.ts
 import { createHash as createHash2, randomUUID as randomUUID3 } from "crypto";
-import { existsSync as existsSync13, lstatSync as lstatSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync8, readdirSync as readdirSync7, readlinkSync, realpathSync as realpathSync3, renameSync as renameSync2, writeFileSync as writeFileSync4, unlinkSync, chmodSync } from "fs";
+import { existsSync as existsSync13, lstatSync as lstatSync3, statSync as statSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync8, readdirSync as readdirSync7, readlinkSync, realpathSync as realpathSync3, renameSync as renameSync2, writeFileSync as writeFileSync4, unlinkSync, chmodSync } from "fs";
 import { dirname as dirname4, join as join13, resolve as resolve4, relative as relative3, isAbsolute as isAbsolute3, sep as sep3 } from "path";
 import { homedir as homedir3 } from "os";
 function assertSafePath(path) {
@@ -43086,15 +43094,27 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
     for (const [agent, path] of ROOTS)
       roots.push([agent, join13(resolve4(options.projectDir), path)]);
   const entries = [], seen = new Set;
-  function visit(agent, path, vendor = false, depth = 0) {
+  const cacheScans = new Map, maxAliasProofEntries = 1e4;
+  function emptySiblingCacheAlias(path, parent) {
+    const link2 = readlinkSync(path), target = resolve4(parent, link2);
+    if (dirname4(target) !== parent || (isAbsolute3(link2) ? link2 !== target : dirname4(link2) !== "."))
+      return false;
+    if (!lstatSync3(target, { throwIfNoEntry: false })?.isDirectory())
+      return false;
+    const scan = cacheScans.get(target);
+    return Boolean(scan?.complete && !scan.hasSkills && scan.entries <= maxAliasProofEntries);
+  }
+  function visit(agent, path, vendor = false, depth = 0, pluginCache = false) {
+    const scan = { complete: true, hasSkills: false, entries: 1 };
     assertSafePath(path);
     if (!existsSync13(path))
-      return;
+      return scan;
     if (!lstatSync3(path).isDirectory())
-      return;
+      return scan;
     if (existsSync13(join13(path, "SKILL.md"))) {
+      scan.hasSkills = true;
       if (seen.has(path))
-        return;
+        return scan;
       seen.add(path);
       let managed = false;
       const marker = join13(path, ".hasna-skills.json");
@@ -43105,11 +43125,14 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
       }
       const rootAlias = aliases.find((item) => path === item.target || path.startsWith(item.target + sep3));
       entries.push({ agent, path, hash: treeHash(path), managed, vendor, ...rootAlias ? { rootAlias } : {} });
-      return;
+      return scan;
     }
     if (depth > (vendor ? 8 : 3))
-      return;
-    for (const name of readdirSync7(path).sort()) {
+      return { ...scan, complete: false };
+    const children = readdirSync7(path, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    if (pluginCache)
+      children.sort((a, b) => Number(a.isSymbolicLink()) - Number(b.isSymbolicLink()));
+    for (const { name } of children) {
       if (name === "node_modules")
         continue;
       if (name.startsWith(".") && name !== ".system")
@@ -43117,14 +43140,28 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
       const isVendor = vendor || name === ".system";
       if (isVendor && !options.includeVendor)
         continue;
-      visit(agent, join13(path, name), isVendor, depth + 1);
+      const child = join13(path, name);
+      if (isVendor && lstatSync3(child, { throwIfNoEntry: false })?.isSymbolicLink()) {
+        const target = statSync7(child, { throwIfNoEntry: false });
+        if (target?.isFile() || pluginCache && target?.isDirectory() && emptySiblingCacheAlias(child, path)) {
+          scan.entries++;
+          continue;
+        }
+      }
+      const childScan = visit(agent, child, isVendor, depth + 1, pluginCache);
+      scan.complete &&= childScan.complete;
+      scan.hasSkills ||= childScan.hasSkills;
+      scan.entries += childScan.entries;
     }
+    if (pluginCache)
+      cacheScans.set(path, scan);
+    return scan;
   }
   for (const [agent, path] of roots)
     visit(agent, path);
   if (options.includeVendor) {
     for (const agent of ["codex", "claude"])
-      visit(agent, canonicalAgentPath(join13(home, `.${agent}`, "plugins", "cache"), aliases), true);
+      visit(agent, canonicalAgentPath(join13(home, `.${agent}`, "plugins", "cache"), aliases), true, 0, true);
   }
   recheckRootAliases(aliases);
   return entries;
@@ -43355,7 +43392,7 @@ var init_agent_integration = __esm(() => {
 });
 
 // src/lib/home-migration.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync5, readdirSync as readdirSync8, renameSync as renameSync3, rmSync as rmSync2, statSync as statSync7, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync14, mkdirSync as mkdirSync5, readdirSync as readdirSync8, renameSync as renameSync3, rmSync as rmSync2, statSync as statSync8, writeFileSync as writeFileSync5 } from "fs";
 import { join as join14 } from "path";
 function layoutMigrationRecordPath(appDir) {
   return join14(appDir, SKILLS_CACHE_DIRNAME, LAYOUT_MIGRATION_RECORD);
@@ -43368,7 +43405,7 @@ function migrationAppDir(homeDir) {
 }
 function looksLikeSkillDirectory2(path) {
   try {
-    if (!statSync7(path).isDirectory())
+    if (!statSync8(path).isDirectory())
       return false;
   } catch {
     return false;
@@ -43500,7 +43537,7 @@ import {
   readdirSync as readdirSync9,
   renameSync as renameSync4,
   rmSync as rmSync3,
-  statSync as statSync8,
+  statSync as statSync9,
   writeFileSync as writeFileSync6
 } from "fs";
 import { homedir as homedir4 } from "os";
@@ -43617,7 +43654,7 @@ function containsSkillDirectories(path) {
 }
 function isDirectory(path) {
   try {
-    return statSync8(path).isDirectory();
+    return statSync9(path).isDirectory();
   } catch {
     return false;
   }
@@ -50115,7 +50152,7 @@ var init_remote_workspace_leave = __esm(() => {
 });
 
 // src/lib/auth-store.ts
-import { chmodSync as chmodSync2, existsSync as existsSync18, mkdirSync as mkdirSync8, readFileSync as readFileSync13, renameSync as renameSync5, statSync as statSync9, unlinkSync as unlinkSync2, writeFileSync as writeFileSync8 } from "fs";
+import { chmodSync as chmodSync2, existsSync as existsSync18, mkdirSync as mkdirSync8, readFileSync as readFileSync13, renameSync as renameSync5, statSync as statSync10, unlinkSync as unlinkSync2, writeFileSync as writeFileSync8 } from "fs";
 import { basename as basename4, dirname as dirname7, join as join19 } from "path";
 function getAuthFilePath(env3 = process.env) {
   return skillsCredentialFilePath(env3);
@@ -50273,7 +50310,7 @@ function getApiUrl(action, env3 = process.env, options = {}) {
 }
 function credentialFileMode(env3 = process.env) {
   try {
-    return statSync9(skillsCredentialFilePath(env3)).mode & 511;
+    return statSync10(skillsCredentialFilePath(env3)).mode & 511;
   } catch {
     return null;
   }
@@ -51422,7 +51459,7 @@ var init_revision = __esm(() => {
 
 // src/lib/skill-bundle.ts
 import { createHash as createHash5 } from "crypto";
-import { readFileSync as readFileSync14, readdirSync as readdirSync10, statSync as statSync10 } from "fs";
+import { readFileSync as readFileSync14, readdirSync as readdirSync10, statSync as statSync11 } from "fs";
 import { join as join20, relative as relative4 } from "path";
 import { createGunzip } from "zlib";
 function isDotenvFile(lower) {
@@ -51483,7 +51520,7 @@ function walk(root, current, out) {
       continue;
     if (isCredentialFile(entry.name))
       continue;
-    const stats = statSync10(absolute);
+    const stats = statSync11(absolute);
     out.push({
       path: rel,
       bytes: ownBytes(readFileSync14(absolute)),
@@ -53548,7 +53585,7 @@ function registerContextCommands(parent) {
         sessionId: options.session,
         file: options.file
       });
-      console.log(options.json ? JSON.stringify(result2) : result2.content);
+      await writeCliOutput(options.json ? JSON.stringify(result2) : result2.content);
     } catch (error) {
       reportContextError(error, options.json);
     }
@@ -53565,7 +53602,7 @@ function registerContextCommands(parent) {
         maxChars: Number(options.maxChars),
         maxSkills: Number(options.maxSkills)
       });
-      console.log(options.json ? JSON.stringify(result2) : result2.context);
+      await writeCliOutput(options.json ? JSON.stringify(result2) : result2.context);
     } catch (error) {
       reportContextError(error, options.json);
     }
@@ -53656,9 +53693,9 @@ async function handleProfileSync(options, dependencies = {}) {
       check: options.check ?? dependencies.check
     });
     if (options.json)
-      console.log(JSON.stringify(result2));
+      await writeCliOutput(JSON.stringify(result2));
     else
-      console.log(options.check ? result2.changed ? "Skills profile or cached bundles need syncing." : "Skills profile and cached bundles are current." : `Synced Skills profile ${result2.profile.profileId} at ${result2.profile.profileRevision}; ${result2.downloaded} bundle(s) downloaded.`);
+      await writeCliOutput(options.check ? result2.changed ? "Skills profile or cached bundles need syncing." : "Skills profile and cached bundles are current." : `Synced Skills profile ${result2.profile.profileId} at ${result2.profile.profileRevision}; ${result2.downloaded} bundle(s) downloaded.`);
     if (options.check && result2.changed)
       process.exitCode = 1;
   } catch (error) {
@@ -55427,7 +55464,7 @@ var init_init = __esm(() => {
 });
 
 // src/lib/home-adoption.ts
-import { constants as constants4, closeSync as closeSync4, fstatSync as fstatSync4, lstatSync as lstatSync8, openSync as openSync4, readSync as readSync3, existsSync as existsSync24, mkdirSync as mkdirSync11, readdirSync as readdirSync11, readFileSync as readFileSync21, rmSync as rmSync6, statSync as statSync11, writeFileSync as writeFileSync12 } from "fs";
+import { constants as constants4, closeSync as closeSync4, fstatSync as fstatSync4, lstatSync as lstatSync8, openSync as openSync4, readSync as readSync3, existsSync as existsSync24, mkdirSync as mkdirSync11, readdirSync as readdirSync11, readFileSync as readFileSync21, rmSync as rmSync6, statSync as statSync12, writeFileSync as writeFileSync12 } from "fs";
 import { homedir as homedir6 } from "os";
 import { join as join27 } from "path";
 function indexCanonicalCorpus(corpusRoot) {
@@ -55463,7 +55500,7 @@ function selectedHomeNames(options, index, homeDir2, agents) {
       continue;
     const present = agents.some((agent) => {
       try {
-        return statSync11(join27(agentGlobalSkillsDir(agent, homeDir2), name)).isDirectory();
+        return statSync12(join27(agentGlobalSkillsDir(agent, homeDir2), name)).isDirectory();
       } catch {
         return false;
       }
@@ -55497,7 +55534,7 @@ function scanUnmarkedHomes(options = {}) {
         continue;
       const dir = join27(home, skill);
       try {
-        if (!statSync11(dir).isDirectory())
+        if (!statSync12(dir).isDirectory())
           continue;
       } catch {
         continue;
@@ -55510,7 +55547,7 @@ function scanUnmarkedHomes(options = {}) {
       if (!existsSync24(skillMdPath))
         continue;
       const hash2 = hashSkillMarkdownFile(skillMdPath);
-      const mtime = statSync11(skillMdPath).mtime.toISOString();
+      const mtime = statSync12(skillMdPath).mtime.toISOString();
       const entry = { agent, skill, home, path: dir, hash: hash2, mtime };
       const canonicalHash = index.get(skill);
       if (canonicalHash === undefined) {
@@ -55639,7 +55676,7 @@ function pruneStrayHomes(options = {}) {
         continue;
       const dir = join27(home, skill);
       try {
-        if (!statSync11(dir).isDirectory())
+        if (!statSync12(dir).isDirectory())
           continue;
       } catch {
         continue;
@@ -55680,7 +55717,7 @@ var init_home_adoption = __esm(() => {
 });
 
 // src/lib/home-census.ts
-import { existsSync as existsSync25, readFileSync as readFileSync22, readdirSync as readdirSync12, statSync as statSync12 } from "fs";
+import { existsSync as existsSync25, readFileSync as readFileSync22, readdirSync as readdirSync12, statSync as statSync13 } from "fs";
 import { homedir as homedir7 } from "os";
 import { join as join28 } from "path";
 function sortEntries(entries) {
@@ -55725,7 +55762,7 @@ function censusHomeDrift(options = {}) {
         continue;
       const dir = join28(home, skill);
       try {
-        if (!statSync12(dir).isDirectory())
+        if (!statSync13(dir).isDirectory())
           continue;
       } catch {
         continue;
@@ -55978,7 +56015,7 @@ var exports_diagnostic = {};
 __export(exports_diagnostic, {
   registerDiagnostic: () => registerDiagnostic
 });
-import { existsSync as existsSync26, readFileSync as readFileSync24, readdirSync as readdirSync13, statSync as statSync13 } from "fs";
+import { existsSync as existsSync26, readFileSync as readFileSync24, readdirSync as readdirSync13, statSync as statSync14 } from "fs";
 import { join as join29 } from "path";
 import { execSync as execSync2 } from "child_process";
 function registerDiagnostic(parent) {
@@ -56171,7 +56208,7 @@ function handleWhoami(options) {
     let skillCount = 0;
     if (exists)
       try {
-        skillCount = readdirSync13(agentSkillsPath).filter((f) => !f.startsWith(".") && statSync13(join29(agentSkillsPath, f)).isDirectory()).length;
+        skillCount = readdirSync13(agentSkillsPath).filter((f) => !f.startsWith(".") && statSync14(join29(agentSkillsPath, f)).isDirectory()).length;
       } catch {}
     agentConfigs.push({ agent, label: AGENT_LABELS[agent], path: agentSkillsPath, exists, skillCount });
   }
@@ -56758,7 +56795,7 @@ var init_runs = __esm(() => {
 
 // src/lib/run-state.ts
 import { createHash as createHash9, randomBytes } from "crypto";
-import { existsSync as existsSync27, mkdirSync as mkdirSync13, readFileSync as readFileSync25, readdirSync as readdirSync14, statSync as statSync14, writeFileSync as writeFileSync14 } from "fs";
+import { existsSync as existsSync27, mkdirSync as mkdirSync13, readFileSync as readFileSync25, readdirSync as readdirSync14, statSync as statSync15, writeFileSync as writeFileSync14 } from "fs";
 import { extname, join as join31, relative as relative5 } from "path";
 function createSkillRun(params, targetDir = process.cwd()) {
   const now3 = new Date;
@@ -56840,7 +56877,7 @@ function listSkillRuns(targetDir = process.cwd(), limit = 50) {
   const records = [];
   for (const day of readdirSync14(runsRoot).sort().reverse()) {
     const dayDir = join31(runsRoot, day);
-    if (!statSync14(dayDir).isDirectory())
+    if (!statSync15(dayDir).isDirectory())
       continue;
     for (const runId2 of readdirSync14(dayDir).sort().reverse()) {
       const record4 = readRunRecord(join31(dayDir, runId2));
@@ -56889,7 +56926,7 @@ function collectRunArtifacts(context) {
     return [];
   const artifacts = [];
   for (const path of walkFiles(context.exportDir)) {
-    const stat = statSync14(path);
+    const stat = statSync15(path);
     const bytes = readFileSync25(path);
     artifacts.push({
       path: toProjectRelative(context.targetDir, path),
@@ -56914,7 +56951,7 @@ function walkFiles(dir) {
   const files = [];
   for (const entry of readdirSync14(dir)) {
     const full = join31(dir, entry);
-    if (statSync14(full).isDirectory())
+    if (statSync15(full).isDirectory())
       files.push(...walkFiles(full));
     else
       files.push(full);
@@ -74823,7 +74860,7 @@ var init_run_routing = __esm(() => {
 });
 
 // src/mcp/operation-tools.ts
-import { existsSync as existsSync28, readdirSync as readdirSync15, statSync as statSync15 } from "fs";
+import { existsSync as existsSync28, readdirSync as readdirSync15, statSync as statSync16 } from "fs";
 import { join as join32 } from "path";
 function registerOperationTools(server) {
   server.registerTool("scaffold_skill", {
@@ -75282,7 +75319,7 @@ function registerOperationTools(server) {
         try {
           skillCount = readdirSync15(agentSkillsPath).filter((f) => {
             const full = join32(agentSkillsPath, f);
-            return !f.startsWith(".") && statSync15(full).isDirectory();
+            return !f.startsWith(".") && statSync16(full).isDirectory();
           }).length;
         } catch {}
       }
@@ -75869,7 +75906,7 @@ import {
   mkdirSync as mkdirSync16,
   readFileSync as readFileSync27,
   readdirSync as readdirSync16,
-  statSync as statSync16,
+  statSync as statSync17,
   writeFileSync as writeFileSync16
 } from "fs";
 import { dirname as dirname12, join as join35, normalize as normalize3, relative as relative6, sep as sep4 } from "path";
@@ -75995,7 +76032,7 @@ function walkFiles2(dir) {
   const files = [];
   for (const entry of readdirSync16(dir)) {
     const full = join35(dir, entry);
-    const stats = statSync16(full);
+    const stats = statSync17(full);
     if (stats.isDirectory())
       files.push(...walkFiles2(full));
     else
@@ -77924,7 +77961,7 @@ function registerRuntime(parent) {
       try {
         const client = await CloudExecutionClient.configured();
         const value = operation === "show" ? await client.get(id) : await client[operation](id);
-        console.log(JSON.stringify(value, null, 2));
+        await writeCliOutput(JSON.stringify(value, null, 2));
       } catch (error2) {
         console.error(JSON.stringify({ error: error2.message }));
         process.exitCode = 1;
@@ -78260,9 +78297,9 @@ async function handleRun(name, args2, options) {
           throw new Error("Selected local execution accepts arguments and structured --input only");
         const result4 = await executeSelectedLocal(selected, { args: args2, input, cwd: process.cwd() });
         if (options.json)
-          console.log(JSON.stringify(result4, null, 2));
+          await writeCliOutput(JSON.stringify(result4, null, 2));
         else {
-          process.stdout.write(result4.stdout);
+          await writeCliOutput(result4.stdout, false);
           process.stderr.write(result4.stderr);
           console.error(JSON.stringify({ selection: result4.selection, target: result4.target, exitCode: result4.exitCode, runDirectory: result4.runDirectory }));
         }
@@ -78281,7 +78318,7 @@ async function handleRun(name, args2, options) {
       if (options.wait)
         console.error(JSON.stringify({ executionId: admitted.id, status: admitted.status }));
       const result3 = options.wait ? await client2.wait(admitted.id, { timeoutMs, intervalMs }) : admitted;
-      console.log(JSON.stringify(result3, null, 2));
+      await writeCliOutput(JSON.stringify(result3, null, 2));
       if (["failed", "cancelled"].includes(result3.status))
         process.exitCode = 1;
     } catch (error2) {
@@ -78484,7 +78521,7 @@ async function handleRun(name, args2, options) {
     console.log(JSON.stringify({ skill: skill.name, args: args2, ...result2, run: completed }, null, 2));
   else {
     if (result2.stdout)
-      process.stdout.write(result2.stdout);
+      await writeCliOutput(result2.stdout, false);
     if (result2.stderr)
       process.stderr.write(result2.stderr);
     if (result2.error)
@@ -79110,7 +79147,7 @@ var init_completion = __esm(() => {
 });
 
 // src/lib/portable-snapshot-filter.ts
-import { readdirSync as readdirSync17, statSync as statSync17 } from "fs";
+import { readdirSync as readdirSync17, statSync as statSync18 } from "fs";
 import { homedir as homedir9 } from "os";
 import { join as join40, sep as sep5 } from "path";
 function isExcludedSkillFileName(fileName) {
@@ -79178,7 +79215,7 @@ function walkEntries(absoluteRoot) {
 }
 function isRegularFile(filePath) {
   try {
-    return statSync17(filePath).isFile();
+    return statSync18(filePath).isFile();
   } catch {
     return false;
   }
@@ -79264,7 +79301,7 @@ import {
   copyFileSync as copyFileSync2,
   mkdirSync as mkdirSync21,
   readFileSync as readFileSync31,
-  statSync as statSync18,
+  statSync as statSync19,
   writeFileSync as writeFileSync21
 } from "fs";
 import { dirname as dirname17, isAbsolute as isAbsolute8, relative as relative7, resolve as resolve9, sep as sep6 } from "path";
@@ -79304,7 +79341,7 @@ function scanHome(definition, homesRoot) {
       skipped.push({ relativePath: entry.relativePath, reason: "not-regular-file" });
       continue;
     }
-    const info = statSync18(entry.fullPath);
+    const info = statSync19(entry.fullPath);
     portable.push({
       relativePath: entry.relativePath,
       fullPath: entry.fullPath,
@@ -79856,15 +79893,15 @@ function agents(value) {
 }
 function registerAgentIntegration(parent) {
   const hook = parent.command("hook").description("Load selected Skills context through agent lifecycle hooks");
-  hook.command("install").option("--agent <agent>", "Agent to configure: claude, codex, all", "all").option("--command <path>", "Skills executable used by the hook", "skills").option("--selection-profile <id>", "Shared selection profile", "default").option("--include-vendor", "Also disable discovered vendor system skills in Codex", false).option("--allow-root-aliases", "Allow home .claude/.codex aliases to existing directories within this home", false).option("--apply", "Apply the plan, preserving prior configuration in private backups", false).option("--json", "Output a receipt as JSON", false).description("Plan or install prompt hooks and disable native skill invocation").action((options) => {
+  hook.command("install").option("--agent <agent>", "Agent to configure: claude, codex, all", "all").option("--command <path>", "Skills executable used by the hook", "skills").option("--selection-profile <id>", "Shared selection profile", "default").option("--include-vendor", "Also disable discovered vendor system skills in Codex", false).option("--allow-root-aliases", "Allow home .claude/.codex aliases to existing directories within this home", false).option("--apply", "Apply the plan, preserving prior configuration in private backups", false).option("--json", "Output a receipt as JSON", false).description("Plan or install prompt hooks and disable native skill invocation").action(async (options) => {
     try {
       const plan = planAgentIntegration({ agents: agents(options.agent), command: options.command, profileId: options.selectionProfile, includeVendor: options.includeVendor, allowRootAliases: options.allowRootAliases });
       const result2 = options.apply ? applyAgentIntegration(plan) : { changed: [], backups: [] };
       const receipt = { applied: options.apply, planned: plan.changes.map((change) => change.path), ...result2, rootAliases: plan.rootAliases ?? [], nativeSkills: plan.nativeSkills.map((entry) => ({ agent: entry.agent, path: entry.path, managed: entry.managed, vendor: entry.vendor })) };
       if (options.json)
-        console.log(JSON.stringify(receipt));
+        await writeCliOutput(JSON.stringify(receipt));
       else
-        console.log(`${options.apply ? "Configured" : "Planned"} ${plan.changes.length} agent configuration change(s).${options.apply ? " Restart the agent and trust the installed hook configuration." : " Use --apply to install."}`);
+        await writeCliOutput(`${options.apply ? "Configured" : "Planned"} ${plan.changes.length} agent configuration change(s).${options.apply ? " Restart the agent and trust the installed hook configuration." : " Use --apply to install."}`);
     } catch (error2) {
       console.error(error2.message);
       process.exitCode = 1;
@@ -79906,29 +79943,29 @@ function registerAgentIntegration(parent) {
         const result2 = JSON.parse(stdout);
         if (typeof result2.context !== "string")
           throw new Error("Invalid Skills context response");
-        console.log(JSON.stringify(hookContextOutput(event, result2)));
+        await writeCliOutput(JSON.stringify(hookContextOutput(event, result2)));
       } finally {
         clearTimeout(timer);
       }
     } catch {
       const reason = "Skills context is unavailable. Run skills sync --selection-profile <id> and skills context --stdin --json to diagnose the selected profile.";
       if (event === "UserPromptSubmit")
-        console.log(JSON.stringify({ decision: "block", reason }));
+        await writeCliOutput(JSON.stringify({ decision: "block", reason }));
       else if (event === "SessionStart")
-        console.log(JSON.stringify({ continue: false, stopReason: reason, systemMessage: reason }));
+        await writeCliOutput(JSON.stringify({ continue: false, stopReason: reason, systemMessage: reason }));
       else
-        console.log(JSON.stringify({ systemMessage: reason, hookSpecificOutput: { hookEventName: "SubagentStart", additionalContext: "Required Skills context was unavailable. Report this to the parent before performing task actions." } }));
+        await writeCliOutput(JSON.stringify({ systemMessage: reason, hookSpecificOutput: { hookEventName: "SubagentStart", additionalContext: "Required Skills context was unavailable. Report this to the parent before performing task actions." } }));
     }
   });
   const migrate = parent.command("migrate").description("Preserve and retire native agent skill copies");
-  migrate.command("native").option("--project <directory>", "Also inventory native skills in a project directory").option("--include-unmanaged", "Archive user-authored skills as well as Skills-managed copies", false).option("--allow-root-aliases", "Allow home .claude/.codex aliases to existing directories within this home", false).option("--apply", "Move selected skills to private archives outside agent discovery roots", false).option("--json", "Output inventory and archive receipt as JSON", false).description("Inventory native skill copies; preserve complete directories before retiring them").action((options) => {
+  migrate.command("native").option("--project <directory>", "Also inventory native skills in a project directory").option("--include-unmanaged", "Archive user-authored skills as well as Skills-managed copies", false).option("--allow-root-aliases", "Allow home .claude/.codex aliases to existing directories within this home", false).option("--apply", "Move selected skills to private archives outside agent discovery roots", false).option("--json", "Output inventory and archive receipt as JSON", false).description("Inventory native skill copies; preserve complete directories before retiring them").action(async (options) => {
     try {
       const inventory = inventoryNativeSkills(undefined, { projectDir: options.project, allowRootAliases: options.allowRootAliases });
       const result2 = options.apply ? archiveNativeSkills(inventory, { includeUnmanaged: options.includeUnmanaged, allowRootAliases: options.allowRootAliases }) : { entries: [] };
       if (options.json)
-        console.log(JSON.stringify({ applied: options.apply, inventory, ...result2 }));
+        await writeCliOutput(JSON.stringify({ applied: options.apply, inventory, ...result2 }));
       else
-        console.log(`${inventory.length} native skill(s) found; ${result2.entries.length} archived with recovery receipts.${options.apply ? "" : " Use --apply to archive managed copies."}`);
+        await writeCliOutput(`${inventory.length} native skill(s) found; ${result2.entries.length} archived with recovery receipts.${options.apply ? "" : " Use --apply to archive managed copies."}`);
     } catch (error2) {
       console.error(error2.message);
       process.exitCode = 1;
@@ -80008,7 +80045,7 @@ function registerProfiles(parent) {
       if (options.save)
         writeFileSync22(options.save, `${text2}
 `, { mode: 384, flag: "wx" });
-      console.log(options.json ? text2 : `${profile.id} at ${profile.revision}: ${profile.selections.map((skill) => `${skill.slug}@${skill.version}`).join(", ")}`);
+      await writeCliOutput(options.json ? text2 : `${profile.id} at ${profile.revision}: ${profile.selections.map((skill) => `${skill.slug}@${skill.version}`).join(", ")}`);
     } catch (error2) {
       console.error(error2.message);
       process.exitCode = 1;
@@ -80021,7 +80058,7 @@ function registerProfiles(parent) {
         throw new Error("Profile input exceeds the size limit");
       const input = JSON.parse(text2);
       const profile = await saveSkillProfile(id2, input.selections, options.ifMatch);
-      console.log(options.json ? JSON.stringify(profile) : `Saved ${profile.id} at ${profile.revision}`);
+      await writeCliOutput(options.json ? JSON.stringify(profile) : `Saved ${profile.id} at ${profile.revision}`);
     } catch (error2) {
       console.error(error2.message);
       process.exitCode = 1;
@@ -80029,7 +80066,7 @@ function registerProfiles(parent) {
   });
   parent.command("station-state <id>").description("Read this actor's last applied skill selection on a station").option("--json", "Output the station receipt as JSON", false).action(async (id2) => {
     try {
-      console.log(JSON.stringify(await readStationSkillState(id2), null, 2));
+      await writeCliOutput(JSON.stringify(await readStationSkillState(id2), null, 2));
     } catch (error2) {
       console.error(error2.message);
       process.exitCode = 1;
@@ -80047,7 +80084,7 @@ import {
   mkdirSync as mkdirSync22,
   readdirSync as readdirSync18,
   readFileSync as readFileSync34,
-  statSync as statSync19,
+  statSync as statSync20,
   writeFileSync as writeFileSync23
 } from "fs";
 import { dirname as dirname18, join as join42, resolve as resolve10, sep as sep7 } from "path";
@@ -80144,7 +80181,7 @@ function planStationHydration(stationId, repoRoot) {
           });
           continue;
         }
-        const info = statSync19(entry.fullPath);
+        const info = statSync20(entry.fullPath);
         const manifestHash = manifestHashes.get(`${agent}${MANIFEST_HASH_KEY_SEP}${homeRelative}`) ?? null;
         let verified = false;
         if (manifestHash !== null) {
@@ -82707,11 +82744,11 @@ var init_storage = __esm(() => {
 });
 
 // src/lib/registry-reconcile.ts
-import { existsSync as existsSync35, readFileSync as readFileSync36, statSync as statSync20, writeFileSync as writeFileSync25 } from "fs";
+import { existsSync as existsSync35, readFileSync as readFileSync36, statSync as statSync21, writeFileSync as writeFileSync25 } from "fs";
 import { join as join44 } from "path";
 function isDirectory2(path) {
   try {
-    return statSync20(path).isDirectory();
+    return statSync21(path).isDirectory();
   } catch {
     return false;
   }
@@ -83147,7 +83184,6 @@ var init_registry_reconcile2 = __esm(() => {
   init_selection_cache();
   init_registry_reconcile();
 });
-
 // ../../node_modules/.bun/ink@5.2.1+6e93904c7bfe2418/node_modules/ink/build/render.js
 import { Stream } from "stream";
 import process12 from "process";
@@ -90963,8 +90999,8 @@ program2.command("interactive", { isDefault: true }).alias("i").allowExcessArgum
     process.exit(1);
   }
   if (!isTTY2) {
-    console.log(JSON.stringify(loadBasicRegistry().map(getCompactSkillDiscovery)));
-    process.exit(0);
+    await writeCliOutput(JSON.stringify(loadBasicRegistry().map(getCompactSkillDiscovery)));
+    return;
   }
   render_default(/* @__PURE__ */ jsx_dev_runtime7.jsxDEV(App2, {}, undefined, false, undefined, this));
 });

package/bin/mcp.js

@@ -5586,7 +5586,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.6.0",
+    version: "0.6.2",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -26973,7 +26973,6 @@ var init_selection_resolver = __esm(() => {
   init_selected_document();
   init_selection_cache();
 });
-
 // src/lib/skill-context.ts
 var init_skill_context = __esm(() => {
   init_selection_resolver();

package/bin/migrate.js

@@ -7,7 +7,7 @@ import { join as join6 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.6.0",
+  version: "0.6.2",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

@@ -23100,7 +23100,7 @@ var init_dist_es9 = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.6.0",
+  version: "0.6.2",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

@@ -23103,7 +23103,7 @@ import { randomUUID as randomUUID5 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.6.0",
+  version: "0.6.2",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/cli/commands/runtime.d.ts

@@ -1,5 +1,2 @@
-/**
- * run / mcp / self-update — runtime commands
- */
 import type { Command } from "commander";
 export declare function registerRuntime(parent: Command): void;

package/dist/cli/output.d.ts

@@ -0,0 +1,2 @@
+/** Finish pipe writes before an async command returns, including under backpressure. */
+export declare function writeCliOutput(text: string, newline?: boolean): Promise<void>;

package/dist/index.js

@@ -3493,7 +3493,7 @@ import {
   readdirSync as readdirSync8,
   renameSync as renameSync3,
   rmSync as rmSync2,
-  statSync as statSync7,
+  statSync as statSync8,
   writeFileSync as writeFileSync5
 } from "fs";
 import { homedir as homedir3 } from "os";
@@ -3501,7 +3501,7 @@ import { basename as basename3, dirname as dirname5, join as join10 } from "path
 
 // src/lib/agent-integration.ts
 import { createHash as createHash2, randomUUID } from "crypto";
-import { existsSync as existsSync9, lstatSync as lstatSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync7, readdirSync as readdirSync7, readlinkSync, realpathSync as realpathSync3, renameSync as renameSync2, writeFileSync as writeFileSync4, unlinkSync, chmodSync } from "fs";
+import { existsSync as existsSync9, lstatSync as lstatSync3, statSync as statSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync7, readdirSync as readdirSync7, readlinkSync, realpathSync as realpathSync3, renameSync as renameSync2, writeFileSync as writeFileSync4, unlinkSync, chmodSync } from "fs";
 import { dirname as dirname4, join as join9, resolve as resolve3, relative as relative3, isAbsolute as isAbsolute3, sep as sep3 } from "path";
 import { homedir as homedir2 } from "os";
 var sha = (data) => createHash2("sha256").update(data).digest("hex");
@@ -3600,15 +3600,27 @@ function inventoryNativeSkills(home = homedir2(), options = {}) {
     for (const [agent, path] of ROOTS)
       roots.push([agent, join9(resolve3(options.projectDir), path)]);
   const entries = [], seen = new Set;
-  function visit(agent, path, vendor = false, depth = 0) {
+  const cacheScans = new Map, maxAliasProofEntries = 1e4;
+  function emptySiblingCacheAlias(path, parent) {
+    const link = readlinkSync(path), target = resolve3(parent, link);
+    if (dirname4(target) !== parent || (isAbsolute3(link) ? link !== target : dirname4(link) !== "."))
+      return false;
+    if (!lstatSync3(target, { throwIfNoEntry: false })?.isDirectory())
+      return false;
+    const scan = cacheScans.get(target);
+    return Boolean(scan?.complete && !scan.hasSkills && scan.entries <= maxAliasProofEntries);
+  }
+  function visit(agent, path, vendor = false, depth = 0, pluginCache = false) {
+    const scan = { complete: true, hasSkills: false, entries: 1 };
     assertSafePath(path);
     if (!existsSync9(path))
-      return;
+      return scan;
     if (!lstatSync3(path).isDirectory())
-      return;
+      return scan;
     if (existsSync9(join9(path, "SKILL.md"))) {
+      scan.hasSkills = true;
       if (seen.has(path))
-        return;
+        return scan;
       seen.add(path);
       let managed = false;
       const marker = join9(path, ".hasna-skills.json");
@@ -3619,11 +3631,14 @@ function inventoryNativeSkills(home = homedir2(), options = {}) {
       }
       const rootAlias = aliases.find((item) => path === item.target || path.startsWith(item.target + sep3));
       entries.push({ agent, path, hash: treeHash(path), managed, vendor, ...rootAlias ? { rootAlias } : {} });
-      return;
+      return scan;
     }
     if (depth > (vendor ? 8 : 3))
-      return;
-    for (const name of readdirSync7(path).sort()) {
+      return { ...scan, complete: false };
+    const children = readdirSync7(path, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    if (pluginCache)
+      children.sort((a, b) => Number(a.isSymbolicLink()) - Number(b.isSymbolicLink()));
+    for (const { name } of children) {
       if (name === "node_modules")
         continue;
       if (name.startsWith(".") && name !== ".system")
@@ -3631,14 +3646,28 @@ function inventoryNativeSkills(home = homedir2(), options = {}) {
       const isVendor = vendor || name === ".system";
       if (isVendor && !options.includeVendor)
         continue;
-      visit(agent, join9(path, name), isVendor, depth + 1);
+      const child = join9(path, name);
+      if (isVendor && lstatSync3(child, { throwIfNoEntry: false })?.isSymbolicLink()) {
+        const target = statSync7(child, { throwIfNoEntry: false });
+        if (target?.isFile() || pluginCache && target?.isDirectory() && emptySiblingCacheAlias(child, path)) {
+          scan.entries++;
+          continue;
+        }
+      }
+      const childScan = visit(agent, child, isVendor, depth + 1, pluginCache);
+      scan.complete &&= childScan.complete;
+      scan.hasSkills ||= childScan.hasSkills;
+      scan.entries += childScan.entries;
     }
+    if (pluginCache)
+      cacheScans.set(path, scan);
+    return scan;
   }
   for (const [agent, path] of roots)
     visit(agent, path);
   if (options.includeVendor) {
     for (const agent of ["codex", "claude"])
-      visit(agent, canonicalAgentPath(join9(home, `.${agent}`, "plugins", "cache"), aliases), true);
+      visit(agent, canonicalAgentPath(join9(home, `.${agent}`, "plugins", "cache"), aliases), true, 0, true);
   }
   recheckRootAliases(aliases);
   return entries;
@@ -3963,7 +3992,7 @@ function containsSkillDirectories(path) {
 }
 function isDirectory(path) {
   try {
-    return statSync7(path).isDirectory();
+    return statSync8(path).isDirectory();
   } catch {
     return false;
   }
@@ -4594,7 +4623,7 @@ function loadProjectConfigCompat(targetDir) {
 }
 // src/lib/run-state.ts
 import { createHash as createHash3, randomBytes } from "crypto";
-import { existsSync as existsSync13, mkdirSync as mkdirSync7, readFileSync as readFileSync11, readdirSync as readdirSync9, statSync as statSync8, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync13, mkdirSync as mkdirSync7, readFileSync as readFileSync11, readdirSync as readdirSync9, statSync as statSync9, writeFileSync as writeFileSync7 } from "fs";
 import { extname, join as join13, relative as relative4 } from "path";
 function createSkillRun(params, targetDir = process.cwd()) {
   const now = new Date;
@@ -4676,7 +4705,7 @@ function listSkillRuns(targetDir = process.cwd(), limit = 50) {
   const records = [];
   for (const day of readdirSync9(runsRoot).sort().reverse()) {
     const dayDir = join13(runsRoot, day);
-    if (!statSync8(dayDir).isDirectory())
+    if (!statSync9(dayDir).isDirectory())
       continue;
     for (const runId of readdirSync9(dayDir).sort().reverse()) {
       const record = readRunRecord(join13(dayDir, runId));
@@ -4715,7 +4744,7 @@ function collectRunArtifacts(context) {
     return [];
   const artifacts = [];
   for (const path of walkFiles(context.exportDir)) {
-    const stat = statSync8(path);
+    const stat = statSync9(path);
     const bytes = readFileSync11(path);
     artifacts.push({
       path: toProjectRelative(context.targetDir, path),
@@ -4740,7 +4769,7 @@ function walkFiles(dir) {
   const files = [];
   for (const entry of readdirSync9(dir)) {
     const full = join13(dir, entry);
-    if (statSync8(full).isDirectory())
+    if (statSync9(full).isDirectory())
       files.push(...walkFiles(full));
     else
       files.push(full);
@@ -12614,7 +12643,7 @@ import { dirname as dirname7, join as join18 } from "path";
 
 // src/lib/skill-bundle.ts
 import { createHash as createHash6 } from "crypto";
-import { readFileSync as readFileSync15, readdirSync as readdirSync10, statSync as statSync9 } from "fs";
+import { readFileSync as readFileSync15, readdirSync as readdirSync10, statSync as statSync10 } from "fs";
 import { join as join17, relative as relative5 } from "path";
 import { createGunzip } from "zlib";
 var BLOCK = 512;
@@ -12798,7 +12827,7 @@ function walk(root, current, out) {
       continue;
     if (isCredentialFile(entry.name))
       continue;
-    const stats = statSync9(absolute);
+    const stats = statSync10(absolute);
     out.push({
       path: rel,
       bytes: ownBytes(readFileSync15(absolute)),
@@ -13710,7 +13739,7 @@ import { dirname as dirname8, relative as relative6 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.6.0",
+  version: "0.6.2",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -15031,7 +15060,7 @@ import {
   mkdirSync as mkdirSync12,
   readFileSync as readFileSync17,
   readdirSync as readdirSync11,
-  statSync as statSync10,
+  statSync as statSync11,
   writeFileSync as writeFileSync11
 } from "fs";
 import { dirname as dirname10, join as join20, normalize as normalize3, relative as relative7, sep as sep4 } from "path";
@@ -15529,7 +15558,7 @@ function walkFiles2(dir) {
   const files = [];
   for (const entry of readdirSync11(dir)) {
     const full = join20(dir, entry);
-    const stats = statSync10(full);
+    const stats = statSync11(full);
     if (stats.isDirectory())
       files.push(...walkFiles2(full));
     else
@@ -15615,13 +15644,13 @@ import {
   copyFileSync as copyFileSync2,
   mkdirSync as mkdirSync13,
   readFileSync as readFileSync18,
-  statSync as statSync12,
+  statSync as statSync13,
   writeFileSync as writeFileSync12
 } from "fs";
 import { dirname as dirname11, isAbsolute as isAbsolute5, relative as relative8, resolve as resolve4, sep as sep6 } from "path";
 
 // src/lib/portable-snapshot-filter.ts
-import { readdirSync as readdirSync12, statSync as statSync11 } from "fs";
+import { readdirSync as readdirSync12, statSync as statSync12 } from "fs";
 import { homedir as homedir5 } from "os";
 import { join as join21, sep as sep5 } from "path";
 var SYNC_HOMES = [
@@ -15759,7 +15788,7 @@ function walkEntries(absoluteRoot) {
 }
 function isRegularFile(filePath) {
   try {
-    return statSync11(filePath).isFile();
+    return statSync12(filePath).isFile();
   } catch {
     return false;
   }
@@ -15815,7 +15844,7 @@ function scanHome(definition, homesRoot) {
       skipped.push({ relativePath: entry.relativePath, reason: "not-regular-file" });
       continue;
     }
-    const info = statSync12(entry.fullPath);
+    const info = statSync13(entry.fullPath);
     portable.push({
       relativePath: entry.relativePath,
       fullPath: entry.fullPath,
@@ -15942,7 +15971,7 @@ import {
   mkdirSync as mkdirSync14,
   readdirSync as readdirSync13,
   readFileSync as readFileSync19,
-  statSync as statSync13,
+  statSync as statSync14,
   writeFileSync as writeFileSync13
 } from "fs";
 import { dirname as dirname12, join as join22, resolve as resolve5, sep as sep7 } from "path";
@@ -16042,7 +16071,7 @@ function planStationHydration(stationId, repoRoot) {
           });
           continue;
         }
-        const info = statSync13(entry.fullPath);
+        const info = statSync14(entry.fullPath);
         const manifestHash = manifestHashes.get(`${agent}${MANIFEST_HASH_KEY_SEP}${homeRelative}`) ?? null;
         let verified = false;
         if (manifestHash !== null) {

package/dist/sdk/index.js

@@ -24427,7 +24427,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.6.0",
+  version: "0.6.2",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -38174,7 +38174,7 @@ import {
   readdirSync as readdirSync9,
   renameSync as renameSync3,
   rmSync as rmSync2,
-  statSync as statSync8,
+  statSync as statSync9,
   writeFileSync as writeFileSync5
 } from "fs";
 import { homedir as homedir4 } from "os";
@@ -38182,7 +38182,7 @@ import { basename as basename3, dirname as dirname9, join as join15 } from "path
 
 // src/lib/agent-integration.ts
 import { createHash as createHash7, randomUUID as randomUUID5 } from "crypto";
-import { existsSync as existsSync4, lstatSync as lstatSync2, mkdirSync as mkdirSync4, readFileSync as readFileSync6, readdirSync as readdirSync4, readlinkSync, realpathSync, renameSync, writeFileSync as writeFileSync2, unlinkSync, chmodSync } from "fs";
+import { existsSync as existsSync4, lstatSync as lstatSync2, statSync as statSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync6, readdirSync as readdirSync4, readlinkSync, realpathSync, renameSync, writeFileSync as writeFileSync2, unlinkSync, chmodSync } from "fs";
 import { dirname as dirname6, join as join9, resolve as resolve2, relative as relative2, isAbsolute as isAbsolute3, sep } from "path";
 import { homedir as homedir3 } from "os";
 var sha = (data) => createHash7("sha256").update(data).digest("hex");
@@ -38281,15 +38281,27 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
     for (const [agent, path] of ROOTS)
       roots.push([agent, join9(resolve2(options.projectDir), path)]);
   const entries = [], seen = new Set;
-  function visit(agent, path, vendor = false, depth = 0) {
+  const cacheScans = new Map, maxAliasProofEntries = 1e4;
+  function emptySiblingCacheAlias(path, parent) {
+    const link = readlinkSync(path), target = resolve2(parent, link);
+    if (dirname6(target) !== parent || (isAbsolute3(link) ? link !== target : dirname6(link) !== "."))
+      return false;
+    if (!lstatSync2(target, { throwIfNoEntry: false })?.isDirectory())
+      return false;
+    const scan = cacheScans.get(target);
+    return Boolean(scan?.complete && !scan.hasSkills && scan.entries <= maxAliasProofEntries);
+  }
+  function visit(agent, path, vendor = false, depth = 0, pluginCache = false) {
+    const scan = { complete: true, hasSkills: false, entries: 1 };
     assertSafePath(path);
     if (!existsSync4(path))
-      return;
+      return scan;
     if (!lstatSync2(path).isDirectory())
-      return;
+      return scan;
     if (existsSync4(join9(path, "SKILL.md"))) {
+      scan.hasSkills = true;
       if (seen.has(path))
-        return;
+        return scan;
       seen.add(path);
       let managed = false;
       const marker = join9(path, ".hasna-skills.json");
@@ -38300,11 +38312,14 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
       }
       const rootAlias = aliases.find((item) => path === item.target || path.startsWith(item.target + sep));
       entries.push({ agent, path, hash: treeHash(path), managed, vendor, ...rootAlias ? { rootAlias } : {} });
-      return;
+      return scan;
     }
     if (depth > (vendor ? 8 : 3))
-      return;
-    for (const name of readdirSync4(path).sort()) {
+      return { ...scan, complete: false };
+    const children = readdirSync4(path, { withFileTypes: true }).sort((a3, b3) => a3.name < b3.name ? -1 : a3.name > b3.name ? 1 : 0);
+    if (pluginCache)
+      children.sort((a3, b3) => Number(a3.isSymbolicLink()) - Number(b3.isSymbolicLink()));
+    for (const { name } of children) {
       if (name === "node_modules")
         continue;
       if (name.startsWith(".") && name !== ".system")
@@ -38312,14 +38327,28 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
       const isVendor = vendor || name === ".system";
       if (isVendor && !options.includeVendor)
         continue;
-      visit(agent, join9(path, name), isVendor, depth + 1);
+      const child = join9(path, name);
+      if (isVendor && lstatSync2(child, { throwIfNoEntry: false })?.isSymbolicLink()) {
+        const target = statSync3(child, { throwIfNoEntry: false });
+        if (target?.isFile() || pluginCache && target?.isDirectory() && emptySiblingCacheAlias(child, path)) {
+          scan.entries++;
+          continue;
+        }
+      }
+      const childScan = visit(agent, child, isVendor, depth + 1, pluginCache);
+      scan.complete &&= childScan.complete;
+      scan.hasSkills ||= childScan.hasSkills;
+      scan.entries += childScan.entries;
     }
+    if (pluginCache)
+      cacheScans.set(path, scan);
+    return scan;
   }
   for (const [agent, path] of roots)
     visit(agent, path);
   if (options.includeVendor) {
     for (const agent of ["codex", "claude"])
-      visit(agent, canonicalAgentPath(join9(home, `.${agent}`, "plugins", "cache"), aliases), true);
+      visit(agent, canonicalAgentPath(join9(home, `.${agent}`, "plugins", "cache"), aliases), true, 0, true);
   }
   recheckRootAliases(aliases);
   return entries;
@@ -38532,7 +38561,7 @@ import {
   realpathSync as realpathSync3,
   renameSync as renameSync2,
   rmSync,
-  statSync as statSync7,
+  statSync as statSync8,
   writeFileSync as writeFileSync4
 } from "fs";
 import { basename as basename2, dirname as dirname8, isAbsolute as isAbsolute5, join as join14, normalize as normalize2, relative as relative4, resolve as resolve3, sep as sep3 } from "path";
@@ -39247,7 +39276,7 @@ var SKILLS = [
 ];
 
 // src/lib/hosted-skill-set.ts
-import { existsSync as existsSync5, readFileSync as readFileSync7, readdirSync as readdirSync5, statSync as statSync3 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync7, readdirSync as readdirSync5, statSync as statSync4 } from "fs";
 import { join as join10 } from "path";
 var HOSTED_RUNTIMES = new Set(["hosted"]);
 var HOSTED_SOURCES = new Set(["remote", "private-hosted"]);
@@ -39286,7 +39315,7 @@ var BRACE_SOURCE_EXCLUSION = new RegExp(`^!skills/\\{(${SLUG}(?:,${SLUG})+)\\}/s
 var SINGLE_SOURCE_EXCLUSION = new RegExp(`^!skills/(${SLUG})/src$`);
 
 // src/lib/skill-validation.ts
-import { existsSync as existsSync6, lstatSync as lstatSync3, readFileSync as readFileSync8, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
+import { existsSync as existsSync6, lstatSync as lstatSync3, readFileSync as readFileSync8, readdirSync as readdirSync6, statSync as statSync5 } from "fs";
 import { isAbsolute as isAbsolute4, join as join11, normalize } from "path";
 var VALID_SKILL_KINDS = ["executable", "instruction"];
 var DOC_FILES = ["SKILL.md", "README.md", "CLAUDE.md"];
@@ -39574,7 +39603,7 @@ function validateSkillDirectory(name, skillPath, registryMeta) {
             const targetPath = join11(skillPath, target);
             if (!existsSync6(targetPath)) {
               add(warnings, "package.bin_target_missing", `package.json bin '${command3}' target '${target}' is not present before build`);
-            } else if (statSync4(targetPath).isDirectory()) {
+            } else if (statSync5(targetPath).isDirectory()) {
               add(issues, "package.bin_target_directory", `package.json bin '${command3}' target '${target}' must point to a file, not a directory`);
             }
           }
@@ -39600,7 +39629,7 @@ function validateSkillDirectory(name, skillPath, registryMeta) {
       add(issues, "skill.src_index_missing", "Missing src/index.ts or src/index.js");
     } else {
       const indexPath = existsSync6(join11(srcDir, "index.ts")) ? join11(srcDir, "index.ts") : join11(srcDir, "index.js");
-      const size = statSync4(indexPath).size;
+      const size = statSync5(indexPath).size;
       if (size < 50)
         add(warnings, "skill.src_index_minimal", `Source entry point is very small (${size}B)`);
     }
@@ -39625,7 +39654,7 @@ function validateRegistryConsistency(registry, skillsDir) {
   })));
   const skillDirs = existsSync6(skillsDir) ? readdirSync6(skillsDir).filter((entry) => {
     const fullPath = join11(skillsDir, entry);
-    return !entry.startsWith(".") && entry !== "_common" && statSync4(fullPath).isDirectory();
+    return !entry.startsWith(".") && entry !== "_common" && statSync5(fullPath).isDirectory();
   }) : [];
   const directoryNames = new Set(skillDirs);
   const registryNameSet = new Set(registryNames);
@@ -39641,7 +39670,7 @@ function validateRegistryConsistency(registry, skillsDir) {
 
 // src/lib/skill-hash.ts
 import { createHash as createHash8 } from "crypto";
-import { existsSync as existsSync7, readdirSync as readdirSync7, readFileSync as readFileSync9, statSync as statSync5 } from "fs";
+import { existsSync as existsSync7, readdirSync as readdirSync7, readFileSync as readFileSync9, statSync as statSync6 } from "fs";
 import { join as join12, sep as sep2 } from "path";
 var CONTENT_HASH_ALGORITHM = "sha256";
 var HASH_EXCLUDE_DIRS = new Set([".git", "node_modules", "dist", "build", ".turbo"]);
@@ -39707,7 +39736,7 @@ function collectBundleFiles(skillPath) {
     const absolute = join12(skillPath, entry);
     if (!existsSync7(absolute))
       continue;
-    if (statSync5(absolute).isDirectory())
+    if (statSync6(absolute).isDirectory())
       collectDirectory(files, absolute, entry);
     else
       collectFile(files, absolute, entry);
@@ -39722,7 +39751,7 @@ function collectDirectory(files, dir, rel) {
     const childRel = `${rel}/${entry}`;
     let stats;
     try {
-      stats = statSync5(absolute);
+      stats = statSync6(absolute);
     } catch {
       continue;
     }
@@ -40871,7 +40900,7 @@ function findPortableSkill(name, options = {}) {
     return null;
   }
   const path = getPortableSkillPath(normalized, options);
-  if (!existsSync9(path) || !statSync7(path).isDirectory())
+  if (!existsSync9(path) || !statSync8(path).isDirectory())
     return null;
   try {
     return summarizePortableSkill(path, normalized);
@@ -40940,7 +40969,7 @@ function scaffoldPortableSkill(name, options = {}) {
 }
 function portPortableSkillDirectory(sourceDir, options = {}) {
   const absoluteSource = normalize2(sourceDir);
-  if (!existsSync9(absoluteSource) || !statSync7(absoluteSource).isDirectory()) {
+  if (!existsSync9(absoluteSource) || !statSync8(absoluteSource).isDirectory()) {
     throw new Error(`Import directory not found: ${sourceDir}`);
   }
   const continueOnError = options.continueOnError ?? true;
@@ -41006,7 +41035,7 @@ function assertDisjointImportPaths(source, destination) {
 }
 function portPortableSkill(sourcePath, options = {}) {
   const absoluteSource = normalize2(sourcePath);
-  if (!existsSync9(absoluteSource) || !statSync7(absoluteSource).isDirectory()) {
+  if (!existsSync9(absoluteSource) || !statSync8(absoluteSource).isDirectory()) {
     throw new Error(`Skill source directory not found: ${sourcePath}`);
   }
   const inferred = readPortableSkillManifestForImport(absoluteSource);
@@ -41170,7 +41199,7 @@ function validatePortableSkillDirectory(name, skillPath) {
             const entryPath = join14(skillPath, command3.entry);
             if (!existsSync9(entryPath))
               add3(issues, "portable.command_entry_missing", `Command '${command3.name}' entry '${command3.entry}' is missing`);
-            else if (statSync7(entryPath).isDirectory())
+            else if (statSync8(entryPath).isDirectory())
               add3(issues, "portable.command_entry_directory", `Command '${command3.name}' entry '${command3.entry}' must be a file`);
           }
         }
@@ -41260,7 +41289,7 @@ function summarizePortableSkill(skillPath, fallbackName) {
 }
 function safeIsDirectory(path) {
   try {
-    return statSync7(path).isDirectory();
+    return statSync8(path).isDirectory();
   } catch {
     return false;
   }
@@ -41400,7 +41429,7 @@ function containsSkillDirectories(path) {
 }
 function isDirectory(path) {
   try {
-    return statSync8(path).isDirectory();
+    return statSync9(path).isDirectory();
   } catch {
     return false;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {