@zhushanwen/pi-exec-skills 0.2.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@zhushanwen/pi-exec-skills",
+  "version": "0.2.0",
+  "description": "Shared skill acquisition library for Pi extensions — disk-scanning discovery over pi's four skill roots (settings overrides + plan-exec frontmatter marker + name dedup) and the pi-registry execution gate (resolveSkills). Shared library, not a Pi extension.",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "skills",
+    "shared",
+    "skill-discovery",
+    "execution-gate"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@zhushanwen/pi-extension-logger": "0.6.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/exec-skills.test.ts

@@ -0,0 +1,449 @@
+import * as fs from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock 共享 logger：降级规格的 warn 留痕可 spy
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => loggerMock,
+  createLogger: () => loggerMock,
+  setPiHandle: vi.fn(),
+}));
+
+// 对拍锚点直接用 node_modules 实装（pi 0.84.4 dist，AGENTS.md 语义断言约定）——
+// 本测试钉跨根组装 / overrides / marker 过滤 / 降级四段共享包自身语义，另设
+// pi 单根规则快照与对拍等价锚（单根枚举横切规则随 pi 实装走，pi bump 改规则时红灯）
+import { loadSkillsFromDir } from "@earendil-works/pi-coding-agent";
+
+import { detectExecSkills, hasPlanExecMarker, isEnabledByOverrides } from "../exec-skills.js";
+import type { ExecSkill } from "../exec-skills.js";
+
+/** SKILL.md 内容构造（frontmatter 字段按需） */
+function skillMd(opts: {
+  name?: string;
+  description?: string;
+  planExec?: boolean;
+  disableModelInvocation?: boolean;
+}): string {
+  const lines = ["---"];
+  if (opts.name !== undefined) lines.push(`name: ${opts.name}`);
+  lines.push(`description: ${opts.description ?? "Execute development workflows."}`);
+  if (opts.planExec) lines.push("plan-exec: true");
+  if (opts.disableModelInvocation) lines.push("disable-model-invocation: true");
+  lines.push("---", "", "# Skill body");
+  return lines.join("\n");
+}
+
+/** 四根 fixture 世界：project（.git + 嵌套 cwd + .pi/skills）/ 祖先链 / agentDir / home */
+function makeWorld(): { root: string; cwd: string; agentDir: string; homeDir: string } {
+  const root = fs.mkdtempSync(join(tmpdir(), "exec-skills-"));
+  const cwd = join(root, "proj", "packages", "lib");
+  fs.mkdirSync(join(cwd, ".pi", "skills"), { recursive: true });
+  fs.mkdirSync(join(root, "proj", ".git"), { recursive: true });
+  fs.mkdirSync(join(root, "proj", "packages", ".agents", "skills"), { recursive: true });
+  fs.mkdirSync(join(root, "proj", ".agents", "skills"), { recursive: true });
+  const agentDir = join(root, "agent");
+  fs.mkdirSync(join(agentDir, "skills"), { recursive: true });
+  const homeDir = join(root, "home");
+  fs.mkdirSync(join(homeDir, ".agents", "skills"), { recursive: true });
+  return { root, cwd, agentDir, homeDir };
+}
+
+/** 在 dir 下建一个标准 SKILL.md 目录形态 skill（默认带 plan-exec marker） */
+function writeSkill(dir: string, content = skillMd({ planExec: true })): string {
+  fs.mkdirSync(dir, { recursive: true });
+  const skillPath = join(dir, "SKILL.md");
+  fs.writeFileSync(skillPath, content);
+  return skillPath;
+}
+
+function rmWorld(root: string): void {
+  fs.rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+}
+
+let world: ReturnType<typeof makeWorld>;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  world = makeWorld();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  rmWorld(world.root);
+});
+
+const detect = (overrides: Partial<Parameters<typeof detectExecSkills>[0]> = {}) =>
+  detectExecSkills({
+    cwd: world.cwd,
+    trusted: true,
+    agentDir: world.agentDir,
+    homeDir: world.homeDir,
+    ...overrides,
+  });
+
+const namesOf = (skills: ExecSkill[]) => skills.map((s) => s.name);
+
+describe("detectExecSkills（发现：四根目录扫描，pi 本体加载集对齐）", () => {
+  it("enumerates all four roots in pi order: .pi/skills → 祖先链(近→远) → agentDir → ~/.agents/skills", () => {
+    writeSkill(join(world.cwd, ".pi", "skills", "lib-skill"));
+    writeSkill(join(world.root, "proj", "packages", ".agents", "skills", "mid-skill"));
+    writeSkill(join(world.root, "proj", ".agents", "skills", "root-skill"));
+    writeSkill(join(world.agentDir, "skills", "agent-skill"));
+    writeSkill(join(world.homeDir, ".agents", "skills", "home-skill"));
+
+    const skills = detect();
+    expect(namesOf(skills)).toEqual(["lib-skill", "mid-skill", "root-skill", "agent-skill", "home-skill"]);
+    // skillEntryPath 数据通路：消费方指引的路径来源 = 入口文件路径（标准形态即 SKILL.md 路径）
+    expect(skills[0].skillEntryPath).toBe(join(world.cwd, ".pi", "skills", "lib-skill", "SKILL.md"));
+    expect(skills[0].description).toBe("Execute development workflows.");
+  });
+
+  it("untrusted skips the project family (.pi/skills + ancestor chain), still scans agentDir/home roots", () => {
+    writeSkill(join(world.cwd, ".pi", "skills", "lib-skill"));
+    writeSkill(join(world.root, "proj", ".agents", "skills", "root-skill"));
+    writeSkill(join(world.agentDir, "skills", "agent-skill"));
+
+    const skills = detect({ trusted: false });
+    expect(namesOf(skills)).toEqual(["agent-skill"]);
+  });
+
+  it("first-writer-wins: an earlier root occupies the name even without the marker", () => {
+    // pi 的 collision 语义以加载集为准——前根占名后根不让位（含 marker 缺席的占名）
+    writeSkill(join(world.cwd, ".pi", "skills", "dup"), skillMd({ planExec: false }));
+    writeSkill(join(world.agentDir, "skills", "dup"));
+
+    expect(namesOf(detect())).toEqual([]);
+  });
+
+  it("user settings '-' disable removes the skill across roots; '+' force-include wins over '!'", () => {
+    writeSkill(join(world.agentDir, "skills", "agent-skill"));
+    writeSkill(join(world.homeDir, ".agents", "skills", "home-skill"));
+    fs.writeFileSync(
+      join(world.agentDir, "settings.json"),
+      JSON.stringify({ skills: ["!agent-skill", "home-skill", "+home-skill"] }),
+    );
+
+    // '-' 强排除最优先：agent-skill 被禁；home-skill 经 '!' 禁止后又被 '+' 强制包含
+    expect(namesOf(detect())).toEqual(["home-skill"]);
+  });
+
+  it("project settings overrides apply only when trusted (untrusted project settings 恒不参与)", () => {
+    writeSkill(join(world.cwd, ".pi", "skills", "lib-skill"));
+    fs.writeFileSync(
+      join(world.cwd, ".pi", "settings.json"),
+      // '!' glob 前缀 pattern：靠 SKILL.md 父目录名命中
+      JSON.stringify({ skills: ["!lib-skill"] }),
+    );
+
+    expect(namesOf(detect({ trusted: true }))).toEqual([]);
+    expect(namesOf(detect({ trusted: false }))).toEqual([]);
+  });
+
+  it("glob disable pattern matches by parent dir name for SKILL.md entries", () => {
+    writeSkill(join(world.agentDir, "skills", "dev-flow"));
+    fs.writeFileSync(
+      join(world.agentDir, "settings.json"),
+      JSON.stringify({ skills: ["!dev-*"] }),
+    );
+
+    expect(namesOf(detect())).toEqual([]);
+  });
+
+  it("degrades per-item: broken YAML frontmatter skips that skill without throwing, siblings survive", () => {
+    // 非法 YAML：pi loadSkillFromFile 解析失败 → 该 skill 不进加载集（检测侧只见空位）
+    writeSkill(join(world.agentDir, "skills", "bad"), "---\nname: [unclosed\ndescription: x\n---\n# body\n");
+    writeSkill(join(world.agentDir, "skills", "good"));
+
+    expect(namesOf(detect())).toEqual(["good"]);
+  });
+
+  it("degrades per-root: EACCES root is skipped without throwing, other roots still detected", () => {
+    writeSkill(join(world.cwd, ".pi", "skills", "blocked-skill"));
+    writeSkill(join(world.homeDir, ".agents", "skills", "home-skill"));
+    fs.chmodSync(join(world.cwd, ".pi", "skills"), 0o000);
+    try {
+      // pi loadSkillsFromDirInternal 内部吞掉 readdir 错误返回空集（外层 try/catch 是纵深防御）
+      expect(namesOf(detect())).toEqual(["home-skill"]);
+    } finally {
+      fs.chmodSync(join(world.cwd, ".pi", "skills"), 0o755);
+    }
+  });
+
+  it("degrades per-root: settings parse failure is treated as no overrides with a warn", () => {
+    writeSkill(join(world.agentDir, "skills", "agent-skill"));
+    fs.writeFileSync(join(world.agentDir, "settings.json"), "{ not json");
+
+    const skills = detect();
+    expect(namesOf(skills)).toEqual(["agent-skill"]);
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      "exec-skills: settings parse failed (treated as no overrides)",
+      expect.objectContaining({ path: join(world.agentDir, "settings.json") }),
+    );
+  });
+
+  it("never throws: a cwd that vanishes mid-detection degrades to the empty set", () => {
+    // 整体降级规格：任何 fs 错 → 空集 + warn，绝不向消费方抛
+    const missingDir = join(world.root, "removed", "cwd");
+    const skills = detect({ cwd: missingDir });
+    expect(skills).toEqual([]);
+  });
+
+  it("missing roots are a legal default (no warn): fresh machines scan cleanly", () => {
+    // 空世界（各根目录存在但无 skill；agentDir/settings 缺失是常态主路径）
+    expect(detect()).toEqual([]);
+    expect(loggerMock.warn).not.toHaveBeenCalled();
+  });
+
+  it("HOME env injection: default homeDir derives from process.env.HOME (pi getHomeDir 同式)", () => {
+    vi.stubEnv("HOME", world.homeDir);
+    writeSkill(join(world.homeDir, ".agents", "skills", "home-skill"));
+
+    const skills = detectExecSkills({ cwd: world.cwd, trusted: true, agentDir: world.agentDir });
+    expect(namesOf(skills)).toEqual(["home-skill"]);
+  });
+
+  it("ancestor chain stops at a .git FILE (worktree 双语义), skills beyond the root are not proposed", () => {
+    // 独立世界：worktree 形态 .git 文件 + 链外根
+    const root = fs.mkdtempSync(join(tmpdir(), "exec-skills-wt-"));
+    try {
+      fs.mkdirSync(join(root, "wt"), { recursive: true });
+      fs.writeFileSync(join(root, "wt", ".git"), "gitdir: /elsewhere\n");
+      const cwd = join(root, "wt", "work");
+      writeSkill(join(cwd, ".agents", "skills", "inside-skill"));
+      writeSkill(join(root, ".agents", "skills", "outside-skill"));
+      const skills = detectExecSkills({ cwd, trusted: true, agentDir: join(root, "empty-agent"), homeDir: join(root, "empty-home") });
+      expect(namesOf(skills)).toEqual(["inside-skill"]);
+    } finally {
+      rmWorld(root);
+    }
+  });
+
+  it("cwd 在 HOME 下时祖先链与 ~/.agents/skills 的同路径项被滤掉（pi :1979 同款，不重复）", () => {
+    // 独立世界：home 即 git root，cwd 在其下——链会经过 home/.agents/skills（与第四根同路径）
+    const root = fs.mkdtempSync(join(tmpdir(), "exec-skills-dedup-"));
+    try {
+      const homeDir = join(root, "home");
+      fs.mkdirSync(join(homeDir, ".git"), { recursive: true });
+      const cwd = join(homeDir, "proj");
+      writeSkill(join(homeDir, ".agents", "skills", "home-skill"));
+      const skills = detectExecSkills({ cwd, trusted: true, agentDir: join(root, "empty-agent"), homeDir });
+      expect(namesOf(skills)).toEqual(["home-skill"]); // 恰一次
+    } finally {
+      rmWorld(root);
+    }
+  });
+
+  it("symlinked duplicate resolves to a single entry（realPath 去重）", () => {
+    const realSkillPath = writeSkill(join(world.cwd, ".pi", "skills", "dup"));
+    fs.symlinkSync(join(world.cwd, ".pi", "skills", "dup"), join(world.homeDir, ".agents", "skills", "alias"));
+    const skills = detect();
+    expect(namesOf(skills)).toEqual(["dup"]);
+    expect(skills[0].skillEntryPath).toBe(realSkillPath); // 入口文件路径（realPath 去重后指向真身）
+  });
+
+  it("plain patterns without +/-/! prefix are ignored for auto resources（pi getOverridePatterns 同款）", () => {
+    writeSkill(join(world.cwd, ".pi", "skills", "dev-flow"));
+    fs.writeFileSync(join(world.cwd, ".pi", "settings.json"), JSON.stringify({ skills: ["dev-flow"] }));
+    expect(namesOf(detect())).toEqual(["dev-flow"]);
+  });
+});
+
+describe("detectExecSkills（marker 过滤：plan-exec frontmatter 标记）", () => {
+  it("filters to skills carrying the plan-exec marker", () => {
+    writeSkill(join(world.agentDir, "skills", "marked"), skillMd({ planExec: true }));
+    writeSkill(join(world.agentDir, "skills", "plain"), skillMd({ planExec: false }));
+
+    expect(namesOf(detect())).toEqual(["marked"]);
+  });
+
+  it("disable-model-invocation coexists with the marker without filtering (user explicit choice is another channel)", () => {
+    writeSkill(
+      join(world.agentDir, "skills", "manual-only"),
+      skillMd({ planExec: true, disableModelInvocation: true }),
+    );
+
+    expect(namesOf(detect())).toEqual(["manual-only"]);
+  });
+});
+
+describe("hasPlanExecMarker（二次读 frontmatter）", () => {
+  it("accepts only the strict boolean true", () => {
+    const strictTrue = join(world.root, "strict.md");
+    const stringTrue = join(world.root, "string.md");
+    const absent = join(world.root, "absent.md");
+    fs.writeFileSync(strictTrue, "---\nplan-exec: true\n---\nbody");
+    fs.writeFileSync(stringTrue, "---\nplan-exec: \"true\"\n---\nbody");
+    fs.writeFileSync(absent, "---\ndescription: x\n---\nbody");
+
+    expect(hasPlanExecMarker(strictTrue)).toBe(true);
+    expect(hasPlanExecMarker(stringTrue)).toBe(false);
+    expect(hasPlanExecMarker(absent)).toBe(false);
+  });
+
+  it("read failure degrades to false with a warn (skill skipped)", () => {
+    const missing = join(world.root, "missing.md");
+    expect(hasPlanExecMarker(missing)).toBe(false);
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      "exec-skills: frontmatter read failed (skill skipped)",
+      expect.objectContaining({ path: missing }),
+    );
+  });
+});
+
+describe("isEnabledByOverrides（overrides 三级优先级，pi 同构）", () => {
+  const file = "/base/skills/demo/SKILL.md";
+
+  it("default enabled when no override matches", () => {
+    expect(isEnabledByOverrides(file, [], "/base")).toBe(true);
+    expect(isEnabledByOverrides(file, ["other-*"], "/base")).toBe(true);
+  });
+
+  it("'!' glob exclude disables, '+' exact force-include re-enables over '!'", () => {
+    expect(isEnabledByOverrides(file, ["!demo"], "/base")).toBe(false);
+    expect(isEnabledByOverrides(file, ["!demo", "+skills/demo/SKILL.md"], "/base")).toBe(true);
+  });
+
+  it("'-' exact force-exclude has the final say over '+' and '!'", () => {
+    expect(isEnabledByOverrides(file, ["!demo", "+demo", "-demo"], "/base")).toBe(false);
+  });
+
+  it("relative-path form hits SKILL.md excludes via the rel candidate", () => {
+    expect(isEnabledByOverrides(file, ["!skills/demo/SKILL.md"], "/base")).toBe(false);
+  });
+
+  it("glob 跨形态命中（parentName/rel glob/跨目录 glob）", () => {
+    const baseDir = join(world.root, "base");
+    const filePath = join(baseDir, "skills", "demo", "SKILL.md");
+    expect(isEnabledByOverrides(filePath, ["!demo"], baseDir)).toBe(false); // parentName
+    expect(isEnabledByOverrides(filePath, ["!skills/demo/*"], baseDir)).toBe(false); // rel glob
+    expect(isEnabledByOverrides(filePath, ["!**/SKILL.md"], baseDir)).toBe(false); // 跨目录 glob
+    expect(isEnabledByOverrides(filePath, ["!other"], baseDir)).toBe(true); // 未命中默认启用
+  });
+
+  // globToRegExp 未测分支（minimatch 子集重实现，与 pi 求值的偏差域）：? 单字符 /
+  // [...] 字符类（含取反）/ 未闭合 ] 字面量 / 正则元字符转义——经公开入口锁语义，
+  // 任一分支回归即红（false = 禁用命中，true = 默认启用未命中）。
+  it("? / 字符类 / 取反 / 未闭合 ] / 元字符转义分支", () => {
+    const baseDir = join(world.root, "base");
+    const filePath = join(baseDir, "skills", "demo", "SKILL.md");
+    // ? = 单字符且不跨 /：dem? 命中 o；demo? 差一字符不命中；skills?demo 不跨 / 不命中
+    expect(isEnabledByOverrides(filePath, ["!skills/dem?/SKILL.md"], baseDir)).toBe(false);
+    expect(isEnabledByOverrides(filePath, ["!skills/demo?/SKILL.md"], baseDir)).toBe(true);
+    expect(isEnabledByOverrides(filePath, ["!skills?demo/SKILL.md"], baseDir)).toBe(true);
+    // 字符类：[a-z] 命中 d；[0-9] 未命中
+    expect(isEnabledByOverrides(filePath, ["!skills/[a-z]emo/SKILL.md"], baseDir)).toBe(false);
+    expect(isEnabledByOverrides(filePath, ["!skills/[0-9]emo/SKILL.md"], baseDir)).toBe(true);
+    // 取反类：[!a-z] 排除小写字母 → d 不命中；[!0-9] 排除数字 → d 命中
+    expect(isEnabledByOverrides(filePath, ["!skills/[!a-z]emo/SKILL.md"], baseDir)).toBe(true);
+    expect(isEnabledByOverrides(filePath, ["!skills/[!0-9]emo/SKILL.md"], baseDir)).toBe(false);
+    // 未闭合 ]：[ 按字面量处理（不吞后续段），demo 目录无 [ → 不命中
+    expect(isEnabledByOverrides(filePath, ["!skills/demo[/SKILL.md"], baseDir)).toBe(true);
+    // 字符类单字：dem[o] 命中（dem 后是 o）；dem[w] 不命中（dem 后非 w）
+    expect(isEnabledByOverrides(filePath, ["!skills/dem[o]/SKILL.md"], baseDir)).toBe(false);
+    expect(isEnabledByOverrides(filePath, ["!skills/dem[w]/SKILL.md"], baseDir)).toBe(true);
+    // 正则元字符转义：. 与 $ 不提前终止/锚定匹配——dem.o（字面点）不命中 demo，
+    // demo$（字面 $）不命中；若未转义 . 会通配命中、$ 会锚定改变语义
+    expect(isEnabledByOverrides(filePath, ["!skills/dem.o/SKILL.md"], baseDir)).toBe(true);
+    expect(isEnabledByOverrides(filePath, ["!skills/demo$/SKILL.md"], baseDir)).toBe(true);
+    expect(isEnabledByOverrides(filePath, ["!skills/demo/SKILL.md"], baseDir)).toBe(false);
+  });
+});
+
+// 单根枚举横切规则的 pi 实装对拍：同 fixture 下共享包跨根结果 ⊆ pi 单根加载集；
+// 单根规则快照锁 pi 实装语义（ignore/description 门/name 派生/递归/node_modules/隐藏文件）
+describe("pi 实装对拍（loadSkillsFromDir 语义锚）", () => {
+  it("loadSkillsFromDir derives the skill name from frontmatter over dir name", () => {
+    writeSkill(join(world.agentDir, "skills", "dir-name"), skillMd({ name: "front-name", planExec: true }));
+
+    const loaded = loadSkillsFromDir({ dir: join(world.agentDir, "skills"), source: "detect" }).skills;
+    expect(loaded.map((s) => s.name)).toEqual(["front-name"]);
+    expect(namesOf(detect())).toEqual(["front-name"]);
+  });
+
+  /**
+   * 单根 fixture（挂在 agentDir/skills，其余根不存在）：
+   * - alpha：frontmatter name 覆盖目录名（⑥ name 派生）
+   * - beta：无 frontmatter name → 目录名 fallback（⑥）
+   * - no-desc：无 description → ③ 必填门排除
+   * - nested/deep/gamma：递归遍历
+   * - loose.md：根级散 .md（loadSkillsFromDir 收集，⑦登记面内）
+   * - ignored/：.gitignore 排除（①）
+   * - node_modules 与 .hidden：loader 内建排除
+   */
+  function makeAnchorRoot(): { root: string; agentDir: string } {
+    const root = fs.mkdtempSync(join(tmpdir(), "exec-skills-anchor-"));
+    const skillsRoot = join(root, "agent", "skills");
+    fs.mkdirSync(skillsRoot, { recursive: true });
+    writeSkill(join(skillsRoot, "alpha"), skillMd({ name: "custom-alpha", planExec: true }));
+    writeSkill(join(skillsRoot, "beta"), skillMd({ planExec: true }));
+    writeSkill(join(skillsRoot, "no-desc"), "---\nname: no-desc\n---\n\n# no description\n");
+    writeSkill(join(skillsRoot, "nested", "deep", "gamma"), skillMd({ planExec: true }));
+    // 根级散 .md（loadSkillsFromDir 收集形态；name 走 frontmatter——散文件 parentDir 名不可用）
+    fs.writeFileSync(join(skillsRoot, "loose.md"), skillMd({ name: "loose", planExec: true }));
+    writeSkill(join(skillsRoot, "ignored"), skillMd({ planExec: true }));
+    writeSkill(join(skillsRoot, "node_modules", "pkg"), skillMd({ planExec: true }));
+    writeSkill(join(skillsRoot, ".hidden"), skillMd({ planExec: true }));
+    fs.writeFileSync(join(skillsRoot, ".gitignore"), "ignored/\n");
+    return { root, agentDir: join(root, "agent") };
+  }
+
+  it("pi loadSkillsFromDir anchor：单根规则快照（①ignore/③description 门/⑥name 派生/递归/node_modules/隐藏文件）", () => {
+    const { root, agentDir } = makeAnchorRoot();
+    try {
+      const piResult = loadSkillsFromDir({ dir: join(agentDir, "skills"), source: "anchor" });
+      // pi 实装语义快照——pi bump 改单根规则时此处红灯（守卫边界 = 单根规则漂移）
+      expect(piResult.skills.map((s) => s.name).sort()).toEqual(["beta", "custom-alpha", "gamma", "loose"]);
+      expect(piResult.skills.some((s) => s.name === "no-desc")).toBe(false); // ③ description 必填门
+      expect(piResult.skills.some((s) => s.filePath.includes("ignored"))).toBe(false); // ① gitignore
+      expect(piResult.skills.some((s) => s.filePath.includes("node_modules"))).toBe(false);
+      expect(piResult.skills.some((s) => s.filePath.includes(".hidden"))).toBe(false);
+    } finally {
+      rmWorld(root);
+    }
+  });
+
+  it("detection per-root enumeration equals pi loadSkillsFromDir on the same fixture（对拍等价）", () => {
+    const { root, agentDir } = makeAnchorRoot();
+    try {
+      const piNames = loadSkillsFromDir({ dir: join(agentDir, "skills"), source: "anchor" })
+        .skills.map((s) => s.name).sort();
+      const detected = detectExecSkills({
+        cwd: join(root, "empty-cwd"),
+        trusted: true,
+        agentDir,
+        homeDir: join(root, "empty-home"),
+      });
+      // marker 过滤前的 pi 加载集 = 检测的单根并集；marker 只减不增
+      expect(piNames).toContain("custom-alpha"); // ⑥ frontmatter name
+      expect(piNames).toContain("beta");
+      expect(namesOf(detected).sort()).toEqual(["beta", "custom-alpha", "gamma", "loose"]);
+      // ⑥：消费方指引名与 pi prompt 列表一致（frontmatter name 而非目录名）
+      expect(detected.some((s) => s.name === "custom-alpha" && s.skillEntryPath.endsWith(join("alpha", "SKILL.md")))).toBe(true);
+      expect(detected.some((s) => s.name === "alpha")).toBe(false);
+    } finally {
+      rmWorld(root);
+    }
+  });
+
+  it("散 .md 形态：skillEntryPath = 文件路径本身（指引路径不悬空，⑦登记面内）", () => {
+    const { root, agentDir } = makeAnchorRoot();
+    try {
+      const detected = detectExecSkills({
+        cwd: join(root, "empty-cwd"),
+        trusted: true,
+        agentDir,
+        homeDir: join(root, "empty-home"),
+      });
+      const loose = detected.find((s) => s.name === "loose");
+      // 入口路径 = loose.md 文件本身——不是 `<skills根>/SKILL.md`（散 .md 形态拼 SKILL.md 必然悬空）
+      expect(loose?.skillEntryPath).toBe(join(agentDir, "skills", "loose.md"));
+    } finally {
+      rmWorld(root);
+    }
+  });
+});

package/src/__tests__/resolve-skills.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { normalizeSkillName, resolveSkills } from "../resolve-skills.js";
+
+/**
+ * fake skill 命令条目（SlashCommandInfo 形态：source === 'skill' + sourceInfo.path）。
+ * name 带 pi 命名空间前缀（`skill:<name>`）——真实 pi.getCommands() 枚举 skill 类
+ * 命令即此形态，归一化比对的靶子。
+ */
+const SKILL_COMMANDS = [
+  { name: "skill:tech-design", source: "skill", sourceInfo: { path: "/skills/tech-design/SKILL.md" } },
+  { name: "skill:dev-flow", source: "skill", sourceInfo: { path: "/skills/dev-flow/SKILL.md" } },
+  { name: "skill:code review", source: "skill", sourceInfo: { path: "/skills/code review/SKILL.md" } },
+  { name: "plan", source: "extension", sourceInfo: { path: "/extensions/universal/plan" } },
+];
+
+const makePi = (commands: unknown[] = SKILL_COMMANDS) =>
+  ({ getCommands: vi.fn(() => commands) }) as unknown as ExtensionAPI;
+
+describe("normalizeSkillName（skill: 命名空间前缀剥离）", () => {
+  it("strips the leading 'skill:' namespace prefix once", () => {
+    expect(normalizeSkillName("skill:tech-design")).toBe("tech-design");
+  });
+
+  it("leaves bare names untouched", () => {
+    expect(normalizeSkillName("tech-design")).toBe("tech-design");
+  });
+
+  it("only strips the prefix form, not a bare name that merely contains it", () => {
+    // skill: 前缀是命名空间标记，非子串替换——「xskill:y」的自然名不是「xy」
+    expect(normalizeSkillName("xskill:y")).toBe("xskill:y");
+  });
+});
+
+describe("resolveSkills（执行门禁：pi 注册表枚举比对，双向剥 skill: 前缀归一）", () => {
+  it("resolves prefixed enum entries from bare-name input (short name in resolved)", () => {
+    // 无前缀输入命中带前缀枚举（输入面：用户用自然技能名）
+    const resolution = resolveSkills(makePi(), ["tech-design", "code review"]);
+    expect(resolution.ok).toBe(true);
+    if (resolution.ok) {
+      expect(resolution.resolved).toEqual([
+        { name: "tech-design", skillPath: "/skills/tech-design/SKILL.md" },
+        { name: "code review", skillPath: "/skills/code review/SKILL.md" },
+      ]);
+    }
+  });
+
+  it("resolves explicit 'skill:'-prefixed input too (both directions normalize)", () => {
+    const resolution = resolveSkills(makePi(), ["skill:tech-design", "skill:dev-flow"]);
+    expect(resolution.ok).toBe(true);
+    if (resolution.ok) {
+      // resolved 用归一后的短名（无前缀）
+      expect(resolution.resolved).toEqual([
+        { name: "tech-design", skillPath: "/skills/tech-design/SKILL.md" },
+        { name: "dev-flow", skillPath: "/skills/dev-flow/SKILL.md" },
+      ]);
+    }
+  });
+
+  it("only compares entries with source === 'skill'", () => {
+    // 非 skill source 的命令（extension 等）不参与门禁——「plan」不被当作技能放行
+    const resolution = resolveSkills(makePi(), ["plan"]);
+    expect(resolution.ok).toBe(false);
+    if (!resolution.ok) {
+      expect(resolution.missing).toEqual(["plan"]);
+      // available 维持枚举原形态（带前缀，错误信息里可直接复制为 pi 命令）
+      expect(resolution.available).toEqual(["skill:tech-design", "skill:dev-flow", "skill:code review"]);
+    }
+  });
+
+  it("unknown skill reports missing together with the available list", () => {
+    const resolution = resolveSkills(makePi(), ["tech-design", "tech-desig"]);
+    expect(resolution.ok).toBe(false);
+    if (!resolution.ok) {
+      expect(resolution.missing).toEqual(["tech-desig"]);
+    }
+  });
+
+  it("prefixed-but-unknown input reports the normalized short name as missing", () => {
+    const resolution = resolveSkills(makePi(), ["skill:tech-desig"]);
+    expect(resolution.ok).toBe(false);
+    if (!resolution.ok) {
+      expect(resolution.missing).toEqual(["tech-desig"]);
+    }
+  });
+
+  it("empty request = 同族 fail-fast：ok:false + 全量 available + 空 missing（报错器的恢复动作输入）", () => {
+    // 「--skills 给了但没给名字」：missing 空 → 报错器走「no skill names followed it」
+    // 文案分支；available 同源枚举供报错文案直接列出可复制命令
+    const resolution = resolveSkills(makePi(), []);
+    expect(resolution.ok).toBe(false);
+    if (!resolution.ok) {
+      expect(resolution.missing).toEqual([]);
+      expect(resolution.available).toEqual(["skill:tech-design", "skill:dev-flow", "skill:code review"]);
+    }
+  });
+});

package/src/exec-skills.ts

@@ -0,0 +1,412 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+import {
+  CONFIG_DIR_NAME,
+  getAgentDir,
+  loadSkillsFromDir,
+  parseFrontmatter,
+} from "@earendil-works/pi-coding-agent";
+import type { Skill } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("pi-exec-skills");
+
+/**
+ * 技能目录扫描共享能力（ADR-0074 落地包）：项目内一切「发现可执行 skill」的磁盘
+ * 扫描单源，禁止各扩展自扫目录或直用 pi 注册表快照形成第二实现（pi 的
+ * getCommands 返回 resource loader 启动加载集——reload 才刷新的滞后快照）。
+ *
+ * 与 ./resolve-skills.js 的两段消费语义闭环（ADR-0074）：
+ * - 本模块 = 「发现」：自研扫描直读磁盘，技能安装即时可见；用于向用户提议
+ *   （表单列出可用执行方式）。
+ * - resolve-skills = 「执行门禁」：注入前经 pi 注册表确认 pi 实际认得该技能。
+ *
+ * 检测语义 = 「向用户提议的执行 skill」，以 pi 本体加载集为基线做意图/信任对齐：
+ * - 单根枚举复用 pi 公开导出 loadSkillsFromDir——单根内横切规则（ignore / description
+ *   必填门 / name 派生 / 递归遍历 / symlink / node_modules / 隐藏文件）随 pi 升级
+ *   自动同步，零漂移面（对照表①③⑥⑦ 的 SKILL.md 目录形态侧）；
+ * - 跨根组装自实现（pi 的四根拼装逻辑未导出，对照表②④⑤）：根序四枚按 pi 本体
+ *   `package-manager.js addAutoDiscoveredResources`——`.pi/skills` → 祖先链
+ *   `.agents/skills`（近→远，git root 级含）→ `<agentDir>/skills` → `~/.agents/skills`
+ *   （HOME 直取，dev-flow 等用户级 skill 标准安装位）；untrusted 跳过前两族（④）；
+ *   settings overrides 的 `+/-/!` 三级优先级 disable 复刻（②）；同名 first-writer-wins
+ *   + realPath 去重（⑤）；
+ * - plan-exec marker 过滤 = 对过 description 门的 skill 二次读 frontmatter
+ *   （`plan-exec: true`；pi 的 Skill 对象不保留原始 frontmatter）。skill 侧自愿
+ *   opt-in，`disable-model-invocation` 与 plan-exec 并存不过滤（用户显式选择是
+ *   另一通路，设计 D10 顺手裁决）。
+ * - steer 执行走路径读取（read `<skillEntryPath>` = skill 入口文件路径），不依赖 pi skill 注册。
+ *
+ * 已登记偏差（对照表⑦散 .md 形态）：与 pi auto 源（collectSkillEntries）方向相反——
+ * agents 源根级散 .md 检测收而 pi 不收（多提议）、子目录散 .md pi 收而检测不收
+ * （漏提议）；`.pi/skills` 源两侧同构。settings npm 源不扫（现无 npm 发布形态
+ * plan-exec skill，出现时补第五根）。
+ *
+ * 降级规格（检测失败最坏后果 = skill 选项空集，绝不允许炸消费方的核心交互闭环；
+ * pi 对坏 skill 也只产 diagnostics 不中断加载）：每根 existsSync 守卫 + 整根
+ * try/catch（EACCES 等任何 fs 错 → 跳过该根 + warn）；单 skill frontmatter 读/解析
+ * 失败 → 跳过该项 + warn；settings 读取/解析失败 → 视为无 overrides。
+ */
+
+/** 降级留痕（warn 级）：缺省走 pi-extension-logger，测试注入收集器 */
+type LogFn = (msg: string, detail?: object) => void;
+
+function defaultLog(msg: string, detail?: object): void {
+  logger.warn(msg, detail);
+}
+
+/** pi getHomeDir 同式（package-manager.js:78）：HOME 优先，缺省 os.homedir() */
+function defaultHomeDir(): string {
+  return process.env.HOME || os.homedir();
+}
+
+/** pi canonicalizePath 同式：realpath 失败回退原路径 */
+function canonicalizePath(p: string): string {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+function toPosixPath(p: string): string {
+  // 与 pi toPosixPath 同构：Windows 分隔符归一（POSIX 上恒等）
+  return sep === "\\" ? p.split("\\").join("/") : p;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** pi findGitRepoRoot 同式：.git 目录或 .git 文件（worktree）均算 root；无 git 推到文件系统根 */
+function findGitRepoRoot(startDir: string): string | null {
+  let dir = resolve(startDir);
+  while (true) {
+    if (fs.existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** pi collectAncestorAgentsSkillDirs 同式：startDir 起每级 `.agents/skills`，近→远，git root 级含 */
+function collectAncestorAgentsSkillDirs(startDir: string): string[] {
+  const skillDirs: string[] = [];
+  const resolvedStartDir = resolve(startDir);
+  const gitRepoRoot = findGitRepoRoot(resolvedStartDir);
+  let dir = resolvedStartDir;
+  while (true) {
+    skillDirs.push(join(dir, ".agents", "skills"));
+    if (gitRepoRoot && dir === gitRepoRoot) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return skillDirs;
+}
+
+/** BOM 剥离（pi stripBom 同构）：带 BOM 的 settings.json 直接 JSON.parse 会 throw */
+function stripBom(text: string): string {
+  return text.replace(/^\uFEFF/, "");
+}
+
+/**
+ * 读 settings.json 的 skills overrides（`+/-/!` pattern 数组）。
+ * 读取/解析失败 → [] + warn（pi tryLoadFromStorage 同折叠：错误不中断加载）。
+ * pi 旧形态 skills 为对象（customDirectories）——其条目无 `+/-/!` 前缀，对 override
+ * 匹配等价于无，此处按非数组折叠为 [] 即可。
+ */
+function readSkillsOverrides(settingsPath: string, log: LogFn): string[] {
+  try {
+    if (!fs.existsSync(settingsPath)) return [];
+    const parsed: unknown = JSON.parse(stripBom(fs.readFileSync(settingsPath, "utf-8")));
+    if (!isRecord(parsed)) return [];
+    const skills: unknown = parsed.skills;
+    if (!Array.isArray(skills)) return [];
+    return skills.filter((p): p is string => typeof p === "string");
+  } catch (error) {
+    log("exec-skills: settings parse failed (treated as no overrides)", {
+      path: settingsPath,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+}
+
+/**
+ * minimatch 子集 glob → RegExp：`**`（跨目录，段间匹配零段）/ `*`（段内任意）/ `?`
+ * （单字符，不跨 /）/ `[...]` 字符类；不支持 brace 展开等高级语法。已登记偏差：
+ * 极端 disable pattern（brace 等）可能与 pi 求值不一致——常用形态（裸名 / `x-*` /
+ * `dir/**`）语义一致。
+ */
+function globToRegExp(pattern: string): RegExp {
+  let source = "^";
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        while (pattern[i + 1] === "*") i++;
+        // 段间 `**/` 允许零段（minimatch globstar 语义），其余 `**` 跨目录任意
+        if (source.endsWith("/") && pattern[i + 1] === "/") {
+          source = `${source.slice(0, -1)}(?:.*/)?`;
+          i++;
+        } else {
+          source += ".*";
+        }
+      } else {
+        source += "[^/]*";
+      }
+    } else if (ch === "?") {
+      source += "[^/]";
+    } else if (ch === "[") {
+      const end = pattern.indexOf("]", i + 1);
+      if (end === -1) {
+        source += "\\[";
+      } else {
+        let cls = pattern.slice(i + 1, end);
+        if (cls.startsWith("!")) cls = `^${cls.slice(1)}`;
+        source += `[${cls}]`;
+        i = end;
+      }
+    } else {
+      source += ch.replace(/[\\^$.+(){}|]/g, "\\$&");
+    }
+  }
+  return new RegExp(`${source}$`);
+}
+
+/** pi normalizeExactPattern 同式：剥前导 `./`（+/- 精确匹配形态归一，只剥一次） */
+function normalizeExactPattern(pattern: string): string {
+  return toPosixPath(pattern.replace(/^\.\/|^\.\\/, ""));
+}
+
+/**
+ * pi matchesAnyPattern 同构（`!` 排除侧的 glob 匹配）：rel / 文件名 / 绝对路径，
+ * SKILL.md 再加父目录的 rel / 名 / 绝对路径三形态——`!dev-flow` 即靠父目录名命中。
+ */
+function matchesAnyGlobPattern(filePath: string, patterns: string[], baseDir: string): boolean {
+  if (patterns.length === 0) return false;
+  const regexes = patterns.map(globToRegExp);
+  const candidates = globMatchCandidates(filePath, baseDir);
+  return candidates.some((candidate) => regexes.some((re) => re.test(candidate)));
+}
+
+/** 匹配候选形态（glob 侧 6 形态 / 精确侧 4 形态的公共部分按需取用） */
+function globMatchCandidates(filePath: string, baseDir: string): string[] {
+  const rel = toPosixPath(relative(baseDir, filePath));
+  const name = basename(filePath);
+  const filePathPosix = toPosixPath(filePath);
+  const isSkillFile = name === "SKILL.md";
+  if (!isSkillFile) return [rel, name, filePathPosix];
+  const parentDir = dirname(filePath);
+  return [
+    rel,
+    name,
+    filePathPosix,
+    toPosixPath(relative(baseDir, parentDir)),
+    basename(parentDir),
+    toPosixPath(parentDir),
+  ];
+}
+
+/** pi matchesAnyExactPattern 同构（`+`/`-` 精确侧）：rel / 绝对路径 + SKILL.md 父目录两形态，无 glob */
+function matchesAnyExactPattern(filePath: string, patterns: string[], baseDir: string): boolean {
+  if (patterns.length === 0) return false;
+  const rel = toPosixPath(relative(baseDir, filePath));
+  const filePathPosix = toPosixPath(filePath);
+  const isSkillFile = basename(filePath) === "SKILL.md";
+  const parentDir = isSkillFile ? dirname(filePath) : undefined;
+  const parentRel = parentDir !== undefined ? toPosixPath(relative(baseDir, parentDir)) : undefined;
+  const parentDirPosix = parentDir !== undefined ? toPosixPath(parentDir) : undefined;
+  return patterns.some((pattern) => {
+    const normalized = normalizeExactPattern(pattern);
+    if (normalized === rel || normalized === filePathPosix) return true;
+    return (parentRel !== undefined && normalized === parentRel)
+      || (parentDirPosix !== undefined && normalized === parentDirPosix);
+  });
+}
+
+/** pi isEnabledByOverrides 同构：三级优先级 `-` > `+` > `!` > 默认启用（横切全部根） */
+export function isEnabledByOverrides(filePath: string, patterns: string[], baseDir: string): boolean {
+  const overrides = patterns.filter((p) => p.startsWith("!") || p.startsWith("+") || p.startsWith("-"));
+  const excludes = overrides.filter((p) => p.startsWith("!")).map((p) => p.slice(1));
+  const forceIncludes = overrides.filter((p) => p.startsWith("+")).map((p) => p.slice(1));
+  const forceExcludes = overrides.filter((p) => p.startsWith("-")).map((p) => p.slice(1));
+  let enabled = true;
+  if (excludes.length > 0 && matchesAnyGlobPattern(filePath, excludes, baseDir)) {
+    enabled = false;
+  }
+  if (forceIncludes.length > 0 && matchesAnyExactPattern(filePath, forceIncludes, baseDir)) {
+    enabled = true;
+  }
+  if (forceExcludes.length > 0 && matchesAnyExactPattern(filePath, forceExcludes, baseDir)) {
+    enabled = false;
+  }
+  return enabled;
+}
+
+/** plan-exec marker 的 frontmatter 键（skill 侧自愿 opt-in：SKILL.md 加一行 `plan-exec: true`） */
+const PLAN_EXEC_MARKER_FIELD = "plan-exec";
+
+/**
+ * 二次读 frontmatter 判 plan-exec marker（pi 的 Skill 对象不保留原始 frontmatter；
+ * pi 加载器对未知字段忽略不拒，marker 字段约定可行）。读/解析失败 → false + warn
+ * （降级：跳过该项）。严格 `=== true`：字符串 "true" 等 YAML 形态不误判。
+ */
+export function hasPlanExecMarker(skillFilePath: string, log: LogFn = defaultLog): boolean {
+  try {
+    const { frontmatter } = parseFrontmatter(fs.readFileSync(skillFilePath, "utf-8"));
+    return frontmatter[PLAN_EXEC_MARKER_FIELD] === true;
+  } catch (error) {
+    log("exec-skills: frontmatter read failed (skill skipped)", {
+      path: skillFilePath,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return false;
+  }
+}
+
+/** 检测产物：一个可提议为执行方式的 skill（name 与 pi prompt 列表一致，⑥） */
+export interface ExecSkill {
+  name: string;
+  description: string;
+  /** skill 入口文件路径（标准形态 = SKILL.md 路径，散 .md 形态 = 文件本身；steer 指引 read 该路径，两种形态统一无分支） */
+  skillEntryPath: string;
+}
+
+export interface DetectExecSkillsOptions {
+  /** 项目目录（`<CONFIG_DIR_NAME>/skills` 根 + 祖先链起点，目录名跟 pi CONFIG_DIR_NAME 导出）。生产调用传 ctx.cwd */
+  cwd: string;
+  /** 项目信任态（untrusted 跳过 `.pi/skills` 与祖先链两族，④）。生产调用传 ctx.isProjectTrusted() */
+  trusted: boolean;
+  /** pi agentDir（`<agentDir>/skills` 根 + 全局 settings 位置）。缺省 pi getAgentDir()（读 PI_CODING_AGENT_DIR）；测试注入 */
+  agentDir?: string;
+  /** 用户 home（`~/.agents/skills` 根）。缺省 `process.env.HOME || os.homedir()`（pi getHomeDir 同式）；测试注入 */
+  homeDir?: string;
+  /** 降级留痕（warn 级），缺省 pi-extension-logger */
+  log?: LogFn;
+}
+
+/** 检测的单根描述：目录 + overrides 求值 baseDir（pi 按根挂各自 baseDir）+ 该根适用的 overrides */
+interface SkillRoot {
+  dir: string;
+  baseDir: string;
+  overrides: string[];
+}
+
+/**
+ * 检测入口：枚举 pi 本体加载集的四根，返回带 plan-exec marker 的 skill 清单
+ * （root 序去重后）。现扫、无缓存（低频路径 + 技能热装可见性）。永不 throw（降级规格）。
+ */
+export function detectExecSkills(options: DetectExecSkillsOptions): ExecSkill[] {
+  const log: LogFn = options.log ?? defaultLog;
+  try {
+    return detectExecSkillsInternal(options, log);
+  } catch (error) {
+    log("exec-skills: detection failed (degraded to empty option set)", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+}
+
+/**
+ * trusted 门内两族根（④）：`.pi/skills` 根 + 祖先链；overrides 挂 project settings。
+ * 祖先链每根 baseDir = 各自的 `.agents` 目录；与 `~/.agents/skills`
+ * 同路径的项滤掉（pi :1979 同款——cwd 在 HOME 下时防与第四根重复）。
+ */
+function collectTrustedProjectRoots(cwd: string, homeDir: string, projectOverrides: string[]): SkillRoot[] {
+  const roots: SkillRoot[] = [];
+  roots.push({ dir: join(cwd, CONFIG_DIR_NAME, "skills"), baseDir: join(cwd, CONFIG_DIR_NAME), overrides: projectOverrides });
+  const userAgentsSkillsDir = join(homeDir, ".agents", "skills");
+  for (const dir of collectAncestorAgentsSkillDirs(cwd)) {
+    if (resolve(dir) === resolve(userAgentsSkillsDir)) continue;
+    roots.push({ dir, baseDir: dirname(dir), overrides: projectOverrides });
+  }
+  return roots;
+}
+
+/** 四根 root 序组装（pi 本体加载集序，见 detectExecSkills 头注）；overrides 按根挂载 */
+function collectSkillRoots(
+  options: DetectExecSkillsOptions,
+  cwd: string,
+  agentDir: string,
+  homeDir: string,
+  log: LogFn,
+): SkillRoot[] {
+  const userOverrides = readSkillsOverrides(join(agentDir, "settings.json"), log);
+  // project settings 仅 trusted 时参与（pi loadFromStorage 对 untrusted 的 project 恒 {}）
+  const projectOverrides = options.trusted
+    ? readSkillsOverrides(join(cwd, CONFIG_DIR_NAME, "settings.json"), log)
+    : [];
+  const roots: SkillRoot[] = options.trusted
+    ? collectTrustedProjectRoots(cwd, homeDir, projectOverrides)
+    : [];
+  roots.push({ dir: join(agentDir, "skills"), baseDir: agentDir, overrides: userOverrides });
+  roots.push({ dir: join(homeDir, ".agents", "skills"), baseDir: join(homeDir, ".agents"), overrides: userOverrides });
+  return roots;
+}
+
+/**
+ * 单根扫描：overrides 过滤（②）→ first-writer-wins 去重（⑤，seen 集跨根共享）→
+ * marker 过滤。根目录缺失 / 整根读失败 → 空集（降级规格，不中断其余根）。
+ */
+function scanSkillRoot(
+  root: SkillRoot,
+  seenNames: Set<string>,
+  seenRealPaths: Set<string>,
+  log: LogFn,
+): ExecSkill[] {
+  if (!fs.existsSync(root.dir)) return []; // 合法缺省（~/.agents/skills 不存在是常态主路径）
+  let skills: Skill[];
+  try {
+    skills = loadSkillsFromDir({ dir: root.dir, source: "detect" }).skills;
+  } catch (error) {
+    log("exec-skills: root scan failed (root skipped)", {
+      dir: root.dir,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+  const found: ExecSkill[] = [];
+  for (const skill of skills) {
+    // ② 用户显式 disable 的 skill 不提议（意图对齐）
+    if (!isEnabledByOverrides(skill.filePath, root.overrides, root.baseDir)) continue;
+    // ⑤ first-writer-wins（含非 marker skill 占名——pi 的 collision 语义以加载集为准，
+    // 后根同名不因 marker 缺席而让位）
+    const realPath = canonicalizePath(skill.filePath);
+    if (seenRealPaths.has(realPath) || seenNames.has(skill.name)) continue;
+    seenRealPaths.add(realPath);
+    seenNames.add(skill.name);
+    if (!hasPlanExecMarker(skill.filePath, log)) continue;
+    found.push({
+      name: skill.name,
+      description: skill.description,
+      // 入口文件路径两种形态统一：标准形态 filePath 即 SKILL.md 路径、散 .md 形态即
+      // 文件本身——接收端（steer 文案）直接 read 该值，不再拼 SKILL.md（散 .md 形态
+      // 拼接会得到不存在的 `<skills根>/SKILL.md` 悬空指引）
+      skillEntryPath: skill.filePath,
+    });
+  }
+  return found;
+}
+
+function detectExecSkillsInternal(options: DetectExecSkillsOptions, log: LogFn): ExecSkill[] {
+  const cwd = resolve(options.cwd);
+  const agentDir = resolve(options.agentDir ?? getAgentDir());
+  const homeDir = resolve(options.homeDir ?? defaultHomeDir());
+
+  const roots = collectSkillRoots(options, cwd, agentDir, homeDir, log);
+
+  const seenNames = new Set<string>();
+  const seenRealPaths = new Set<string>();
+  const found: ExecSkill[] = [];
+  for (const root of roots) {
+    for (const skill of scanSkillRoot(root, seenNames, seenRealPaths, log)) {
+      found.push(skill);
+    }
+  }
+  return found;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @zhushanwen/pi-exec-skills 公共出口（ADR-0074 落地包）。
+ *
+ * 两段消费语义闭环：exec-skills = 发现（目录扫描，技能热装即时可见）；
+ * resolve-skills = 执行门禁（pi 注册表确认 pi 实际认得）。禁止各扩展自扫
+ * skill 目录或直用 pi 注册表快照形成第二实现。
+ */
+export { detectExecSkills, hasPlanExecMarker, isEnabledByOverrides } from "./exec-skills.js";
+export type { DetectExecSkillsOptions, ExecSkill } from "./exec-skills.js";
+export { normalizeSkillName, resolveSkills } from "./resolve-skills.js";
+export type { SkillRef, SkillResolution } from "./resolve-skills.js";

package/src/resolve-skills.ts

@@ -0,0 +1,65 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * 技能执行门禁共享能力（ADR-0074 落地包）：steer/注入前的「pi 实际认得」确认，
+ * 走 pi 注册表（pi.getCommands）。与同包 exec-skills 模块构成两段消费语义闭环——
+ * 扫描（发现，自研直读磁盘，技能热装即时可见）≠ 本模块（执行门禁，pi 注册表
+ * 是执行权威）；pi 不认得的技能只提示不注入。
+ *
+ * 门禁取注册表快照在此是有意选择：执行权在 pi 本体，快照滞后只造成「刚装的
+ * 技能本 turn 门禁拒绝」，重试即过——与「发现」侧的滞后不可接受（表单永远
+ * 看不到新技能）不同源。
+ */
+
+/** E1 技能解析结果：ok=false 时携带缺失项与可用清单（fail-fast 回复的材料） */
+export type SkillResolution =
+  | { ok: true; resolved: SkillRef[] }
+  | { ok: false; available: string[]; missing: string[] };
+
+/** 一个已确认可执行的技能引用：自然名 + 注册表回执的入口路径 */
+export interface SkillRef { // oe-exempt:20261001:framework:exec-skills 共享包公开 API 条目形状（resolveSkills 返回值条目，包 index 导出供外部 pi 用户消费）——库契约接口先立、单实现常态
+  name: string;
+  skillPath: string;
+}
+
+/**
+ * 技能名归一：剥掉 pi 命令命名空间前导 `skill:` 前缀，得到自然技能名。
+ * pi.getCommands() 枚举 skill 类命令时 name 带 `skill:` 前缀（如 `skill:tech-design`），
+ * 这是 pi 的实现细节，不得泄漏到输入面——slash `--skills` 与消费方工具的 skills 参数
+ * 都用自然技能名。枚举侧与输入侧双向剥前缀后比对，兼容两种形态。
+ */
+export function normalizeSkillName(name: string): string {
+  return name.startsWith("skill:") ? name.slice("skill:".length) : name;
+}
+
+/**
+ * 执行门禁：pi.getCommands() 过滤 source === "skill" 枚举比对。比对前双向剥
+ * `skill:` 前缀归一：resolved/missing 用归一后的短名；available 维持枚举原形态
+ * （错误信息里可直接复制为 pi 命令）。
+ *
+ * 空请求 = 同族 fail-fast（「--skills 给了但没给名字」）：返回 ok:false + 全量
+ * available + 空 missing——available 正是调用方报错文案的恢复动作输入（错误 →
+ * 可用清单 → 重试闭环），missing 空让报错器走「没有给技能名」分支。自 plan 包
+ * enter.ts 迁入（plan-mode-audit-remediation 批次 4②b）：该分支是 slash 空
+ * `--skills` 报错复用单源的活契约，非死防御；既有调用方先判非空才调的，行为不受影响。
+ */
+export function resolveSkills(pi: ExtensionAPI, requested: string[]): SkillResolution {
+  const skillCommands = pi.getCommands().filter((c) => c.source === "skill");
+  const byShortName = new Map(skillCommands.map((c) => [normalizeSkillName(c.name), c.sourceInfo.path]));
+  const available = skillCommands.map((c) => c.name);
+  const resolved: SkillRef[] = [];
+  const missing: string[] = [];
+  for (const raw of requested) {
+    const name = normalizeSkillName(raw);
+    const skillPath = byShortName.get(name);
+    if (skillPath === undefined) {
+      missing.push(name);
+    } else {
+      resolved.push({ name, skillPath });
+    }
+  }
+  if (requested.length === 0) {
+    return { ok: false, available, missing: [] };
+  }
+  return missing.length > 0 ? { ok: false, available, missing } : { ok: true, resolved };
+}