@hasna/skills 0.10.73 → 0.10.75

package/dist/runtime-prerequisites.js

@@ -49,7 +49,7 @@ var __require = import.meta.require;
 // src/runtime-prerequisites.ts
 import { isAbsolute as isAbsolute7 } from "path";
 // package.json
-var version = "0.10.73";
+var version = "0.10.75";
 var package_default = {
   name: "@hasna/skills",
   version,

package/dist/sdk/index.js

@@ -32371,7 +32371,7 @@ var init_event_sink = __esm(() => {
   init_dist();
 });
 // package.json
-var version = "0.10.73";
+var version = "0.10.75";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -46491,6 +46491,12 @@ function verifyAgentDiscovery(binding, codexRecovery, reviewedRootAliases, witne
 }
 var CLAUDE_CONTROL_WITNESS_MODES = new Set(["claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry", "claude-marketplace-registry-v2", "claude-marketplace-entry-v1", "claude-plugin-registry"]);
 var CLAUDE_CONTROL_FILES = new Set(["settings.json", "settings.local.json", "installed_plugins.json", "known_marketplaces.json"]);
+function claudeControlSource(source) {
+  return CLAUDE_CONTROL_WITNESS_MODES.has(source.hashMode ?? "") || CLAUDE_CONTROL_FILES.has(basename12(source.path)) && !source.path.includes(`${sep13}.claude${sep13}plugins${sep13}cache${sep13}`);
+}
+function retainedAbsentClaudeRoot(absentRoots, source) {
+  return claudeControlSource(source) ? undefined : retainedAbsentRoot(absentRoots, source);
+}
 function codexInstallationRoots(binding) {
   const proof = binding.codexInstallationInputs;
   if (proof === undefined)
@@ -46900,7 +46906,10 @@ function resolveAgentDiscovery(options) {
     if (!review.sources.some((source) => source.path === canonical9(configPath)))
       throw new Error("Discovery review must include the agent configuration source");
     const reviewedSources = supersedesSettingsProjection(agent, review.sources, canonical9(configPath)) ? sources.filter((source) => !isSupersededSettingsProjection(agent, canonical9(configPath), source)) : sources;
+    const absentRoots = absentRetiredClaudeRoots(supplied);
     const reviewedSourcesWithManifestProjection = review.sources.map((source) => {
+      if (retainedAbsentClaudeRoot(absentRoots, source) !== undefined)
+        return source;
       if (agent === "claude" && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined && source.reviewArtifact === undefined && [undefined, "bytes", "path-bytes"].includes(source.hashMode) && isClaudePluginCacheOrphanMarker(source.path)) {
         return { path: source.path, hashMode: CLAUDE_ORPHAN_MARKER_MODE, sha256: hashClaudePluginCacheOrphanMarker(source.path) };
       }
@@ -46933,6 +46942,11 @@ function resolveAgentDiscovery(options) {
     });
     if (agent === "claude")
       assertReviewedClaudeCacheClosures(home, config, review, canonical9);
+    for (const root2 of absentRoots) {
+      safe6(root2);
+      if (lstatSync28(root2, { throwIfNoEntry: false }))
+        throw new Error("Retired native materialization changed during discovery review");
+    }
     const combined = [...reviewedSources, ...reviewedSourcesWithManifestProjection];
     const unique = combined.filter((source, index) => combined.findIndex((candidate2) => isDeepStrictEqual8(candidate2, source)) === index);
     return { ...supplied, roots: [...new Set([...roots, ...supplied.roots])].sort(), sources: unique, ...agent === "gemini" ? { builtinNames } : {} };
@@ -48259,11 +48273,19 @@ function planAgentIntegration(options) {
     const executable2 = discoveryExecutable(agent) ?? (prior ? recordedDiscoveryExecutable(agent, prior) : null);
     executables.set(agent, executable2);
     const retainedReview = options.discoveryInputs === undefined && policy.bridge?.discovery?.[agent]?.method === "reviewed" ? { ...policy.bridge.discovery[agent], ...agent === "codex" ? { codexDisabledPluginSkills: policy.bridge.codexPluginSkills ?? [] } : {} } : undefined;
-    if (retainedReview) {
-      assertManagedAgentBridge(agent, { home, dataDir: dataDir2, projectDir: options.projectDir ?? home });
-      retainedAgents.push(agent);
+    try {
+      if (retainedReview) {
+        assertRetainedReviewState(agent, { home, dataDir: dataDir2, projectDir: options.projectDir ?? home });
+        retainedAgents.push(agent);
+      }
+      return resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, retainedReview, canonical: (path) => canonicalAgentPath(path, aliases), executable: executable2 });
+    } catch (error) {
+      if (isDiscoveryRootUnresolved(error) || error instanceof SumiPathResolverError || error instanceof NativeSkillCopiesDriftError)
+        throw error;
+      if (!retainedReview)
+        throw error;
+      throw new Error(`NATIVE_SKILL_DRIFT: ${error.message.replace(/^NATIVE_SKILL_DRIFT: /, "")}. This agent reuses a saved discovery review and that review no longer verifies, so a fresh explicit review is required: skills hook install --agent ${agent} --discovery-inputs <review> --apply.`);
     }
-    return resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, retainedReview, canonical: (path) => canonicalAgentPath(path, aliases), executable: executable2 });
   });
   const codexConfigBefore = options.agents.includes("codex") ? readOptional(canonicalAgentPath(join33(home, ".codex", "config.toml"), aliases)) : null;
   const codexConfig = Bun.TOML.parse(codexConfigBefore ?? "");
@@ -49017,7 +49039,7 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
   assertCurrent();
   recheckRootAliases(aliases);
   for (const agent of plan.retainedReviewChecks?.agents ?? [])
-    assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
+    assertRetainedReviewState(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
   if (plan.reviewArtifactMigration) {
     const verified = planReviewedArtifactMigration(plan.reviewArtifactMigration);
     if (JSON.stringify(verified.changes) !== JSON.stringify(plan.changes) || JSON.stringify(verified.discoveryAfter) !== JSON.stringify(plan.discoveryAfter))
@@ -49060,6 +49082,8 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
   if (!plan.changes.length) {
     assertCurrent();
     recheckRootAliases(aliases);
+    for (const agent of plan.retainedReviewChecks?.agents ?? [])
+      assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
     return { changed: [], backups, ...aliases.length ? { rootAliases: aliases } : {} };
   }
   assertSafePath(backupRoot);
@@ -49109,6 +49133,8 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
     }
     for (const agent of plan.managedAgentChecks?.agents ?? [])
       assertManagedAgentBridge(agent, { home: plan.managedAgentChecks.home, dataDir: plan.dataDir, projectDir: plan.managedAgentChecks.projectDir ?? plan.managedAgentChecks.home });
+    for (const agent of plan.retainedReviewChecks?.agents ?? [])
+      assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
     atomicWrite2(join33(backupRoot, "receipt.json"), JSON.stringify({ version: 1, changes: written.map((change) => ({ path: change.path, beforeHash: change.before === null ? null : sha5(change.before), afterHash: sha5(change.after) })), backups, ...plan.cacheWitnessUpgrade ? { cacheWitnessUpgrade: plan.cacheWitnessUpgrade } : {}, ...plan.retainedReviewArtifacts?.length ? { retainedReviewArtifacts: plan.retainedReviewArtifacts.map((item) => ({ path: item.path, ...item.artifact })) } : {}, ...aliases.length ? { rootAliases: aliases } : {} }) + `
 `);
   } catch (error) {
@@ -49440,7 +49466,7 @@ enabled = false
 function assertManagedAgentBridge(agent, options = {}) {
   return assertManagedAgentBridgeWithDiscovery(agent, options);
 }
-function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscovery) {
+function assertManagedBridgeCustody(agent, options = {}, provenDiscovery) {
   const home = resolve27(options.home ?? homedir3()), dataDir2 = options.dataDir ?? getDataDirReadOnly();
   assertSafePath(join33(dataDir2, "agent-policy.json"));
   const snapshot2 = readManagedSkillPolicySnapshot(dataDir2);
@@ -49457,7 +49483,6 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
   if (!isOwnedCliBridge(expected, [expected]))
     throw new Error("NATIVE_SKILL_DRIFT: the native Skills bridge is missing or modified; repair it before continuing");
   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", "sumi"].includes(agent) && entry.path.includes(`${sep14}.agents${sep14}skills${sep14}`) || ["opencode", "sumi"].includes(agent) && entry.agent === "claude";
   const discovery = provenDiscovery ?? binding.discovery?.[agent];
   assertProjectDiscovery(agent, [...roots], home, (path) => canonicalAgentPath(path, aliases), discovery);
   for (const source of discovery?.sources ?? [])
@@ -49472,11 +49497,30 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
     throw new Error("NATIVE_SKILL_DRIFT: the native hook command/profile binding is missing");
   if (options.profileId !== undefined && options.profileId !== profile)
     throw new Error("NATIVE_SKILL_DRIFT: the hook selection profile differs from its managed binding; restart the native client after reviewing skills hook install");
+  return { home, dataDir: dataDir2, binding, aliases, expected, roots, discovery, configPath, config, command, profile };
+}
+function assertUnrepairableBridgeProtection(custody, agent) {
+  if (agent !== "hermes")
+    return;
+  const { home, dataDir: dataDir2, binding, config, command, profile } = custody;
+  const supervisor = binding.supervisors?.hermes;
+  if (supervisor?.path !== join33(dataDir2, "agent-hooks", "hermes.js") || supervisor?.sha256 !== sha5(renderHermesSupervisor(command, profile)))
+    throw new Error("NATIVE_SKILL_DRIFT: Hermes supervisor binding changed; run skills hook install");
+  assertHermesProtection(home, config, command, profile, supervisor);
+}
+function assertRetainedReviewState(agent, options) {
+  const custody = assertManagedBridgeCustody(agent, options);
+  assertUnrepairableBridgeProtection(custody, agent);
+  assertManagedNativeDiscovery(custody, agent, options);
+}
+
+class NativeSkillCopiesDriftError extends Error {
+}
+function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscovery) {
+  const custody = assertManagedBridgeCustody(agent, options, provenDiscovery);
+  const { home, aliases, expected, discovery, config, command, profile } = custody;
   if (agent === "hermes") {
-    const supervisor = binding.supervisors?.hermes;
-    if (supervisor?.path !== join33(dataDir2, "agent-hooks", "hermes.js") || supervisor?.sha256 !== sha5(renderHermesSupervisor(command, profile)))
-      throw new Error("NATIVE_SKILL_DRIFT: Hermes supervisor binding changed; run skills hook install");
-    assertHermesProtection(home, config, command, profile, supervisor);
+    assertUnrepairableBridgeProtection(custody, agent);
   } else if (agent === "sumi") {
     if (JSON.stringify(config.permissions?.filter((rule) => rule.action === "skill")) !== JSON.stringify(SUMI_SKILL_PERMISSIONS) || !isManagedSumiPlugin(readOptional(join33(sumiConfigDirectory(home, process.env, options.projectDir ?? process.cwd()), "plugins", "skills-cli.js")), command, profile))
       throw new Error("NATIVE_SKILL_DRIFT: Sumi bridge protection changed; run skills hook install");
@@ -49498,6 +49542,21 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
     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");
   }
+  if (agent === "codex") {
+    const codexConfig = Bun.TOML.parse(readOptional(canonicalAgentPath(join33(home, ".codex", "config.toml"), aliases)) ?? "");
+    if (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, join33(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
+    if ([...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");
+  }
+  if (agent === "gemini" && discovery && !discovery.builtinNames?.every((name) => config.skills.disabled.includes(name)))
+    throw new Error("NATIVE_SKILL_DRIFT: an installed Gemini builtin is not disabled");
+  return assertManagedNativeDiscovery(custody, agent, options);
+}
+function assertManagedNativeDiscovery(custody, agent, options) {
+  const { home, dataDir: dataDir2, binding, aliases, expected, roots, discovery } = custody;
+  const visible = (entry) => entry.agent === agent || ["codex", "gemini", "opencode", "hermes", "sumi"].includes(agent) && entry.path.includes(`${sep14}.agents${sep14}skills${sep14}`) || ["opencode", "sumi"].includes(agent) && entry.agent === "claude";
   const codexPath = canonicalAgentPath(join33(home, ".codex", "config.toml"), aliases);
   const vendorCache = canonicalAgentPath(join33(home, ".codex", "plugins", "cache"), aliases);
   const witnessTolerance = agent === "codex" && options.codexPromptHook === true ? {
@@ -49508,11 +49567,6 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
   if (options.codexDiscoveryRecovery && (agent !== "codex" || options.codexDiscoveryRecovery.configPath !== codexPath))
     throw new Error("NATIVE_SKILL_DRIFT: Codex trust recovery names a different configuration root");
   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, join33(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
-  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");
   if (agent === "codex" && !reviewedCodexPluginCapabilitiesUnchanged(canonicalAgentPath(join33(home, ".codex/plugins/cache"), aliases), binding.codexPluginSkills ?? [], (path) => new TextDecoder("utf-8", { fatal: true }).decode(readNativeBytes(path, 1024 * 1024)), codexConfig.skills?.config ?? []))
     throw new Error("NATIVE_SKILL_DRIFT: reviewed native plugin capability controls changed; run skills hook install with a fresh discovery review");
   const disabledPlugin = (entry) => {
@@ -49549,8 +49603,6 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
   };
   if (!discovery || discovery.agent !== agent)
     throw new Error("NATIVE_SKILL_DRIFT: native discovery coverage is missing; run skills hook install");
-  if (agent === "gemini" && !discovery.builtinNames?.every((name) => config.skills.disabled.includes(name)))
-    throw new Error("NATIVE_SKILL_DRIFT: an installed Gemini builtin is not disabled");
   try {
     verifyAgentDiscovery(agent === "codex" ? { ...discovery, codexDisabledPluginSkills: binding.codexPluginSkills ?? [] } : discovery, options.codexDiscoveryRecovery, aliases, witnessTolerance);
     if (agent === "sumi" && discovery.method === "reviewed")
@@ -49605,7 +49657,7 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
         return false;
       }
     }, read: (path) => new TextDecoder("utf-8", { fatal: true }).decode(readNativeBytes(path, 1024 * 1024)) });
-    throw new Error(`NATIVE_SKILL_DRIFT: ${blocking.length} unexpected native skill copies were found: ${nativeSkillPathList(blocking.map((entry) => entry.path))}. ${remediation}${adapterRefusal ? ` Native policy adapter refused: ${adapterRefusal}` : ""}`);
+    throw new NativeSkillCopiesDriftError(`NATIVE_SKILL_DRIFT: ${blocking.length} unexpected native skill copies were found: ${nativeSkillPathList(blocking.map((entry) => entry.path))}. ${remediation}${adapterRefusal ? ` Native policy adapter refused: ${adapterRefusal}` : ""}`);
   }
   recheckRootAliases(aliases);
   const discoveryChanges = (witnessTolerance?.changes ?? []).filter((change, index, all) => all.findIndex((other) => other.kind === change.kind && other.path === change.path) === index);
@@ -50460,8 +50512,8 @@ function ensureInstructionSkillFiles(skillPath, manifest) {
     displayName: manifest.displayName ?? displayName(manifest.name),
     category: manifest.category ?? "Development Tools",
     tags: manifest.tags?.length ? manifest.tags : ["custom", manifest.name],
-    inputs: [],
-    commands: []
+    inputs: Array.isArray(manifest.inputs) ? manifest.inputs : [],
+    commands: Array.isArray(manifest.commands) ? manifest.commands : []
   };
   if (!existsSync9(join35(skillPath, "SKILL.md"))) {
     writeFileSync6(join35(skillPath, "SKILL.md"), renderSkillMd(next));
@@ -51861,10 +51913,33 @@ function searchSkills(query, registry = loadRegistry()) {
   scored.sort((a, b) => b.score - a.score);
   return scored.map((s) => s.skill);
 }
+function findCloseSkillNames(query, names, maxResults = 3) {
+  if (maxResults <= 0)
+    return [];
+  const q = query.trim().toLowerCase();
+  if (q.length === 0)
+    return [];
+  const tokens = q.split("-").filter(Boolean);
+  const ranked = [];
+  if (q.length >= 3) {
+    for (const name of names) {
+      const candidate2 = name.toLowerCase();
+      const rank = candidate2 === q ? 0 : candidate2.endsWith(`-${q}`) || candidate2.startsWith(`${q}-`) ? 1 : tokens.length > 1 && tokens.every((token) => candidate2.split("-").includes(token)) ? 2 : undefined;
+      if (rank !== undefined)
+        ranked.push([name, rank]);
+    }
+  }
+  ranked.sort((a, b) => a[1] - b[1] || a[0].length - b[0].length || a[0].localeCompare(b[0]));
+  const found = ranked.slice(0, maxResults).map(([name]) => name);
+  if (found.length === maxResults)
+    return found;
+  const taken = new Set(found);
+  const threshold = Math.max(3, Math.floor(q.length / 2));
+  const byDistance = names.filter((name) => !taken.has(name)).map((name) => ({ name, distance: editDistance(q, name.toLowerCase()) })).filter((entry) => entry.distance <= threshold).sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+  return [...found, ...byDistance.slice(0, maxResults - found.length).map((entry) => entry.name)];
+}
 function findSimilarSkills(query, maxResults = 3, registry = loadRegistry()) {
-  const q = query.toLowerCase();
-  const scored = registry.map((s) => ({ name: s.name, dist: editDistance(q, s.name.toLowerCase()) })).filter((s) => s.dist <= Math.max(3, Math.floor(q.length / 2))).sort((a, b) => a.dist - b.dist);
-  return scored.slice(0, maxResults).map((s) => s.name);
+  return findCloseSkillNames(query, registry.map((skill) => skill.name), maxResults);
 }
 // src/lib/registry.ts
 function isBasicSkillName(name) {
@@ -52885,11 +52960,31 @@ function exactProfileSelection(spec, profile) {
   const at = spec.lastIndexOf("@");
   const slug = at > 0 ? spec.slice(0, at) : spec;
   const version2 = at > 0 ? spec.slice(at + 1) : undefined;
-  const selection2 = profile.selections.find((entry) => (entry.slug === slug || entry.aliases?.includes(slug)) && (version2 === undefined || version2 === entry.version));
-  if (!selection2 || version2 === "")
-    throw new SkillSelectionError("SKILL_NOT_SELECTED", "The requested exact skill version is not selected by this profile or project lock.");
+  const named = profile.selections.filter((entry) => entry.slug === slug || entry.aliases?.includes(slug));
+  if (version2 === "")
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", emptyVersionRefusal(spec));
+  if (named.length === 0)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", unknownNameRefusal(slug, profile));
+  const selection2 = version2 === undefined ? named[0] : named.find((entry) => entry.version === version2);
+  if (!selection2)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", wrongVersionRefusal(slug, version2, named));
   return selection2;
 }
+var ACCEPTED_FORM = "Accepted form: '<slug>' or '<slug>@<version>'.";
+function emptyVersionRefusal(spec) {
+  return `The requested name '${spec}' has an empty version. ${ACCEPTED_FORM}`;
+}
+function wrongVersionRefusal(slug, version2, named) {
+  const versions = [...new Set(named.map((entry) => entry.version))].sort();
+  const canonical9 = named[0].slug;
+  return `Skill '${slug}' is selected at version '${versions.join("', '")}', but '${version2}' was requested. ` + `Accepted form: '${canonical9}@${versions[0]}'.`;
+}
+function unknownNameRefusal(slug, profile) {
+  const names = profile.selections.flatMap((entry) => [entry.slug, ...entry.aliases ?? []]);
+  const close = findCloseSkillNames(slug, names);
+  const hint = close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : "";
+  return `Skill '${slug}' is not selected by this Skills profile or project lock.${hint} ` + `Read the accepted names with 'skills search <term>' or 'skills list --all --json'; accept one with 'skills pin <name>'. ${ACCEPTED_FORM}`;
+}
 
 // src/lib/selected-run.ts
 async function resolveSelectedRun(spec, profileId, options = {}) {
@@ -52898,12 +52993,51 @@ async function resolveSelectedRun(spec, profileId, options = {}) {
   const entries = await readSelectedEntries(selection2, context, options);
   return { selection: selection2, profileId: context.receipt.profile.profileId, entries, ...describeEntries(entries), cacheDir: selectionCacheRoot(options) };
 }
+function declaredOperation(manifest) {
+  const entry = instructionCommandEntry(manifest);
+  if (!entry)
+    return null;
+  const runtime = manifest.runtime;
+  if (!runtime || typeof runtime !== "object" || Array.isArray(runtime))
+    return null;
+  if (runtime.runtime !== "bun" && runtime.runtime !== "node" && runtime.runtime !== "python3")
+    return null;
+  if (instructionEntrypointMismatch(manifest))
+    return null;
+  return { entry };
+}
+function instructionCommandEntry(manifest) {
+  const commands = Array.isArray(manifest.commands) ? manifest.commands : [];
+  const command = commands[0];
+  if (!command || typeof command !== "object" || typeof command.entry !== "string" || command.entry.length === 0)
+    return null;
+  return command.entry;
+}
+function instructionEntrypointMismatch(manifest) {
+  const entry = instructionCommandEntry(manifest);
+  const declared = manifest.runtime;
+  if (!entry || !declared || typeof declared !== "object" || Array.isArray(declared))
+    return null;
+  const runtimeEntrypoint = declared.entrypoint;
+  return typeof runtimeEntrypoint === "string" && runtimeEntrypoint !== entry ? runtimeEntrypoint : null;
+}
+function instructionRunRefusal(manifest, isBundledFile) {
+  const declaredEntry = instructionCommandEntry(manifest);
+  if (declaredEntry && !isBundledFile(declaredEntry))
+    return { code: "LOCAL_ENTRYPOINT_MISSING", message: `This selected instruction skill declares its operation entry as ${declaredEntry}, which is not a regular file in the selected bundle; a different runtime.entrypoint never substitutes for it.` };
+  const mismatch = instructionEntrypointMismatch(manifest);
+  if (mismatch)
+    return { code: "LOCAL_ENTRYPOINT_MISMATCH", message: `This selected instruction skill declares its operation entry as ${declaredEntry}, but its runtime.entrypoint is ${mismatch}; the two must agree.` };
+  if (!declaredOperation(manifest))
+    return { code: "INSTRUCTION_SKILL", message: "This selected skill contains instructions. Use skills load instead of skills run." };
+  return null;
+}
 async function prepareSelectedSecretBindings(selected, cwd = process.cwd()) {
   const entries = await readCachedSelection(selected.selection, { cacheDir: selected.cacheDir });
   if (!entries)
     throw new SkillSelectionError("CACHED_BUNDLE_MISSING", "The selected execution bundle is not cached.");
   const { kind, manifest } = describeEntries(entries);
-  if (kind !== "executable")
+  if (kind !== "executable" && !declaredOperation(manifest))
     throw new SkillSelectionError("INSTRUCTION_SKILL", "Instruction skills do not accept execution secret bindings.");
   const names = declaredSecretNames(manifest.runtime?.env);
   if (!names.length)
@@ -52916,8 +53050,12 @@ async function executeSelectedLocal(selected, options = {}) {
   if (!entries)
     throw new SkillSelectionError("CACHED_BUNDLE_MISSING", "The selected local execution bundle is not cached.");
   const { kind, manifest, packageJson } = describeEntries(entries);
-  if (kind === "instruction")
-    throw new SkillSelectionError("INSTRUCTION_SKILL", "This selected skill contains instructions. Use skills load instead of skills run.");
+  const operation = declaredOperation(manifest);
+  if (kind === "instruction") {
+    const refusal2 = instructionRunRefusal(manifest, (path) => entries.some((entry) => entry.path === path));
+    if (refusal2)
+      throw new SkillSelectionError(refusal2.code, refusal2.message);
+  }
   const runtime = manifest.runtime ?? {};
   if (!runtime || typeof runtime !== "object" || Array.isArray(runtime))
     throw new SkillSelectionError("INVALID_SKILL_MANIFEST", "The selected runtime declaration is invalid.");
@@ -52936,9 +53074,9 @@ async function executeSelectedLocal(selected, options = {}) {
   const executable2 = runtimeName === "bun" ? process.execPath : Bun.which(runtimeName);
   if (!executable2)
     throw new SkillSelectionError("LOCAL_RUNTIME_UNAVAILABLE", "The selected runtime is not installed on this station.");
-  const declaredEntry = runtime.entrypoint ?? (typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin && typeof packageJson.bin === "object" ? Object.values(packageJson.bin)[0] : undefined);
+  const declaredEntry = (kind === "instruction" ? operation?.entry : undefined) ?? runtime.entrypoint ?? (typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin && typeof packageJson.bin === "object" ? Object.values(packageJson.bin)[0] : undefined);
   if (typeof declaredEntry !== "string" || !entries.some((entry) => entry.path === declaredEntry))
-    throw new SkillSelectionError("LOCAL_ENTRYPOINT_MISSING", "The selected bundle must declare a regular-file entrypoint in its runtime manifest or package bin.");
+    throw new SkillSelectionError("LOCAL_ENTRYPOINT_MISSING", kind === "instruction" ? "The selected instruction skill must declare the operation entrypoint it ships in its manifest, and that declared entry must be a regular file in the selected bundle; a different runtime.entrypoint never substitutes for it." : "The selected bundle must declare a regular-file entrypoint in its runtime manifest or package bin.");
   const args = options.args ?? [];
   if (args.length > 128 || args.some((arg) => typeof arg !== "string" || arg.length > 16384 || arg.includes("\x00")))
     throw new SkillSelectionError("INVALID_RUN_INPUT", "Local skill arguments exceed their limits.");
@@ -53013,6 +53151,7 @@ async function executeSelectedLocal(selected, options = {}) {
     selection: selection2,
     target: "local",
     runtime: runtimeName,
+    entrypoint: declaredEntry,
     inputDigest: `sha256:${createHash32("sha256").update(input).digest("hex")}`,
     runDirectory,
     ...executionGrant ? { executionGrant } : {},

package/docs/plugin-admission.md

@@ -354,7 +354,8 @@ What the software currently enforces is narrower:
   non-null hash. A non-string `hooks` value and a `hooks` target outside the
   plugin root are refused. A manifest listed as `claude-plugin-manifest-v1`
   (the form Skills writes into the stored policy) or as `path-bytes` triggers
-  no hook-file requirement. Nothing else is required.
+  no hook-file requirement, and neither does a manifest the absent retired
+  version rule below retains. Nothing else is required.
 - A `hooks/hooks.json` that is absent at review time and appears later is
   detected if the review pins it with `sha256: null` or covers it with a
   reviewed `directories` membership witness on the plugin root or its `hooks/`
@@ -383,7 +384,7 @@ What the software currently enforces is narrower:
   `captureDiscoveryPathSources` (including the installer `path-bytes`
   operation) produces a `claude-plugin-orphaned-at-v1` witness, and a fresh
   explicit review converts a plain byte or `path-bytes` witness of it to that
-  form. The witness binds the marker's presence or absence, not its bytes or
+  form, unless the absent retired version rule below retains it. The witness binds the marker's presence or absence, not its bytes or
   inode. Every capture and check still requires a regular, non-symlink file
   owned by the current user, at most 32 bytes, matching `^[1-9][0-9]{12}$`.
   The name stays in `directories` membership, so other added or removed names
@@ -392,17 +393,20 @@ What the software currently enforces is narrower:
   that binds the marker's bytes keeps that meaning and needs one fresh review.
 - An entirely absent retired Claude version root exempts only its plain byte
   sources (`hashMode` omitted or `"bytes"`, with no `format`, `fields` or
-  `managedPlugins`) and a present `claude-plugin-orphaned-at-v1` marker. Such a
-  source with a non-null `sha256` is also the only
+  `managedPlugins`), its `.claude-plugin/plugin.json` as a
+  `claude-plugin-manifest-v1` witness and a present
+  `claude-plugin-orphaned-at-v1` marker. Such a source with a non-null
+  `sha256` is also the only
   thing that identifies the root, and the root qualifies only while it stays
   entirely absent and the reviewed settings and registry select a different,
   verified version. Every other source under that root is re-hashed as usual,
   and one whose file existed at review no longer matches its hash, so the
-  check refuses. That includes the plugin manifest in the
-  `claude-plugin-manifest-v1` form Skills stores, so a stored review that lists
-  the retired version's manifest refuses until a fresh review replaces it. A
-  `directories` witness that covers the retired root is not exempt either. If
-  the root reappears, its sources are checked again.
+  check refuses. A `directories` witness that covers the retired root is not
+  exempt either. An explicit review (`--discovery-inputs`) keeps each exempt
+  source exactly as listed: it does not project a byte-witnessed manifest,
+  require its hook files or convert a byte-witnessed marker, so a historical
+  byte witness keeps its meaning. If the root reappears, its sources are
+  checked again.
 - It is detection-only. Later checks re-hash the stored sources and re-walk any
   reviewed `directories` witnesses. Drift makes the
   Skills hooks refuse with `NATIVE_SKILL_DRIFT`; it does not stop, unload or

package/docs/skill-standard.md

@@ -91,10 +91,24 @@ existing Codewith conventions):
   `package.json`, a non-empty `bin`, and `src/index.ts`. `skills run` executes it.
 - `kind: instruction` — a `SKILL.md`-primary prose skill for coding agents.
   `package.json`, `bin`, and `src/` are all optional. Instruction skills may still
-  bundle optional helper scripts (a `bin`/`src` is permitted, not forbidden), but
-  they are consumed by agents via `SKILL.md`, not executed. `skills run` on an
-  instruction skill returns a clear "not runnable — instruction skill" error
-  instead of executing a stub.
+  bundle optional helper scripts (a `bin`/`src` is permitted, not forbidden) and
+  are consumed by agents via `SKILL.md`. `skills run` refuses a prose-only
+  instruction skill with a clear "not runnable — instruction skill" error instead
+  of executing a stub.
+- An instruction skill may instead declare the one operation it ships: the first
+  `commands` entry, naming its helper, together with an explicit `runtime`
+  contract. `skills run` then executes exactly that declared entrypoint from the
+  selected bundle — the same immutable object, digest receipt, argument,
+  timeout, output and no-ambient-credential contract an executable skill gets —
+  and still refuses the skill when it declares no operation or no runtime. The
+  declared command entry is the authority: it must be a regular file in the
+  selected bundle, and a `runtime.entrypoint` that disagrees with it is an
+  inconsistent declaration that refuses (`LOCAL_ENTRYPOINT_MISMATCH`) rather than
+  running the other file. A declared entry missing from the bundle refuses
+  (`LOCAL_ENTRYPOINT_MISSING`) and is never substituted, and the mutable
+  authoring corpus is never executed. Executable skills keep their own
+  precedence (`runtime.entrypoint`, then `package.json` bin) unchanged, and cloud
+  execution keeps requiring an executable skill version.
 
 New scaffolds always record their selected kind. Legacy local readers retain
 their executable fallback, while the legacy publication API retains its

package/package.json

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