@hasna/skills 0.8.7 → 0.8.9

package/README.md

@@ -70,6 +70,22 @@ skills hook install --agent all --selection-profile default --json
 skills hook install --agent all --selection-profile default --apply --json
 ```
 
+Native migration includes the current directory, every ancestor, and the global
+agent directories. Use `--project /path/to/project` to include another project
+and its ancestors. This matches the prompt hook's project discovery, including
+skills inherited from a parent workspace. Preview the JSON inventory before
+applying it; archived copies retain recovery receipts. A drift refusal reports
+the affected paths without printing their skill documents.
+
+Claude hook installation sets `syncClaudeAiSkills: false` in user settings to
+stop [account skill synchronization](https://code.claude.com/docs/en/skills#skills-synced-from-claudeai)
+from recreating native copies. The prompt hook checks that setting. Vendor
+migration also inventories `~/.claude/plugins/synced/` and archives its skill
+documents while preserving other plugin files. Whole-plugin synchronization
+remains unchanged because synced plugins can also provide hooks, MCP servers,
+and language servers. A later plugin download that restores a skill document
+will trigger another drift refusal and require review.
+
 Native hook invocations must use their installed adapter's selection profile.
 An old client command or environment override naming another profile refuses
 before synchronization or context loading. Review the hook installation and
@@ -178,9 +194,22 @@ Reviewed Hermes installations need fresh source and directory coverage in their
 reviewed bindings without changing existing source-only reviews.
 
 Hook installation preserves unrelated configuration, hooks, and plugin assets.
-It disables discovered Codex native skills; exact system-skill trees can remain
-only with their hash-bound disabled paths; migration preserves these package files. A client that restores or changes
-packaged skills requires a fresh inventory and disable plan. Native exports are
+For Codex it sets `skills.bundled.enabled = false` in user configuration, preserving
+the `skills-cli` bridge and disabling discovered native skill paths. This prevents
+supported Codex clients from installing or loading their bundled `.system` skills.
+The setting and its discovery witness are enrolled in the same configuration
+transaction; existing installations must rerun `skills hook install`. Missing or
+re-enabled bundled protection fails `skills hook check` before context loads.
+Ordinary `[skills.bundled]` and legacy `[[skills.config]]` tables are supported;
+inline or dotted target definitions that require rewriting refuse before changes.
+Convert those definitions to ordinary tables while preserving their values, then
+rerun installation. The control has been verified with Codex 0.153.0, 0.153.4 and
+0.154.0; this is not a claim that every older build supports it. Use a client that
+supports `skills.bundled.enabled`; Skills does not infer support from version text
+or silently substitute path-only protection. Existing exact system-skill trees can
+remain only with their hash-bound disabled paths; migration preserves these package
+files. A client that restores or changes packaged skills requires a fresh inventory
+and disable plan. Native exports are
 refused while managed CLI loading is active. Migration preserves ordinary skill
 directories in private archives; `--include-unmanaged` includes user-authored
 copies, and `--include-vendor` retires vendor `SKILL.md` discovery files while
@@ -365,6 +394,18 @@ skills grants set default --file ./reviewed-policy.json --if-match <policy-revis
 skills grants show default --revision <prior-policy-revision> --json
 ```
 
+For executable arguments, use `--` after the skill and Skills options:
+
+```bash
+skills run --target local --selection-profile default --json \
+  your-skill@1.0.0 -- prepare --input child-input.json --json
+```
+
+Everything after that separator belongs to the executable, including flags such
+as `--input`, `--json` and any further `--`. Cloud execution accepts structured
+Skills `--input` only and rejects executable arguments. Existing calls without a
+separator retain their option parsing behavior.
+
 Updating a policy appends a revision and atomically changes its current pointer.
 An empty `grants` array revokes shared execution access. Historical policies remain
 readable and can be submitted as a new reviewed revision for rollback; they cannot
@@ -603,7 +644,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills search <query>` | `s` | Search by name, description, or tags |
 | `skills info <name>` | | Show metadata, env vars, and system dependencies |
 | `skills show <name>` | | Show account or owned portable skill details |
-| `skills docs <name>` | | Show documentation (SKILL.md > README.md > CLAUDE.md) |
+| `skills docs <name>` | `--file skill\|readme\|claude` | Show preferred documentation; an explicit file must exist and unknown aliases fail |
 | `skills requires <name>` | | Show env vars, system deps, and npm dependencies |
 | `skills profiles show <id>` / `skills profiles set <id> --file <json>` | | Read an exact shared selection or update it with writer authorization |
 | `skills install [name@version] --selection-profile <id>` | | Cache selected immutable bundles; without names, sync the profile |

package/bin/index.js

@@ -36868,7 +36868,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.8.7",
+    version: "0.8.9",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -51119,6 +51119,83 @@ var init_agent_adapters = __esm(() => {
   };
 });
 
+// src/lib/agent-codex.ts
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
+function assertCodexPathConfigEditable(text2) {
+  const before2 = Bun.TOML.parse(text2);
+  if (before2.skills?.config === undefined)
+    return;
+  const expected = structuredClone(before2);
+  delete expected.skills.config;
+  try {
+    const withoutSections = Bun.TOML.parse(text2.replace(CODEX_SKILL_CONFIG_SECTIONS, ""));
+    if (isDeepStrictEqual2(withoutSections, expected))
+      return;
+  } catch {}
+  throw new Error("Codex skill path controls require ordinary [[skills.config]] TOML tables; preserve and convert inline or dotted config arrays before running skills hook install");
+}
+function disableCodexBundledSkills(text2) {
+  const before2 = Bun.TOML.parse(text2);
+  const table = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
+  const refuse = () => new Error("Codex bundled skills configuration requires ordinary [skills.bundled] TOML with a boolean enabled setting; preserve and convert inline or dotted definitions before running skills hook install");
+  if (before2.skills !== undefined && !table(before2.skills))
+    throw refuse();
+  if (before2.skills?.bundled !== undefined && !table(before2.skills.bundled))
+    throw refuse();
+  if (before2.skills !== undefined) {
+    let root = before2, attempts = 0;
+    for (const header of text2.matchAll(/^[ \t]*\[/gm)) {
+      if (++attempts > 256)
+        throw refuse();
+      try {
+        root = Bun.TOML.parse(text2.slice(0, header.index));
+        break;
+      } catch {}
+    }
+    if (root.skills !== undefined)
+      throw refuse();
+  }
+  const enabled = before2.skills?.bundled?.enabled;
+  if (enabled !== undefined && typeof enabled !== "boolean")
+    throw refuse();
+  if (enabled === false)
+    return text2;
+  const expected = structuredClone(before2);
+  expected.skills ??= {};
+  expected.skills.bundled ??= {};
+  expected.skills.bundled.enabled = false;
+  const candidates = new Set;
+  const consider = (candidate) => {
+    try {
+      if (isDeepStrictEqual2(Bun.TOML.parse(candidate), expected))
+        candidates.add(candidate);
+    } catch {}
+  };
+  const newline = text2.includes(`\r
+`) ? `\r
+` : `
+`;
+  if (before2.skills?.bundled !== undefined) {
+    for (const section of text2.matchAll(/^[ \t]*\[skills\.bundled\][ \t]*(?:#[^\r\n]*)?(?:\r?\n|$)(?:(?![ \t]*\[)[^\n]*(?:\n|$))*/gm)) {
+      const headerEnd = section[0].indexOf(`
+`) + 1 || section[0].length;
+      const replacement = enabled === true ? section[0].replace(/^([ \t]*enabled[ \t]*=[ \t]*)true([ \t]*(?:#[^\r\n]*)?)(\r?)$/m, "$1false$2$3") : section[0].slice(0, headerEnd) + (section[0].slice(0, headerEnd).endsWith(`
+`) ? "" : newline) + `enabled = false${newline}` + section[0].slice(headerEnd);
+      consider(text2.slice(0, section.index) + replacement + text2.slice(section.index + section[0].length));
+    }
+  } else {
+    consider(`${text2}${text2.endsWith(`
+`) || !text2 ? "" : newline}${newline}[skills.bundled]${newline}enabled = false${newline}`);
+  }
+  if (candidates.size !== 1)
+    throw refuse();
+  return [...candidates][0];
+}
+var CODEX_SKILL_CONFIG_SECTIONS;
+var init_agent_codex = __esm(() => {
+  CODEX_SKILL_CONFIG_SECTIONS = /^\[\[skills\.config\]\][^\n]*(?:\n(?!\s*\[)[^\n]*)*/gm;
+});
+
 // src/lib/agent-integration.ts
 import { createHash as createHash9, randomUUID as randomUUID5 } from "crypto";
 import { existsSync as existsSync14, lstatSync as lstatSync11, statSync as statSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync12, readdirSync as readdirSync9, opendirSync as opendirSync3, readlinkSync as readlinkSync2, realpathSync as realpathSync4, renameSync as renameSync3, rmdirSync, writeFileSync as writeFileSync5, unlinkSync as unlinkSync2, chmodSync, openSync as openSync4, closeSync as closeSync4, fsyncSync, fstatSync as fstatSync4, readSync as readSync4, constants as constants5, linkSync } from "fs";
@@ -51228,11 +51305,26 @@ function treeHash(root) {
   visit2(root);
   return hash2.digest("hex");
 }
+function projectAncestorDirectories(projects) {
+  const directories = new Set;
+  for (const project of projects) {
+    for (let path = resolve10(project), depth = 0;; depth++) {
+      if (depth >= 100)
+        throw new Error("NATIVE_SKILL_DRIFT: project ancestor discovery limit exceeded");
+      directories.add(path);
+      const parent = dirname10(path);
+      if (parent === path)
+        break;
+      path = parent;
+    }
+  }
+  return [...directories];
+}
 function inventoryNativeSkills(home = homedir3(), options = {}) {
   const aliases = rootAliases(home, options.allowRootAliases);
   const roots = ROOTS.map(([agent, path]) => [agent, canonicalAgentPath(join21(home, path), aliases)]);
   const bridgePaths = Object.values(AGENT_ADAPTERS).map((adapter) => canonicalAgentPath(join21(home, adapter.root, CLI_BRIDGE_NAME), aliases));
-  for (const project of new Set([...options.projectDirs ?? [], ...options.projectDir ? [options.projectDir] : []].map((path) => resolve10(path)))) {
+  for (const project of projectAncestorDirectories([...options.projectDirs ?? [], ...options.projectDir ? [options.projectDir] : []])) {
     for (const [agent, path] of ROOTS)
       roots.push([agent, canonicalAgentPath(join21(project, path), aliases)]);
   }
@@ -51335,6 +51427,7 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
   if (options.includeVendor) {
     for (const agent of ["codex", "claude"])
       scanRoot(agent, canonicalAgentPath(join21(home, `.${agent}`, "plugins", "cache"), aliases), true, true);
+    scanRoot("claude", canonicalAgentPath(join21(home, ".claude", "plugins", "synced"), aliases), true);
     scanRoot("gemini", join21(home, ".gemini", "extensions"), true);
   }
   const configured = options.configured ? INTEGRATION_AGENTS.flatMap((agent) => resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, canonical: (path) => canonicalAgentPath(path, aliases) }).roots.map((path) => ({ agent, path }))) : [];
@@ -51399,6 +51492,7 @@ function configureHooks(config, agent, command, profileId, nativeReady) {
     config.permissions.deny = nativeReady ? denied.filter((rule) => rule !== "Skill") : [...new Set([...denied, "Skill"])];
     config.permissions.allow = nativeReady ? [...new Set([...allowed, `Skill(${CLI_BRIDGE_NAME})`])] : allowed;
     config.disableBundledSkills = true;
+    config.syncClaudeAiSkills = false;
   }
   if (agent === "gemini") {
     config.skills ??= {};
@@ -51429,16 +51523,21 @@ function configureHooks(config, agent, command, profileId, nativeReady) {
   }
 }
 function disableCodexSkills(text2, skills, aliases, bridgePath) {
-  Bun.TOML.parse(text2);
-  let result2 = text2;
+  const bundled = disableCodexBundledSkills(text2);
+  let result2 = bundled;
+  const bridgeSelector = (entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME || typeof entry.path === "string" && [resolve10(bridgePath), resolve10(join21(bridgePath, "SKILL.md"))].includes(canonicalAgentPath(entry.path, aliases));
+  const previousConfig = Bun.TOML.parse(bundled).skills?.config;
+  if (previousConfig !== undefined && (!Array.isArray(previousConfig) || previousConfig.some((entry) => !entry || typeof entry !== "object" || entry.path !== undefined && entry.name !== undefined)))
+    throw new Error("Codex skill controls require one path or name selector per [[skills.config]] entry; review ambiguous entries before running skills hook install");
+  const bridgeNeedsRepair = previousConfig?.some((entry) => entry.enabled === false && bridgeSelector(entry));
   const selections = [...skills.filter((entry) => entry.agent === "codex" && !entry.bridge).map((skill) => ({ path: skill.path, enabled: false })), { path: bridgePath, enabled: true }];
   for (const skill of selections) {
     const path = join21(skill.path, "SKILL.md");
     let found = false;
-    result2 = result2.replace(/^\[\[skills\.config\]\][^\n]*(?:\n(?!\s*\[)[^\n]*)*/gm, (section) => {
+    result2 = result2.replace(CODEX_SKILL_CONFIG_SECTIONS, (section) => {
       const parsed = Bun.TOML.parse(section);
-      const declared = parsed.skills?.config?.[0]?.path;
-      if (!declared || ![resolve10(path), resolve10(skill.path)].includes(canonicalAgentPath(declared, aliases)))
+      const declared = parsed.skills?.config?.[0];
+      if (!declared || !(skill.enabled && bridgeSelector(declared)) && !(typeof declared.path === "string" && [resolve10(path), resolve10(skill.path)].includes(canonicalAgentPath(declared.path, aliases))))
         return section;
       found = true;
       return /^\s*enabled\s*=/m.test(section) ? section.replace(/^\s*enabled\s*=.*$/m, `enabled = ${skill.enabled}`) : `${section.trimEnd()}
@@ -51453,6 +51552,8 @@ path = ${JSON.stringify(path)}
 enabled = false
 `;
   }
+  if (result2 !== bundled || bridgeNeedsRepair)
+    assertCodexPathConfigEditable(bundled);
   Bun.TOML.parse(result2);
   return result2;
 }
@@ -51811,18 +51912,7 @@ function assertManagedAgentBridge(agent, options = {}) {
   const expected = canonicalAgentPath(join21(home, AGENT_ADAPTERS[agent].root, CLI_BRIDGE_NAME), aliases);
   if (!isOwnedCliBridge(expected, [expected]))
     throw new Error("NATIVE_SKILL_DRIFT: the native Skills bridge is missing or modified; repair it before continuing");
-  const roots = new Set;
-  for (const project of [options.projectDir ?? process.cwd(), ...options.projectDirs ?? [], ...agent === "hermes" && process.env.TERMINAL_CWD ? [process.cwd()] : []]) {
-    for (let path = resolve10(project), depth = 0;; depth++) {
-      if (depth >= 100)
-        throw new Error("NATIVE_SKILL_DRIFT: project ancestor discovery limit exceeded");
-      roots.add(path);
-      const parent = dirname10(path);
-      if (parent === path)
-        break;
-      path = parent;
-    }
-  }
+  const roots = projectAncestorDirectories([options.projectDir ?? process.cwd(), ...options.projectDirs ?? [], ...agent === "hermes" && process.env.TERMINAL_CWD ? [process.cwd()] : []]);
   const visible = (entry) => entry.agent === agent || ["codex", "gemini", "opencode", "hermes"].includes(agent) && entry.path.includes(`${sep5}.agents${sep5}skills${sep5}`) || agent === "opencode" && entry.agent === "claude";
   assertProjectDiscovery(agent, [...roots], home, (path) => canonicalAgentPath(path, aliases));
   const configPath = canonicalAgentPath(join21(home, AGENT_ADAPTERS[agent].config), aliases), config = agent === "hermes" ? parseHermesConfig(readOptional(configPath)) : jsonObject(readOptional(configPath), configPath);
@@ -51849,13 +51939,17 @@ function assertManagedAgentBridge(agent, options = {}) {
       }
     if (agent === "claude" && (config.disableBundledSkills !== true || config.disableAllHooks === true || !config.permissions?.allow?.includes(`Skill(${CLI_BRIDGE_NAME})`) || config.permissions?.deny?.includes("Skill")))
       throw new Error("NATIVE_SKILL_DRIFT: Claude bridge or bundled-skill protection changed; retire copies and run skills hook install");
+    if (agent === "claude" && config.syncClaudeAiSkills !== false)
+      throw new Error("NATIVE_SKILL_DRIFT: Claude account skill synchronization is not disabled (syncClaudeAiSkills); run skills hook install to prevent native copies from returning");
     if (agent === "gemini" && (config.hooksConfig?.enabled === false || config.skills?.enabled !== true || !["antigravity-support", "skill-creator"].every((name) => config.skills?.disabled?.includes(name)) || config.skills?.disabled?.includes(CLI_BRIDGE_NAME)))
       throw new Error("NATIVE_SKILL_DRIFT: Gemini bridge or bundled-skill protection changed; run skills hook install");
   }
   const codexPath = canonicalAgentPath(join21(home, ".codex", "config.toml"), aliases);
   const codexConfig = agent === "codex" ? Bun.TOML.parse(readOptional(codexPath) ?? "") : {};
+  if (agent === "codex" && codexConfig.skills?.bundled?.enabled !== false)
+    throw new Error("NATIVE_SKILL_DRIFT: Codex bundled skill reseeding is not disabled (skills.bundled.enabled); run skills hook install");
   const setting = (path) => (codexConfig.skills?.config ?? []).filter((entry) => typeof entry.path === "string" && [path, join21(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
-  if (agent === "codex" && setting(expected).some((entry) => entry.enabled === false))
+  if (agent === "codex" && [...setting(expected), ...(codexConfig.skills?.config ?? []).filter((entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME)].some((entry) => entry.enabled === false))
     throw new Error("NATIVE_SKILL_DRIFT: the Codex CLI bridge is disabled; run skills hook install");
   const disabledBuiltin = (entry) => {
     if (agent !== "codex" || !entry.vendor || !entry.path.startsWith(canonicalAgentPath(join21(home, ".codex", "skills", ".system"), aliases) + sep5))
@@ -51880,8 +51974,15 @@ function assertManagedAgentBridge(agent, options = {}) {
     throw new Error(`NATIVE_SKILL_DRIFT: ${error.message}`);
   }
   const inventory = inventoryNativeSkills(home, { includeVendor: true, guardHermes: agent === "hermes", projectDirs: [...roots], agentRoots: discovery.roots.map((path) => ({ agent, path })), allowRootAliases: aliases.length > 0 });
-  if (inventory.some((entry) => visible(entry) && !entry.bridge && !disabledBuiltin(entry)))
-    throw new Error("NATIVE_SKILL_DRIFT: unexpected native skill copies were found; review skills migrate native --include-unmanaged --include-vendor before continuing");
+  const unexpected = inventory.filter((entry) => visible(entry) && !entry.bridge && !disabledBuiltin(entry));
+  if (unexpected.length) {
+    const paths = unexpected.slice(0, 3).map((entry) => {
+      const escaped = JSON.stringify(entry.path).replace(/[\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+      return escaped.length > 768 ? `${escaped.slice(0, 384)}...${escaped.slice(-381)}` : escaped;
+    });
+    const remaining = unexpected.length - paths.length;
+    throw new Error(`NATIVE_SKILL_DRIFT: ${unexpected.length} unexpected native skill copies were found: ${paths.join(", ")}${remaining ? `; ${remaining} more` : ""}. Review skills migrate native --project <working-directory> --include-unmanaged --include-vendor --json before continuing; it inventories that directory and its ancestors. Use --apply after reviewing the archive plan.`);
+  }
   recheckRootAliases(aliases);
 }
 function normalizeAgentHookPrompt(agent, event, prompt) {
@@ -51926,6 +52027,7 @@ var init_agent_integration = __esm(() => {
   init_agent_bridge();
   init_agent_discovery();
   init_agent_adapters();
+  init_agent_codex();
   init_agent_hermes();
   HOOK_EVENTS = ["UserPromptSubmit", "SessionStart", "SubagentStart"];
   ROOTS = [
@@ -73459,6 +73561,46 @@ var init_read_access = __esm(() => {
   init_remote_registry();
 });
 
+// src/cli/option-boundary.ts
+function optionPrefix(program2, args) {
+  const indices = [];
+  let command = program2, runArguments = false;
+  for (let index = 0;index < args.length; index++) {
+    const value = args[index];
+    if (value === "--")
+      return { indices, separator: index };
+    indices.push(index);
+    if (runArguments)
+      continue;
+    const options = [...command.options, ...program2.options];
+    const option = options.find((option2) => option2.long === value || option2.short === value);
+    if (option?.required || option?.optional && args[index + 1] !== undefined && !args[index + 1].startsWith("-")) {
+      index++;
+      continue;
+    }
+    if (!value.startsWith("--") && value.startsWith("-") && value.length > 2) {
+      for (let offset = 1;offset < value.length; offset++) {
+        const short = options.find((option2) => option2.short === `-${value[offset]}`);
+        if (!short)
+          break;
+        if (short.required || short.optional) {
+          if (offset === value.length - 1 && (short.required || args[index + 1] !== undefined && !args[index + 1].startsWith("-")))
+            index++;
+          break;
+        }
+      }
+    }
+    if (value.startsWith("-"))
+      continue;
+    const child = command.commands.find((child2) => child2.name() === value || child2.aliases().includes(value));
+    if (child)
+      command = child;
+    else if (command.name() === "run" && command.parent === program2)
+      runArguments = true;
+  }
+  return { indices, separator: -1 };
+}
+
 // node_modules/zod/v4/classic/index.js
 var init_classic = __esm(() => {
   init_external();
@@ -76454,6 +76596,43 @@ async function prepareSkillDependencies(skillPath, env3, timeoutMs = DEFAULT_PRE
 var DEPENDENCY_PREPARATION_MARKER = ".skills-dependency-preparation", RECOVERY = "Skill dependency preparation is incomplete. Confirm no installer is running, successfully run bun install --no-save in the skill directory, then remove only .skills-dependency-preparation. See docs/skill-standard.md#recovering-interrupted-dependency-preparation.", DEFAULT_PREPARATION_TIMEOUT_MS = 60000;
 var init_dependency_preparation = () => {};
 
+// src/lib/skill-doc-file.ts
+function resolveSkillDocFile(file2) {
+  switch (file2) {
+    case undefined:
+    case "":
+      return;
+    case "skill":
+      return "SKILL.md";
+    case "readme":
+      return "README.md";
+    case "claude":
+      return "CLAUDE.md";
+    default:
+      throw new SkillDocFileError("SKILL_DOC_FILE_INVALID", "Unsupported documentation file. Choose skill, readme, or claude.");
+  }
+}
+function selectSkillDoc(docs, file2) {
+  const path = resolveSkillDocFile(file2);
+  if (path === undefined)
+    return docs.skillMd || docs.readme || docs.claudeMd || null;
+  const content = path === "SKILL.md" ? docs.skillMd : path === "README.md" ? docs.readme : docs.claudeMd;
+  if (content === null)
+    throw new SkillDocFileError("SKILL_DOC_FILE_MISSING", `Documentation file ${path} was not found.`);
+  return content;
+}
+var SkillDocFileError;
+var init_skill_doc_file = __esm(() => {
+  SkillDocFileError = class SkillDocFileError extends Error {
+    code;
+    constructor(code, message) {
+      super(message);
+      this.code = code;
+      this.name = "SkillDocFileError";
+    }
+  };
+});
+
 // src/lib/skillinfo.ts
 var exports_skillinfo = {};
 __export(exports_skillinfo, {
@@ -76491,11 +76670,12 @@ function getSkillDocs(name) {
     claudeMd: readIfExists(join32(skillPath, "CLAUDE.md"))
   };
 }
-function getSkillBestDoc(name) {
+function getSkillBestDoc(name, file2) {
+  resolveSkillDocFile(file2);
   const docs = getSkillDocs(name);
   if (!docs)
     return null;
-  return docs.skillMd || docs.readme || docs.claudeMd || null;
+  return selectSkillDoc(docs, file2);
 }
 function getSkillRequirements(name) {
   const skillPath = getSkillPath(name);
@@ -76815,6 +76995,7 @@ var init_skillinfo = __esm(() => {
   init_installer();
   init_registry();
   init_skill_validation();
+  init_skill_doc_file();
   HOSTED_PROVIDER_ENV_PREFIXES = [
     "OPENAI_",
     "ANTHROPIC_",
@@ -77994,7 +78175,7 @@ function skillNotFound(name, similar = findSimilarSkills(name)) {
     console.error(source_default.dim(`Did you mean: ${similar.join(", ")}?`));
 }
 function handleReadRefusal(error61) {
-  if (!isSkillsFleetCredentialError(error61))
+  if (!isSkillsFleetCredentialError(error61) && !(error61 instanceof SkillDocFileError))
     throw error61;
   console.error(source_default.red(error61.message));
   process.exitCode = 1;
@@ -78084,9 +78265,9 @@ async function resolveRemoteNotFound(name, remote, message) {
   }
 }
 async function handleDocs(name, options) {
+  const file2 = resolveSkillDocFile(options.file);
   const access = await requireSkillsReadAccess();
   if (access.mode === "hosted") {
-    const file2 = options.file === "readme" ? "README.md" : options.file === "claude" ? "CLAUDE.md" : options.file ? "SKILL.md" : undefined;
     const result2 = await loadSelectedSkill(name, selectedProfileId(options.selectionProfile), { projectDir: process.cwd(), file: file2 });
     console.log(options.json ? JSON.stringify({ skill: name, ...result2 }) : result2.content);
     return;
@@ -78100,37 +78281,19 @@ async function handleDocs(name, options) {
     process.exitCode = 1;
     return;
   }
+  const content = selectSkillDoc(docs, options.file);
   if (options.json) {
     console.log(JSON.stringify({
       skill: name,
       hasSkillMd: docs.skillMd !== null,
       hasReadme: docs.readme !== null,
       hasClaudeMd: docs.claudeMd !== null,
-      content: options.file ? docs[options.file === "skill" ? "skillMd" : options.file === "readme" ? "readme" : "claudeMd"] : docs.skillMd || docs.readme || docs.claudeMd
+      content
     }, null, 2));
     return;
   }
-  let content = null;
-  if (options.file === "skill")
-    content = docs.skillMd;
-  else if (options.file === "readme")
-    content = docs.readme;
-  else if (options.file === "claude")
-    content = docs.claudeMd;
-  else
-    content = docs.skillMd || docs.readme || docs.claudeMd;
-  if (!content) {
-    const available = [];
-    if (docs.skillMd)
-      available.push("skill");
-    if (docs.readme)
-      available.push("readme");
-    if (docs.claudeMd)
-      available.push("claude");
-    if (!available.length)
-      console.log(source_default.dim(`No documentation found for '${name}'`));
-    else
-      console.log(source_default.dim(`File '${options.file}' not found. Available: ${available.join(", ")}`));
+  if (content === null) {
+    console.log(source_default.dim(`No documentation found for '${name}'`));
     return;
   }
   console.log(content);
@@ -78295,6 +78458,7 @@ var init_introspect = __esm(() => {
   init_fleet_credentials();
   init_read_access();
   init_skillinfo();
+  init_skill_doc_file();
   init_installer();
   init_skill_validation();
   init_portable_skills();
@@ -81581,7 +81745,7 @@ var init_execution_grants = __esm(() => {
 });
 
 // src/lib/execution-grant-client.ts
-import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual3 } from "util";
 function id(value) {
   if (!grantIdentifier(value))
     throw new Error("Invalid execution grant profile or revision identifier.");
@@ -81633,7 +81797,7 @@ async function saveExecutionGrantPolicy(profileId, grants, revision) {
     headers: revision === undefined ? { "If-None-Match": "*" } : { "If-Match": `"${revision}"` },
     body: JSON.stringify({ grants: snapshot })
   }));
-  if (policy.profileId !== profileId || policy.previousRevision !== (revision ?? null) || !isDeepStrictEqual2(policy.grants, snapshot)) {
+  if (policy.profileId !== profileId || policy.previousRevision !== (revision ?? null) || !isDeepStrictEqual3(policy.grants, snapshot)) {
     throw new Error("The API did not preserve the reviewed execution grant policy; read it before retrying.");
   }
   return policy;
@@ -81644,7 +81808,7 @@ async function resolveExecutionGrant(input2) {
   if (!grantRecord(value) || Object.keys(value).length !== 3 || !grantIdentifier(value.policyRevision) || !grantIdentifier(value.grantId) || !grantRecord(value.bindings)) {
     throw new SkillSelectionError("INVALID_EXECUTION_GRANT", "The Skills API returned an invalid execution grant.");
   }
-  if (!isDeepStrictEqual2(value.bindings.selection, snapshot.selection) || !isDeepStrictEqual2(value.bindings.consumer, snapshot.consumer)) {
+  if (!isDeepStrictEqual3(value.bindings.selection, snapshot.selection) || !isDeepStrictEqual3(value.bindings.consumer, snapshot.consumer)) {
     throw new SkillSelectionError("EXECUTION_GRANT_SCOPE_MISMATCH", "The Skills API returned a grant for a different selection or consumer.");
   }
   return value;
@@ -103274,7 +103438,12 @@ import { lstatSync as lstatSync21, mkdirSync as mkdirSync22, readFileSync as rea
 import { basename as basename6, isAbsolute as isAbsolute15, join as join49 } from "path";
 import { createInterface } from "readline";
 function registerRuntime(parent) {
-  parent.command("run").argument("<skill>", "Skill name").argument("[args...]", "Arguments to pass to the skill").allowUnknownOption(true).passThroughOptions(true).option("--json", "Output result as JSON", false).option("--remote", "Run on the configured server, using its catalog and quote", false).option("--target <target>", "Execution target: local or cloud").option("--secret-bindings <path>", "Reviewed, exact-selection local execution vault bindings (JSON file)").option("--secret-bindings-template", "Print a scoped bindings template without resolving secrets or running the skill", false).option("--input <json>", "Structured cloud execution input").option("--skill-version <version>", "Exact selected skill version").option("--selection-profile <id>", "Selected Skills profile").option("--session <id>", "Pinned Skills session").option("--cached", "Use the explicit verified selected cache", false).option("--yes", "Approve the server's quoted credit cost for this run", false).option("--idempotency-key <key>", "Reuse this key when retrying the same remote submission").option("--file <path>", "Attach a local input file to a remote run (repeatable)", (value, prior) => [...prior, value], []).option("--wait", "Poll remote runs until a terminal status", false).option("--poll-interval-ms <ms>", "Remote polling interval in milliseconds", "1000").option("--poll-timeout-ms <ms>", "Maximum time to wait for a remote run", "300000").description("Run a skill directly").action(async (name, args2, options) => handleRun(name, args2, options));
+  parent.command("run").argument("<skill>", "Skill name").argument("[args...]", "Arguments to pass to the skill; use -- to end Skills options").allowUnknownOption(true).passThroughOptions(true).option("--json", "Output result as JSON", false).option("--remote", "Run on the configured server, using its catalog and quote", false).option("--target <target>", "Execution target: local or cloud").option("--secret-bindings <path>", "Reviewed, exact-selection local execution vault bindings (JSON file)").option("--secret-bindings-template", "Print a scoped bindings template without resolving secrets or running the skill", false).option("--input <json>", "Structured cloud execution input").option("--skill-version <version>", "Exact selected skill version").option("--selection-profile <id>", "Selected Skills profile").option("--session <id>", "Pinned Skills session").option("--cached", "Use the explicit verified selected cache", false).option("--yes", "Approve the server's quoted credit cost for this run", false).option("--idempotency-key <key>", "Reuse this key when retrying the same remote submission").option("--file <path>", "Attach a local input file to a remote run (repeatable)", (value, prior) => [...prior, value], []).option("--wait", "Poll remote runs until a terminal status", false).option("--poll-interval-ms <ms>", "Remote polling interval in milliseconds", "1000").option("--poll-timeout-ms <ms>", "Maximum time to wait for a remote run", "300000").description("Run a skill directly").action(async (name, args2, options, command) => {
+    const parentArgs = command.parent.args;
+    const prefix = parentArgs.slice(0, parentArgs.length - command.args.length);
+    const separatorBeforeSkill = optionPrefix(command.parent, prefix).separator >= 0;
+    await handleRun(name, args2, options, separatorBeforeSkill);
+  });
   const executions = parent.command("executions").description("Inspect isolated cloud executions");
   for (const operation of ["show", "logs", "artifacts", "cancel"]) {
     executions.command(operation).argument("<execution-id>").option("--json", "Output as JSON", false).action(async (id2) => {
@@ -103536,7 +103705,7 @@ function promptLine(question) {
     });
   });
 }
-async function handleRun(name, args2, options) {
+async function handleRun(name, args2, options, separatorBeforeSkill) {
   let managed;
   try {
     managed = requiresCliSkillLoading();
@@ -103545,6 +103714,12 @@ async function handleRun(name, args2, options) {
     process.exitCode = 1;
     return;
   }
+  const separator = args2.indexOf("--");
+  const childArgs = separatorBeforeSkill ? args2 : separator < 0 ? [] : args2.slice(separator + 1);
+  if (separatorBeforeSkill)
+    args2 = [];
+  else if (separator >= 0)
+    args2 = args2.slice(0, separator);
   const targetIndex = args2.indexOf("--target");
   if (managed && !options.remote || options.target || targetIndex >= 0 || options.secretBindings || options.secretBindingsTemplate || args2.includes("--secret-bindings") || args2.includes("--secret-bindings-template")) {
     options = { ...options };
@@ -103570,6 +103745,7 @@ async function handleRun(name, args2, options) {
       }
     }
   }
+  args2 = [...args2, ...childArgs];
   if (options.remote && options.target) {
     console.error("Conflicting --remote and --target execution modes");
     process.exitCode = 1;
@@ -105609,10 +105785,10 @@ function registerAgentIntegration(parent) {
     }
   });
   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("--include-vendor", "Retire vendor SKILL.md discovery files while preserving plugin scripts and assets", false).option("--discovery-inputs <file>", "Advanced reviewed active plugin roots and source hashes").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) => {
+  migrate.command("native").option("--project <directory>", "Also inventory a project and its ancestors (the current directory and its ancestors are always included)").option("--include-unmanaged", "Archive user-authored skills as well as Skills-managed copies", false).option("--include-vendor", "Retire vendor SKILL.md discovery files while preserving plugin scripts and assets", false).option("--discovery-inputs <file>", "Advanced reviewed active plugin roots and source hashes").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 discoveryInputs = options.discoveryInputs ? JSON.parse(readFileSync37(options.discoveryInputs, "utf8")) : undefined;
-      const inventory = inventoryNativeSkills(undefined, { projectDir: options.project, includeVendor: options.includeVendor, configured: options.includeVendor, discoveryInputs, allowRootAliases: options.allowRootAliases });
+      const inventory = inventoryNativeSkills(undefined, { projectDirs: [process.cwd(), ...options.project ? [options.project] : []], includeVendor: options.includeVendor, configured: options.includeVendor, discoveryInputs, allowRootAliases: options.allowRootAliases });
       const result2 = options.apply ? archiveNativeSkills(inventory, { includeUnmanaged: options.includeUnmanaged, includeVendor: options.includeVendor, allowRootAliases: options.allowRootAliases }) : { entries: [] };
       if (options.json)
         await writeCliOutput(JSON.stringify({ applied: options.apply, inventory, ...result2 }));
@@ -116915,11 +117091,6 @@ init_fleet_credentials();
 init_read_access();
 var jsx_dev_runtime7 = __toESM(require_jsx_dev_runtime(), 1);
 var isTTY2 = (process.stdout.isTTY ?? false) && (process.stdin.isTTY ?? false);
-if (process.argv.includes("--no-color")) {
-  source_default.level = 0;
-  const idx = process.argv.indexOf("--no-color");
-  process.argv.splice(idx, 1);
-}
 var program2 = new Command;
 program2.name("skills").description("Discover and run AI agent skills through the Skills CLI/MCP").version(package_default.version).option("--verbose", "Enable verbose logging", false).option("--profile <name>", "Use an isolated Skills instance credential profile").option("--no-color", "Disable colored output (also respects NO_COLOR env var)").enablePositionalOptions();
 program2.hook("preAction", () => {
@@ -117003,6 +117174,12 @@ registerStorage2(program2);
 var { registerRegistryReconcile: registerRegistryReconcile2 } = await Promise.resolve().then(() => (init_registry_reconcile2(), exports_registry_reconcile));
 registerRegistryReconcile2(program2);
 registerEventsCommands(program2, { source: "skills" });
+var cliArgs = process.argv.slice(2);
+var colorFlag = optionPrefix(program2, cliArgs).indices.find((index) => cliArgs[index] === "--no-color");
+if (colorFlag !== undefined) {
+  source_default.level = 0;
+  process.argv.splice(colorFlag + 2, 1);
+}
 try {
   await program2.parseAsync();
 } catch (err) {

package/bin/mcp.js

@@ -20019,7 +20019,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.8.7",
+    version: "0.8.9",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -47384,6 +47384,9 @@ var init_agent_discovery = __esm(() => {
 // src/lib/agent-adapters.ts
 var init_agent_adapters = () => {};
 
+// src/lib/agent-codex.ts
+var init_agent_codex = () => {};
+
 // src/lib/agent-integration.ts
 var init_agent_integration = __esm(() => {
   init_config();
@@ -47391,6 +47394,7 @@ var init_agent_integration = __esm(() => {
   init_agent_bridge();
   init_agent_discovery();
   init_agent_adapters();
+  init_agent_codex();
   init_agent_hermes();
 });
 
@@ -47649,6 +47653,43 @@ var init_installer = __esm(() => {
   };
 });
 
+// src/lib/skill-doc-file.ts
+function resolveSkillDocFile(file2) {
+  switch (file2) {
+    case undefined:
+    case "":
+      return;
+    case "skill":
+      return "SKILL.md";
+    case "readme":
+      return "README.md";
+    case "claude":
+      return "CLAUDE.md";
+    default:
+      throw new SkillDocFileError("SKILL_DOC_FILE_INVALID", "Unsupported documentation file. Choose skill, readme, or claude.");
+  }
+}
+function selectSkillDoc(docs, file2) {
+  const path = resolveSkillDocFile(file2);
+  if (path === undefined)
+    return docs.skillMd || docs.readme || docs.claudeMd || null;
+  const content = path === "SKILL.md" ? docs.skillMd : path === "README.md" ? docs.readme : docs.claudeMd;
+  if (content === null)
+    throw new SkillDocFileError("SKILL_DOC_FILE_MISSING", `Documentation file ${path} was not found.`);
+  return content;
+}
+var SkillDocFileError;
+var init_skill_doc_file = __esm(() => {
+  SkillDocFileError = class SkillDocFileError extends Error {
+    code;
+    constructor(code, message) {
+      super(message);
+      this.code = code;
+      this.name = "SkillDocFileError";
+    }
+  };
+});
+
 // src/lib/skillinfo.ts
 import { existsSync as existsSync12, readFileSync as readFileSync14 } from "fs";
 import { join as join18 } from "path";
@@ -47674,11 +47715,12 @@ function getSkillDocs(name) {
     claudeMd: readIfExists(join18(skillPath, "CLAUDE.md"))
   };
 }
-function getSkillBestDoc(name) {
+function getSkillBestDoc(name, file2) {
+  resolveSkillDocFile(file2);
   const docs = getSkillDocs(name);
   if (!docs)
     return null;
-  return docs.skillMd || docs.readme || docs.claudeMd || null;
+  return selectSkillDoc(docs, file2);
 }
 function getSkillRequirements(name) {
   const skillPath = getSkillPath(name);
@@ -47856,6 +47898,7 @@ var init_skillinfo = __esm(() => {
   init_installer();
   init_registry();
   init_skill_validation();
+  init_skill_doc_file();
   HOSTED_PROVIDER_ENV_PREFIXES = [
     "OPENAI_",
     "ANTHROPIC_",

package/bin/migrate.js

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

package/bin/server.js

@@ -83749,7 +83749,7 @@ var require_protocols9 = __commonJS((exports) => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.8.7",
+  version: "0.8.9",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

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

package/dist/cli/option-boundary.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/** Locate a real terminator without mistaking a required option value for it. */
+export declare function optionPrefix(program: Command, args: string[]): {
+    indices: number[];
+    separator: number;
+};

package/dist/index.js

@@ -11570,6 +11570,80 @@ export default async ({ directory }) => {
 `;
 }
 
+// src/lib/agent-codex.ts
+import { isDeepStrictEqual } from "util";
+var CODEX_SKILL_CONFIG_SECTIONS = /^\[\[skills\.config\]\][^\n]*(?:\n(?!\s*\[)[^\n]*)*/gm;
+function assertCodexPathConfigEditable(text2) {
+  const before = Bun.TOML.parse(text2);
+  if (before.skills?.config === undefined)
+    return;
+  const expected = structuredClone(before);
+  delete expected.skills.config;
+  try {
+    const withoutSections = Bun.TOML.parse(text2.replace(CODEX_SKILL_CONFIG_SECTIONS, ""));
+    if (isDeepStrictEqual(withoutSections, expected))
+      return;
+  } catch {}
+  throw new Error("Codex skill path controls require ordinary [[skills.config]] TOML tables; preserve and convert inline or dotted config arrays before running skills hook install");
+}
+function disableCodexBundledSkills(text2) {
+  const before = Bun.TOML.parse(text2);
+  const table = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
+  const refuse = () => new Error("Codex bundled skills configuration requires ordinary [skills.bundled] TOML with a boolean enabled setting; preserve and convert inline or dotted definitions before running skills hook install");
+  if (before.skills !== undefined && !table(before.skills))
+    throw refuse();
+  if (before.skills?.bundled !== undefined && !table(before.skills.bundled))
+    throw refuse();
+  if (before.skills !== undefined) {
+    let root = before, attempts = 0;
+    for (const header of text2.matchAll(/^[ \t]*\[/gm)) {
+      if (++attempts > 256)
+        throw refuse();
+      try {
+        root = Bun.TOML.parse(text2.slice(0, header.index));
+        break;
+      } catch {}
+    }
+    if (root.skills !== undefined)
+      throw refuse();
+  }
+  const enabled = before.skills?.bundled?.enabled;
+  if (enabled !== undefined && typeof enabled !== "boolean")
+    throw refuse();
+  if (enabled === false)
+    return text2;
+  const expected = structuredClone(before);
+  expected.skills ??= {};
+  expected.skills.bundled ??= {};
+  expected.skills.bundled.enabled = false;
+  const candidates = new Set;
+  const consider = (candidate) => {
+    try {
+      if (isDeepStrictEqual(Bun.TOML.parse(candidate), expected))
+        candidates.add(candidate);
+    } catch {}
+  };
+  const newline = text2.includes(`\r
+`) ? `\r
+` : `
+`;
+  if (before.skills?.bundled !== undefined) {
+    for (const section of text2.matchAll(/^[ \t]*\[skills\.bundled\][ \t]*(?:#[^\r\n]*)?(?:\r?\n|$)(?:(?![ \t]*\[)[^\n]*(?:\n|$))*/gm)) {
+      const headerEnd = section[0].indexOf(`
+`) + 1 || section[0].length;
+      const replacement = enabled === true ? section[0].replace(/^([ \t]*enabled[ \t]*=[ \t]*)true([ \t]*(?:#[^\r\n]*)?)(\r?)$/m, "$1false$2$3") : section[0].slice(0, headerEnd) + (section[0].slice(0, headerEnd).endsWith(`
+`) ? "" : newline) + `enabled = false${newline}` + section[0].slice(headerEnd);
+      consider(text2.slice(0, section.index) + replacement + text2.slice(section.index + section[0].length));
+    }
+  } else {
+    consider(`${text2}${text2.endsWith(`
+`) || !text2 ? "" : newline}${newline}[skills.bundled]${newline}enabled = false${newline}`);
+  }
+  if (candidates.size !== 1)
+    throw refuse();
+  return [...candidates][0];
+}
+
 // src/lib/agent-integration.ts
 var sha = (data) => createHash9("sha256").update(data).digest("hex");
 var ROOTS = [
@@ -11693,11 +11767,26 @@ function treeHash(root) {
   visit2(root);
   return hash2.digest("hex");
 }
+function projectAncestorDirectories(projects) {
+  const directories = new Set;
+  for (const project of projects) {
+    for (let path = resolve9(project), depth = 0;; depth++) {
+      if (depth >= 100)
+        throw new Error("NATIVE_SKILL_DRIFT: project ancestor discovery limit exceeded");
+      directories.add(path);
+      const parent = dirname10(path);
+      if (parent === path)
+        break;
+      path = parent;
+    }
+  }
+  return [...directories];
+}
 function inventoryNativeSkills(home = homedir2(), options = {}) {
   const aliases = rootAliases(home, options.allowRootAliases);
   const roots = ROOTS.map(([agent, path]) => [agent, canonicalAgentPath(join17(home, path), aliases)]);
   const bridgePaths = Object.values(AGENT_ADAPTERS).map((adapter) => canonicalAgentPath(join17(home, adapter.root, CLI_BRIDGE_NAME), aliases));
-  for (const project of new Set([...options.projectDirs ?? [], ...options.projectDir ? [options.projectDir] : []].map((path) => resolve9(path)))) {
+  for (const project of projectAncestorDirectories([...options.projectDirs ?? [], ...options.projectDir ? [options.projectDir] : []])) {
     for (const [agent, path] of ROOTS)
       roots.push([agent, canonicalAgentPath(join17(project, path), aliases)]);
   }
@@ -11800,6 +11889,7 @@ function inventoryNativeSkills(home = homedir2(), options = {}) {
   if (options.includeVendor) {
     for (const agent of ["codex", "claude"])
       scanRoot(agent, canonicalAgentPath(join17(home, `.${agent}`, "plugins", "cache"), aliases), true, true);
+    scanRoot("claude", canonicalAgentPath(join17(home, ".claude", "plugins", "synced"), aliases), true);
     scanRoot("gemini", join17(home, ".gemini", "extensions"), true);
   }
   const configured = options.configured ? INTEGRATION_AGENTS.flatMap((agent) => resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, canonical: (path) => canonicalAgentPath(path, aliases) }).roots.map((path) => ({ agent, path }))) : [];
@@ -11864,6 +11954,7 @@ function configureHooks(config, agent, command, profileId, nativeReady) {
     config.permissions.deny = nativeReady ? denied.filter((rule) => rule !== "Skill") : [...new Set([...denied, "Skill"])];
     config.permissions.allow = nativeReady ? [...new Set([...allowed, `Skill(${CLI_BRIDGE_NAME})`])] : allowed;
     config.disableBundledSkills = true;
+    config.syncClaudeAiSkills = false;
   }
   if (agent === "gemini") {
     config.skills ??= {};
@@ -11894,16 +11985,21 @@ function configureHooks(config, agent, command, profileId, nativeReady) {
   }
 }
 function disableCodexSkills(text2, skills, aliases, bridgePath) {
-  Bun.TOML.parse(text2);
-  let result = text2;
+  const bundled = disableCodexBundledSkills(text2);
+  let result = bundled;
+  const bridgeSelector = (entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME || typeof entry.path === "string" && [resolve9(bridgePath), resolve9(join17(bridgePath, "SKILL.md"))].includes(canonicalAgentPath(entry.path, aliases));
+  const previousConfig = Bun.TOML.parse(bundled).skills?.config;
+  if (previousConfig !== undefined && (!Array.isArray(previousConfig) || previousConfig.some((entry) => !entry || typeof entry !== "object" || entry.path !== undefined && entry.name !== undefined)))
+    throw new Error("Codex skill controls require one path or name selector per [[skills.config]] entry; review ambiguous entries before running skills hook install");
+  const bridgeNeedsRepair = previousConfig?.some((entry) => entry.enabled === false && bridgeSelector(entry));
   const selections = [...skills.filter((entry) => entry.agent === "codex" && !entry.bridge).map((skill) => ({ path: skill.path, enabled: false })), { path: bridgePath, enabled: true }];
   for (const skill of selections) {
     const path = join17(skill.path, "SKILL.md");
     let found = false;
-    result = result.replace(/^\[\[skills\.config\]\][^\n]*(?:\n(?!\s*\[)[^\n]*)*/gm, (section) => {
+    result = result.replace(CODEX_SKILL_CONFIG_SECTIONS, (section) => {
       const parsed = Bun.TOML.parse(section);
-      const declared = parsed.skills?.config?.[0]?.path;
-      if (!declared || ![resolve9(path), resolve9(skill.path)].includes(canonicalAgentPath(declared, aliases)))
+      const declared = parsed.skills?.config?.[0];
+      if (!declared || !(skill.enabled && bridgeSelector(declared)) && !(typeof declared.path === "string" && [resolve9(path), resolve9(skill.path)].includes(canonicalAgentPath(declared.path, aliases))))
         return section;
       found = true;
       return /^\s*enabled\s*=/m.test(section) ? section.replace(/^\s*enabled\s*=.*$/m, `enabled = ${skill.enabled}`) : `${section.trimEnd()}
@@ -11918,6 +12014,8 @@ path = ${JSON.stringify(path)}
 enabled = false
 `;
   }
+  if (result !== bundled || bridgeNeedsRepair)
+    assertCodexPathConfigEditable(bundled);
   Bun.TOML.parse(result);
   return result;
 }
@@ -13403,6 +13501,42 @@ async function prepareSkillDependencies(skillPath, env, timeoutMs = DEFAULT_PREP
 // src/lib/skillinfo.ts
 import { existsSync as existsSync15, readFileSync as readFileSync17 } from "fs";
 import { join as join23 } from "path";
+
+// src/lib/skill-doc-file.ts
+class SkillDocFileError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SkillDocFileError";
+  }
+}
+function resolveSkillDocFile(file) {
+  switch (file) {
+    case undefined:
+    case "":
+      return;
+    case "skill":
+      return "SKILL.md";
+    case "readme":
+      return "README.md";
+    case "claude":
+      return "CLAUDE.md";
+    default:
+      throw new SkillDocFileError("SKILL_DOC_FILE_INVALID", "Unsupported documentation file. Choose skill, readme, or claude.");
+  }
+}
+function selectSkillDoc(docs, file) {
+  const path = resolveSkillDocFile(file);
+  if (path === undefined)
+    return docs.skillMd || docs.readme || docs.claudeMd || null;
+  const content = path === "SKILL.md" ? docs.skillMd : path === "README.md" ? docs.readme : docs.claudeMd;
+  if (content === null)
+    throw new SkillDocFileError("SKILL_DOC_FILE_MISSING", `Documentation file ${path} was not found.`);
+  return content;
+}
+
+// src/lib/skillinfo.ts
 function isInstructionSkillDir(skillPath, meta) {
   if (meta?.kind === "instruction")
     return true;
@@ -13441,11 +13575,12 @@ function getSkillDocs(name) {
     claudeMd: readIfExists(join23(skillPath, "CLAUDE.md"))
   };
 }
-function getSkillBestDoc(name) {
+function getSkillBestDoc(name, file) {
+  resolveSkillDocFile(file);
   const docs = getSkillDocs(name);
   if (!docs)
     return null;
-  return docs.skillMd || docs.readme || docs.claudeMd || null;
+  return selectSkillDoc(docs, file);
 }
 function getSkillRequirements(name) {
   const skillPath = getSkillPath(name);
@@ -37705,7 +37840,7 @@ import { dirname as dirname14, relative as relative7 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.8.7",
+  version: "0.8.9",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/lib/agent-codex.d.ts

@@ -0,0 +1,10 @@
+export declare const CODEX_SKILL_CONFIG_SECTIONS: RegExp;
+/** The path editor supports ordinary array-of-table sections only. Removing
+ * those sections must remove exactly the parsed path array, with all other
+ * values unchanged. This also excludes header-like text inside user strings. */
+export declare function assertCodexPathConfigEditable(text: string): void;
+/** Preserve user TOML verbatim except for the supported bundled-skill control.
+ * Bun's parser accepts some illegal table reopenings, so never append a table
+ * over an existing inline/dotted skills definition. Refuse unfamiliar layouts
+ * before the integration transaction writes any files. */
+export declare function disableCodexBundledSkills(text: string): string;

package/dist/lib/skill-doc-file.d.ts

@@ -0,0 +1,9 @@
+import type { SkillDocs } from "./skillinfo.js";
+export declare class SkillDocFileError extends Error {
+    readonly code: "SKILL_DOC_FILE_INVALID" | "SKILL_DOC_FILE_MISSING";
+    constructor(code: "SKILL_DOC_FILE_INVALID" | "SKILL_DOC_FILE_MISSING", message: string);
+}
+/** The docs command's aliases are not arbitrary bundle paths (skills load supports those). */
+export declare function resolveSkillDocFile(file?: string): "SKILL.md" | "README.md" | "CLAUDE.md" | undefined;
+/** Fall back only when no file was requested, identically for text, JSON and SDK reads. */
+export declare function selectSkillDoc(docs: SkillDocs, file?: string): string | null;

package/dist/lib/skillinfo.d.ts

@@ -15,9 +15,10 @@ export interface SkillRequirements {
  */
 export declare function getSkillDocs(name: string): SkillDocs | null;
 /**
- * Get the best available documentation for a skill (SKILL.md > README.md > CLAUDE.md)
+ * Get preferred documentation, or an exact docs alias (skill, readme, claude).
+ * Unknown aliases and missing explicitly requested files refuse without fallback.
  */
-export declare function getSkillBestDoc(name: string): string | null;
+export declare function getSkillBestDoc(name: string, file?: string): string | null;
 /**
  * Extract requirements from a skill's source files
  */

package/dist/sdk/index.js

@@ -96141,7 +96141,7 @@ async function resolveExecutionGrant(input) {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.8.7",
+  version: "0.8.9",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -97659,6 +97659,80 @@ export default async ({ directory }) => {
 `;
 }
 
+// src/lib/agent-codex.ts
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
+var CODEX_SKILL_CONFIG_SECTIONS = /^\[\[skills\.config\]\][^\n]*(?:\n(?!\s*\[)[^\n]*)*/gm;
+function assertCodexPathConfigEditable(text2) {
+  const before = Bun.TOML.parse(text2);
+  if (before.skills?.config === undefined)
+    return;
+  const expected = structuredClone(before);
+  delete expected.skills.config;
+  try {
+    const withoutSections = Bun.TOML.parse(text2.replace(CODEX_SKILL_CONFIG_SECTIONS, ""));
+    if (isDeepStrictEqual2(withoutSections, expected))
+      return;
+  } catch {}
+  throw new Error("Codex skill path controls require ordinary [[skills.config]] TOML tables; preserve and convert inline or dotted config arrays before running skills hook install");
+}
+function disableCodexBundledSkills(text2) {
+  const before = Bun.TOML.parse(text2);
+  const table = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
+  const refuse2 = () => new Error("Codex bundled skills configuration requires ordinary [skills.bundled] TOML with a boolean enabled setting; preserve and convert inline or dotted definitions before running skills hook install");
+  if (before.skills !== undefined && !table(before.skills))
+    throw refuse2();
+  if (before.skills?.bundled !== undefined && !table(before.skills.bundled))
+    throw refuse2();
+  if (before.skills !== undefined) {
+    let root = before, attempts = 0;
+    for (const header of text2.matchAll(/^[ \t]*\[/gm)) {
+      if (++attempts > 256)
+        throw refuse2();
+      try {
+        root = Bun.TOML.parse(text2.slice(0, header.index));
+        break;
+      } catch {}
+    }
+    if (root.skills !== undefined)
+      throw refuse2();
+  }
+  const enabled = before.skills?.bundled?.enabled;
+  if (enabled !== undefined && typeof enabled !== "boolean")
+    throw refuse2();
+  if (enabled === false)
+    return text2;
+  const expected = structuredClone(before);
+  expected.skills ??= {};
+  expected.skills.bundled ??= {};
+  expected.skills.bundled.enabled = false;
+  const candidates = new Set;
+  const consider = (candidate) => {
+    try {
+      if (isDeepStrictEqual2(Bun.TOML.parse(candidate), expected))
+        candidates.add(candidate);
+    } catch {}
+  };
+  const newline = text2.includes(`\r
+`) ? `\r
+` : `
+`;
+  if (before.skills?.bundled !== undefined) {
+    for (const section of text2.matchAll(/^[ \t]*\[skills\.bundled\][ \t]*(?:#[^\r\n]*)?(?:\r?\n|$)(?:(?![ \t]*\[)[^\n]*(?:\n|$))*/gm)) {
+      const headerEnd = section[0].indexOf(`
+`) + 1 || section[0].length;
+      const replacement = enabled === true ? section[0].replace(/^([ \t]*enabled[ \t]*=[ \t]*)true([ \t]*(?:#[^\r\n]*)?)(\r?)$/m, "$1false$2$3") : section[0].slice(0, headerEnd) + (section[0].slice(0, headerEnd).endsWith(`
+`) ? "" : newline) + `enabled = false${newline}` + section[0].slice(headerEnd);
+      consider(text2.slice(0, section.index) + replacement + text2.slice(section.index + section[0].length));
+    }
+  } else {
+    consider(`${text2}${text2.endsWith(`
+`) || !text2 ? "" : newline}${newline}[skills.bundled]${newline}enabled = false${newline}`);
+  }
+  if (candidates.size !== 1)
+    throw refuse2();
+  return [...candidates][0];
+}
+
 // src/lib/agent-integration.ts
 var sha = (data) => createHash9("sha256").update(data).digest("hex");
 var ROOTS = [
@@ -97782,11 +97856,26 @@ function treeHash(root) {
   visit2(root);
   return hash2.digest("hex");
 }
+function projectAncestorDirectories(projects) {
+  const directories = new Set;
+  for (const project of projects) {
+    for (let path = resolve8(project), depth = 0;; depth++) {
+      if (depth >= 100)
+        throw new Error("NATIVE_SKILL_DRIFT: project ancestor discovery limit exceeded");
+      directories.add(path);
+      const parent = dirname9(path);
+      if (parent === path)
+        break;
+      path = parent;
+    }
+  }
+  return [...directories];
+}
 function inventoryNativeSkills(home = homedir2(), options = {}) {
   const aliases = rootAliases(home, options.allowRootAliases);
   const roots = ROOTS.map(([agent, path]) => [agent, canonicalAgentPath(join16(home, path), aliases)]);
   const bridgePaths = Object.values(AGENT_ADAPTERS).map((adapter) => canonicalAgentPath(join16(home, adapter.root, CLI_BRIDGE_NAME), aliases));
-  for (const project of new Set([...options.projectDirs ?? [], ...options.projectDir ? [options.projectDir] : []].map((path) => resolve8(path)))) {
+  for (const project of projectAncestorDirectories([...options.projectDirs ?? [], ...options.projectDir ? [options.projectDir] : []])) {
     for (const [agent, path] of ROOTS)
       roots.push([agent, canonicalAgentPath(join16(project, path), aliases)]);
   }
@@ -97889,6 +97978,7 @@ function inventoryNativeSkills(home = homedir2(), options = {}) {
   if (options.includeVendor) {
     for (const agent of ["codex", "claude"])
       scanRoot(agent, canonicalAgentPath(join16(home, `.${agent}`, "plugins", "cache"), aliases), true, true);
+    scanRoot("claude", canonicalAgentPath(join16(home, ".claude", "plugins", "synced"), aliases), true);
     scanRoot("gemini", join16(home, ".gemini", "extensions"), true);
   }
   const configured = options.configured ? INTEGRATION_AGENTS.flatMap((agent) => resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, canonical: (path) => canonicalAgentPath(path, aliases) }).roots.map((path) => ({ agent, path }))) : [];
@@ -97953,6 +98043,7 @@ function configureHooks(config, agent, command, profileId, nativeReady) {
     config.permissions.deny = nativeReady ? denied.filter((rule) => rule !== "Skill") : [...new Set([...denied, "Skill"])];
     config.permissions.allow = nativeReady ? [...new Set([...allowed, `Skill(${CLI_BRIDGE_NAME})`])] : allowed;
     config.disableBundledSkills = true;
+    config.syncClaudeAiSkills = false;
   }
   if (agent === "gemini") {
     config.skills ??= {};
@@ -97983,16 +98074,21 @@ function configureHooks(config, agent, command, profileId, nativeReady) {
   }
 }
 function disableCodexSkills(text2, skills, aliases, bridgePath) {
-  Bun.TOML.parse(text2);
-  let result = text2;
+  const bundled = disableCodexBundledSkills(text2);
+  let result = bundled;
+  const bridgeSelector = (entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME || typeof entry.path === "string" && [resolve8(bridgePath), resolve8(join16(bridgePath, "SKILL.md"))].includes(canonicalAgentPath(entry.path, aliases));
+  const previousConfig = Bun.TOML.parse(bundled).skills?.config;
+  if (previousConfig !== undefined && (!Array.isArray(previousConfig) || previousConfig.some((entry) => !entry || typeof entry !== "object" || entry.path !== undefined && entry.name !== undefined)))
+    throw new Error("Codex skill controls require one path or name selector per [[skills.config]] entry; review ambiguous entries before running skills hook install");
+  const bridgeNeedsRepair = previousConfig?.some((entry) => entry.enabled === false && bridgeSelector(entry));
   const selections = [...skills.filter((entry) => entry.agent === "codex" && !entry.bridge).map((skill) => ({ path: skill.path, enabled: false })), { path: bridgePath, enabled: true }];
   for (const skill of selections) {
     const path = join16(skill.path, "SKILL.md");
     let found = false;
-    result = result.replace(/^\[\[skills\.config\]\][^\n]*(?:\n(?!\s*\[)[^\n]*)*/gm, (section) => {
+    result = result.replace(CODEX_SKILL_CONFIG_SECTIONS, (section) => {
       const parsed = Bun.TOML.parse(section);
-      const declared = parsed.skills?.config?.[0]?.path;
-      if (!declared || ![resolve8(path), resolve8(skill.path)].includes(canonicalAgentPath(declared, aliases)))
+      const declared = parsed.skills?.config?.[0];
+      if (!declared || !(skill.enabled && bridgeSelector(declared)) && !(typeof declared.path === "string" && [resolve8(path), resolve8(skill.path)].includes(canonicalAgentPath(declared.path, aliases))))
         return section;
       found = true;
       return /^\s*enabled\s*=/m.test(section) ? section.replace(/^\s*enabled\s*=.*$/m, `enabled = ${skill.enabled}`) : `${section.trimEnd()}
@@ -98007,6 +98103,8 @@ path = ${JSON.stringify(path)}
 enabled = false
 `;
   }
+  if (result !== bundled || bridgeNeedsRepair)
+    assertCodexPathConfigEditable(bundled);
   Bun.TOML.parse(result);
   return result;
 }
@@ -101453,6 +101551,40 @@ function loadProjectConfigCompat(targetDir) {
   return loadProjectConfig(targetDir);
 }
 
+// src/lib/skill-doc-file.ts
+class SkillDocFileError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SkillDocFileError";
+  }
+}
+function resolveSkillDocFile(file) {
+  switch (file) {
+    case undefined:
+    case "":
+      return;
+    case "skill":
+      return "SKILL.md";
+    case "readme":
+      return "README.md";
+    case "claude":
+      return "CLAUDE.md";
+    default:
+      throw new SkillDocFileError("SKILL_DOC_FILE_INVALID", "Unsupported documentation file. Choose skill, readme, or claude.");
+  }
+}
+function selectSkillDoc(docs, file) {
+  const path = resolveSkillDocFile(file);
+  if (path === undefined)
+    return docs.skillMd || docs.readme || docs.claudeMd || null;
+  const content = path === "SKILL.md" ? docs.skillMd : path === "README.md" ? docs.readme : docs.claudeMd;
+  if (content === null)
+    throw new SkillDocFileError("SKILL_DOC_FILE_MISSING", `Documentation file ${path} was not found.`);
+  return content;
+}
+
 // src/lib/skillinfo.ts
 function isInstructionSkillDir(skillPath, meta) {
   if (meta?.kind === "instruction")
@@ -101492,11 +101624,12 @@ function getSkillDocs(name) {
     claudeMd: readIfExists(join26(skillPath, "CLAUDE.md"))
   };
 }
-function getSkillBestDoc(name) {
+function getSkillBestDoc(name, file) {
+  resolveSkillDocFile(file);
   const docs = getSkillDocs(name);
   if (!docs)
     return null;
-  return docs.skillMd || docs.readme || docs.claudeMd || null;
+  return selectSkillDoc(docs, file);
 }
 function getSkillRequirements(name) {
   const skillPath = getSkillPath(name);

package/package.json

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