@heihei0299/matt-skills 3.0.30 → 3.1.0

package/bin/commands/check.js

@@ -0,0 +1,48 @@
+import { rm } from 'node:fs/promises';
+
+export async function runCheck(args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--all' || arg === '--json' || arg === '--help' || arg === '-h') continue;
+    if (arg === '--upstream' || arg === '--ref') {
+      if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+        process.stderr.write(`error: option '${arg}' for command 'check' requires a value\n`);
+        process.stderr.write(`Run 'matt-skills check --help' for usage.\n`);
+        process.exitCode = 2;
+        return;
+      }
+      i++;
+      continue;
+    }
+    if (arg.startsWith('--upstream=') || arg.startsWith('--ref=')) continue;
+    if (arg.startsWith('-')) {
+      process.stderr.write(`error: unknown option '${arg}' for command 'check'\n`);
+      process.stderr.write(`Run 'matt-skills check --help' for usage.\n`);
+      process.exitCode = 2;
+      return;
+    }
+    process.stderr.write(`error: unknown argument '${arg}' for command 'check'\n`);
+    process.stderr.write(`Run 'matt-skills check --help' for usage.\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const { compare, formatComparison } = await import('../../scripts/sync-upstream.js');
+  const json = args.includes('--json');
+  const onlyProgramming = !args.includes('--all');
+  const upstreamIdx = args.indexOf('--upstream');
+  const upstreamEq = args.find((x) => x.startsWith('--upstream='));
+  const upstreamUrl = upstreamIdx !== -1 ? args[upstreamIdx + 1] : (upstreamEq ? upstreamEq.slice('--upstream='.length) : undefined);
+  const refIdx = args.indexOf('--ref');
+  const refEq = args.find((x) => x.startsWith('--ref='));
+  const ref = refIdx !== -1 ? args[refIdx + 1] : (refEq ? refEq.slice('--ref='.length) : undefined);
+  const cmp = await compare({ upstreamUrl, ref, onlyProgramming });
+  if (json) {
+    process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result, onlyProgramming }, null, 2) + '\n');
+  } else {
+    process.stdout.write(formatComparison(cmp) + '\n');
+  }
+  await rm(cmp.dest, { recursive: true, force: true });
+  const hasDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length > 0;
+  if (hasDiff) process.exitCode = 1;
+}

package/bin/commands/init.js

@@ -0,0 +1,63 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { PROPRIETARY_SKILLS, isRepoLocalSkill } from '../skills/boundaries.js';
+import { listSkillNames, listSkills, SKILLS_DIR } from '../skills/discovery.js';
+import { pathExists } from '../project/filesystem.js';
+import { copyTemplate } from '../project/template.js';
+import { distributeProjectSkills, PROJECT_SKILLS_DIR } from '../project/skills.js';
+
+export function parseInitArgs(args) {
+  let dest;
+  let all = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--dest') {
+      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--dest' requires a value`);
+      dest = args[++i];
+    } else if (arg.startsWith('--dest=')) dest = arg.slice('--dest='.length);
+    else if (arg === '--all') all = true;
+    else if (arg === '--help' || arg === '-h') {}
+    else if (arg.startsWith('-')) throw new Error(`unknown option '${arg}' for command 'init'`);
+    else throw new Error(`unknown argument '${arg}' for command 'init'`);
+  }
+  return { dest, all };
+}
+
+export async function runInit(args) {
+  const { dest, all } = parseInitArgs(args);
+  const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
+  const marker = path.join(target, 'AGENTS.md');
+  const onlyProgramming = !all;
+  if (await pathExists(marker)) {
+    process.stdout.write('模板已存在（AGENTS.md），跳过\n');
+  } else {
+    await copyTemplate(target);
+    const selectedSkills = await listSkillNames({ onlyProgramming });
+    await distributeProjectSkills({ target, sourceDir: SKILLS_DIR, skillNames: selectedSkills });
+    process.stdout.write(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILLS_DIR}）\n`);
+  }
+  // 统计（区分编程 vs 全量）
+  const skillsDir = path.join(target, '.agents', 'skills');
+  let installed = 0;
+  try {
+    const entries = await readdir(skillsDir, { withFileTypes: true });
+    installed = entries.filter((e) => e.isDirectory() && !e.name.endsWith('.bak') && e.name !== '.git' && e.name !== 'skill-creator' && !isRepoLocalSkill(e.name)).length;
+  } catch {}
+  const allSkillsFull = await listSkills({ onlyProgramming: false });
+  const defaultSkills = await listSkills({ onlyProgramming: true });
+  const defaultCount = defaultSkills.length;
+  const upstreamFull = allSkillsFull.filter((s) => !PROPRIETARY_SKILLS.has(s.name)).length;
+  const upstreamDefault = defaultSkills.filter((s) => !PROPRIETARY_SKILLS.has(s.name)).length;
+  const displayTotal = onlyProgramming ? defaultCount : allSkillsFull.length;
+  const displayUpstream = onlyProgramming ? upstreamDefault : upstreamFull;
+  if (path.resolve(skillsDir) === path.resolve(SKILLS_DIR)) {
+    process.stdout.write(`技能：已装 ${installed}、跳过 0（可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}；默认 workflow ${defaultCount}，含上游 ${upstreamDefault}）\n`);
+  } else {
+    if (onlyProgramming) {
+      process.stdout.write(`技能：已装 ${installed}（默认 workflow ${displayTotal}，含上游 ${displayUpstream}；可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}）\n`);
+    } else {
+      process.stdout.write(`技能：已装 ${installed}（可分发 ${displayTotal}，含上游 ${displayUpstream}）\n`);
+    }
+  }
+  process.stdout.write(`目标路径：${target}\n`);
+}

package/bin/commands/install.js

@@ -0,0 +1,114 @@
+import path from 'node:path';
+import prompts from 'prompts';
+import { isDistributableSkill } from '../skills/boundaries.js';
+import { listSkillNames, listSkills, SKILLS_DIR } from '../skills/discovery.js';
+import { TOOLS, copySkills, toolDir } from '../project/skills.js';
+
+async function promptTools() {
+  const res = await prompts({
+    type: 'multiselect',
+    name: 'tools',
+    message: '选择要安装到的工具',
+    choices: TOOLS.map((t) => ({ title: t, value: t })),
+    instructions: '空格勾选，回车确认',
+  });
+  return Array.isArray(res?.tools) ? res.tools : [];
+}
+
+async function promptSkills(skills) {
+  const res = await prompts({
+    type: 'autocompleteMultiselect',
+    name: 'skills',
+    message: '选择要安装的技能',
+    choices: skills.map((s) => ({ title: s.name, value: s.name })),
+    instructions: '输入过滤，空格勾选，回车确认',
+    onRender() {
+      if (this.inputValue && this.filteredOptions.length === 0) {
+        this.filteredOptions = [{ title: '没有匹配的技能', value: '__no-match__', disabled: true }];
+        this.cursor = 0;
+      }
+    },
+  });
+  return Array.isArray(res?.skills) ? res.skills : [];
+}
+
+function parseInstallArgs(args) {
+  let dest;
+  let all = false;
+  let force = false;
+  let global = false;
+  let toolsArg;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--dest') {
+      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--dest' requires a value`);
+      dest = args[++i];
+    } else if (arg.startsWith('--dest=')) dest = arg.slice('--dest='.length);
+    else if (arg === '--all') all = true;
+    else if (arg === '--force') force = true;
+    else if (arg === '--tools') {
+      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--tools' requires a value`);
+      toolsArg = args[++i];
+    } else if (arg.startsWith('--tools=')) toolsArg = arg.slice('--tools='.length);
+    else if (arg === '--global') global = true;
+    else if (arg === '--project') global = false;
+    else if (arg === '--help' || arg === '-h') {}
+    else if (arg.startsWith('-')) throw new Error(`unknown option '${arg}' for command 'install'`);
+    else throw new Error(`unknown argument '${arg}' for command 'install'`);
+  }
+  const tools = toolsArg
+    ? toolsArg.split(',').map((t) => t.trim()).filter(Boolean)
+    : null;
+  return { dest, all, force, global, tools };
+}
+
+async function installCommand({ dest, all, force, tools, global }) {
+  const onlyProgramming = !all;
+  const skillNames = await listSkillNames({ onlyProgramming });
+  const skills = await listSkills({ onlyProgramming });
+  let targets;
+  if (dest) {
+    targets = [{ tool: null, dir: path.resolve(process.cwd(), dest) }];
+  } else {
+    const selectedTools = tools
+      ? tools.filter((t) => TOOLS.includes(t))
+      : await promptTools();
+    if (selectedTools.length === 0) {
+      process.stdout.write('未选择任何工具，未安装任何技能\n');
+      return;
+    }
+    targets = selectedTools.map((tool) => ({ tool, dir: toolDir(tool, global) }));
+    // 去重：保留对自定义 PROJECT_DIRS 映射的兼容。
+    const seen = new Map();
+    for (const t of targets) {
+      if (!seen.has(t.dir)) seen.set(t.dir, t);
+    }
+    targets = [...seen.values()];
+  }
+  const selected = all ? skillNames : await promptSkills(skills);
+  if (selected.length === 0) {
+    process.stdout.write('未选择任何技能，未安装任何技能\n');
+    return;
+  }
+  const knownDistributable = new Set(skillNames);
+  for (const name of selected) {
+    if (!isDistributableSkill(name, knownDistributable)) {
+      throw new Error(`${name} is repository-local or unavailable and cannot be distributed`);
+    }
+  }
+  for (const { tool, dir } of targets) {
+    const { installed, skipped } = await copySkills({
+      sourceDir: SKILLS_DIR,
+      targetDir: dir,
+      skillNames: selected,
+      force,
+    });
+    if (tool) process.stdout.write(`${tool}：已装 ${installed}、跳过 ${skipped}\n`);
+    else process.stdout.write(`已装 ${installed}、跳过 ${skipped}\n`);
+    process.stdout.write(`目标路径：${dir}\n`);
+  }
+}
+
+export async function runInstall(args) {
+  await installCommand(parseInstallArgs(args));
+}

package/bin/commands/list.js

@@ -0,0 +1,26 @@
+import { listSkills } from '../skills/discovery.js';
+
+export async function runList(args) {
+  for (const arg of args) {
+    if (arg === '--all' || arg === '--json' || arg === '--help' || arg === '-h') continue;
+    if (arg.startsWith('-')) {
+      process.stderr.write(`error: unknown option '${arg}' for command 'list'\n`);
+      process.stderr.write(`Run 'matt-skills list --help' for usage.\n`);
+      process.exitCode = 2;
+      return;
+    }
+    process.stderr.write(`error: unknown argument '${arg}' for command 'list'\n`);
+    process.stderr.write(`Run 'matt-skills list --help' for usage.\n`);
+    process.exitCode = 2;
+    return;
+  }
+  const onlyProgramming = !args.includes('--all');
+  const skills = await listSkills({ onlyProgramming });
+  if (args.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(skills, null, 2)}\n`);
+  } else {
+    for (const skill of skills) {
+      process.stdout.write(`${skill.name} — ${skill.description}\n`);
+    }
+  }
+}

package/bin/commands/sync.js

@@ -0,0 +1,96 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { REPO_LOCAL_SKILLS } from '../skills/boundaries.js';
+import { listSkillNames, SKILLS_DIR } from '../skills/discovery.js';
+import { copyDryRunInputs, compareDryRunTrees, formatTargetComparison, syncTemplate } from '../project/template.js';
+import { PROJECT_SKILLS_DIR, syncProjectSkills } from '../project/skills.js';
+
+export function parseSyncArgs(args) {
+  let dest;
+  let all = false;
+  let dryRun = false;
+  let json = false;
+  let refreshAgents = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--dest') {
+      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--dest' requires a value`);
+      dest = args[++i];
+    } else if (arg.startsWith('--dest=')) dest = arg.slice('--dest='.length);
+    else if (arg === '--all') all = true;
+    else if (arg === '--dry-run') dryRun = true;
+    else if (arg === '--json') json = true;
+    else if (arg === '--refresh-agents') refreshAgents = true;
+    else if (arg === '--help' || arg === '-h') {}
+    else if (arg === '--apply') {}
+    else if (arg.startsWith('-')) throw new Error(`unknown option '${arg}' for command 'sync'`);
+    else throw new Error(`unknown argument '${arg}' for command 'sync'`);
+  }
+  return { dest, all, dryRun, json, refreshAgents };
+}
+
+async function syncCommand({ dest, all, dryRun, json, refreshAgents, quiet = false }) {
+  const onlyProgramming = !all;
+  const output = (text) => {
+    if (!quiet) process.stdout.write(text);
+  };
+  if (!dryRun && json) throw new Error('--json 仅支持 sync --dry-run');
+  if (dryRun) {
+    const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
+    const stage = await mkdtemp(path.join(os.tmpdir(), 'matt-skills-sync-dry-run-'));
+    try {
+      await copyDryRunInputs(target, stage);
+      await syncCommand({ dest: stage, all, dryRun: false, json: false, refreshAgents, quiet: true });
+      const result = await compareDryRunTrees(target, stage);
+      const payload = { target, result, onlyProgramming, refreshAgents };
+      if (json) output(`${JSON.stringify(payload, null, 2)}\n`);
+      else output(`${formatTargetComparison(payload)}\n`);
+      const totalDiff = result.added.length + result.updated.length + result.removed.length;
+      if (totalDiff > 0) process.exitCode = 1;
+    } finally {
+      await rm(stage, { recursive: true, force: true });
+    }
+    return;
+  }
+
+  const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
+  const template = await syncTemplate({ target, refreshAgents });
+  if (template.initialized) {
+    output('未检测到现有项目（AGENTS.md 不存在），将执行全新初始化\n');
+    output(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILLS_DIR}）\n`);
+  } else {
+    output('同步：检测到现有项目，将增量更新\n');
+    if (template.agentsRefreshed && template.agentsRefreshMode === 'managed') {
+      output(`模板：已同步（AGENTS.md 受管区块已刷新、skills：${PROJECT_SKILLS_DIR}，项目自定义内容已保留）\n`);
+    } else if (template.agentsRefreshed) {
+      output(`模板：已同步（AGENTS.md 已刷新，旧文件备份为 AGENTS.md.bak、skills：${PROJECT_SKILLS_DIR}）\n`);
+    } else if (template.agentsManaged) {
+      output(`模板：已同步（AGENTS.md 受管区块已更新、skills：${PROJECT_SKILLS_DIR}，项目自定义内容已保留）\n`);
+    } else {
+      output(`模板：已同步（AGENTS.md 未受管、skills：${PROJECT_SKILLS_DIR}，已原样保留）\n`);
+    }
+  }
+  // --all 只扩大技能范围；同名覆盖、不存在新增，不删除目标中的额外技能。
+  const allSkills = await listSkillNames({ onlyProgramming });
+  const result = await syncProjectSkills({
+    target,
+    sourceDir: SKILLS_DIR,
+    skillNames: allSkills,
+    distributableSkillNames: (await listSkillNames({ onlyProgramming: false })).filter((name) => !REPO_LOCAL_SKILLS.has(name)),
+    repoLocalSkills: REPO_LOCAL_SKILLS,
+  });
+  if (result.cleanedLegacy.length) {
+    output(`迁移清理：${result.cleanedLegacy.join(', ')} 旧共享副本已移除\n`);
+  }
+  if (result.preservedRepoLocal.length) {
+    output(`迁移提示：${result.preservedRepoLocal.join(', ')} 已不再分发，现有副本已保留\n`);
+  }
+  const modeLabel = onlyProgramming ? '默认 workflow' : '全部可分发';
+  output(`技能：新增 ${result.installed}、更新 ${result.updated}（${modeLabel} ${allSkills.length}）\n`);
+  output(`目标路径：${target}\n`);
+}
+
+export async function runSync(args) {
+  await syncCommand(parseSyncArgs(args));
+}

package/bin/project/agents.js

@@ -0,0 +1,29 @@
+import { readFile, writeFile } from 'node:fs/promises';
+
+export const AGENTS_MANAGED_START = '<!-- matt-skills:managed:start -->';
+export const AGENTS_MANAGED_END = '<!-- matt-skills:managed:end -->';
+
+export function findManagedBlock(content) {
+  const start = content.indexOf(AGENTS_MANAGED_START);
+  if (start < 0 || content.indexOf(AGENTS_MANAGED_START, start + AGENTS_MANAGED_START.length) >= 0) return null;
+  const endStart = content.indexOf(AGENTS_MANAGED_END, start + AGENTS_MANAGED_START.length);
+  if (endStart < 0 || content.indexOf(AGENTS_MANAGED_END, endStart + AGENTS_MANAGED_END.length) >= 0) return null;
+  return { start, end: endStart + AGENTS_MANAGED_END.length };
+}
+
+export function mergeManagedAgents(current, template) {
+  const currentBlock = findManagedBlock(current);
+  const templateBlock = findManagedBlock(template);
+  if (!currentBlock || !templateBlock) return null;
+  const managed = template.slice(templateBlock.start, templateBlock.end);
+  return current.slice(0, currentBlock.start) + managed + current.slice(currentBlock.end);
+}
+
+export async function syncManagedAgents(targetFile, templateFile) {
+  const current = await readFile(targetFile, 'utf8');
+  const template = await readFile(templateFile, 'utf8');
+  const merged = mergeManagedAgents(current, template);
+  if (merged === null) return false;
+  if (merged !== current) await writeFile(targetFile, merged);
+  return true;
+}

package/bin/project/filesystem.js

@@ -0,0 +1,60 @@
+import { readdir, readFile, lstat, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+export async function pathExists(targetPath) {
+  try {
+    await stat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isSafeRealPath(targetPath) {
+  const absolute = path.resolve(targetPath);
+  const root = path.parse(absolute).root;
+  let current = root;
+  for (const segment of path.relative(root, absolute).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      if ((await lstat(current)).isSymbolicLink()) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+function sameMetadata(left, right) {
+  return (left.mode & 0o7777) === (right.mode & 0o7777)
+    && left.uid === right.uid
+    && left.gid === right.gid;
+}
+
+export async function sameTree(left, right) {
+  try {
+    const [leftInfo, rightInfo] = await Promise.all([lstat(left), lstat(right)]);
+    if (leftInfo.isSymbolicLink() || rightInfo.isSymbolicLink()) return false;
+    if (leftInfo.isDirectory() !== rightInfo.isDirectory()) return false;
+    if (leftInfo.isDirectory()) {
+      const [leftEntries, rightEntries] = await Promise.all([
+        readdir(left, { withFileTypes: true }),
+        readdir(right, { withFileTypes: true }),
+      ]);
+      if (!sameMetadata(leftInfo, rightInfo) || leftEntries.length !== rightEntries.length) return false;
+      const rightNames = new Set(rightEntries.map((entry) => entry.name));
+      for (const entry of leftEntries) {
+        if (!rightNames.has(entry.name) || !await sameTree(path.join(left, entry.name), path.join(right, entry.name))) {
+          return false;
+        }
+      }
+      return true;
+    }
+    if (leftInfo.isFile() && rightInfo.isFile()) {
+      return (await readFile(left)).equals(await readFile(right)) && sameMetadata(leftInfo, rightInfo);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}

package/bin/project/skills.js

@@ -0,0 +1,144 @@
+import { cp, lstat, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isSafeRealPath, pathExists, sameTree } from './filesystem.js';
+
+export const TOOLS = ['codex', 'pi', 'opencode', 'claude'];
+
+export const PROJECT_SKILLS_DIR = '.agents/skills';
+
+export const PROJECT_DIRS = {
+  codex: PROJECT_SKILLS_DIR,
+  pi: PROJECT_SKILLS_DIR,
+  opencode: PROJECT_SKILLS_DIR,
+  claude: PROJECT_SKILLS_DIR,
+};
+
+export const LEGACY_PROJECT_SKILL_DIRS = ['.pi/skills', '.opencode/skills', '.claude/skills'];
+
+const GLOBAL_DIRS = {
+  codex: '.codex/skills',
+  pi: '.pi/agent/skills',
+  opencode: '.config/opencode/skills',
+  claude: '.claude/skills',
+};
+
+export function projectSkillTargets(target) {
+  const targets = new Map();
+  for (const tool of TOOLS) {
+    const dir = path.resolve(target, PROJECT_DIRS[tool]);
+    if (!targets.has(dir)) targets.set(dir, { tool, dir });
+  }
+  return [...targets.values()];
+}
+
+export function toolDir(tool, global) {
+  if (global) return path.join(os.homedir(), GLOBAL_DIRS[tool]);
+  return path.resolve(process.cwd(), PROJECT_DIRS[tool]);
+}
+
+export async function copySkills({ sourceDir, targetDir, skillNames, force = true }) {
+  let installed = 0;
+  let skipped = 0;
+  for (const name of skillNames) {
+    const source = path.join(sourceDir, name);
+    const destination = path.join(targetDir, name);
+    if (path.resolve(source) === path.resolve(destination)) continue;
+    if (!force && await pathExists(destination)) {
+      skipped++;
+      continue;
+    }
+    await cp(source, destination, { recursive: true, force: true });
+    installed++;
+  }
+  return { installed, skipped };
+}
+
+export async function distributeProjectSkills({ target, sourceDir, skillNames }) {
+  for (const { dir } of projectSkillTargets(target)) {
+    await mkdir(dir, { recursive: true });
+    await copySkills({ sourceDir, targetDir: dir, skillNames });
+  }
+}
+
+export async function syncProjectSkills({ target, sourceDir, skillNames, distributableSkillNames, repoLocalSkills }) {
+  const skillTargets = projectSkillTargets(target);
+  const skillsDir = path.resolve(target, PROJECT_DIRS.codex);
+  const legacyLocations = LEGACY_PROJECT_SKILL_DIRS.map((relative) => ({
+    dir: path.resolve(target, relative),
+    label: relative,
+    isWorkspaceSource: false,
+  }));
+  const preservedRepoLocal = [];
+  const preserveLocations = [
+    ...skillTargets.map(({ tool, dir }) => ({
+      dir,
+      label: PROJECT_DIRS[tool],
+      isWorkspaceSource: path.resolve(dir) === path.resolve(sourceDir),
+    })),
+    ...legacyLocations,
+  ];
+  for (const { dir } of skillTargets) await mkdir(dir, { recursive: true });
+  for (const name of repoLocalSkills) {
+    for (const location of preserveLocations) {
+      if (!location.isWorkspaceSource && await pathExists(path.join(location.dir, name))) {
+        preservedRepoLocal.push(`${location.label}/${name}`);
+      }
+    }
+  }
+  let installed = 0;
+  let updated = 0;
+  for (const { dir } of skillTargets) {
+    for (const name of skillNames) {
+      const source = path.join(sourceDir, name);
+      const destination = path.join(dir, name);
+      if (path.resolve(source) === path.resolve(destination)) {
+        if (path.resolve(dir) === skillsDir) updated++;
+        continue;
+      }
+      const exists = await pathExists(destination);
+      if (exists) {
+        await rm(destination, { recursive: true, force: true });
+        await cp(source, destination, { recursive: true, force: true });
+        if (path.resolve(dir) === skillsDir) updated++;
+      } else {
+        await cp(source, destination, { recursive: true, force: true });
+        if (path.resolve(dir) === skillsDir) installed++;
+      }
+    }
+  }
+  const cleanedLegacy = [];
+  for (const location of legacyLocations) {
+    let entries;
+    try {
+      if (!await isSafeRealPath(location.dir)) continue;
+      const locationInfo = await lstat(location.dir);
+      if (!locationInfo.isDirectory()) continue;
+      entries = await readdir(location.dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === '.git' || entry.name.endsWith('.bak')) continue;
+      if (!distributableSkillNames.includes(entry.name)) continue;
+      const source = path.join(sourceDir, entry.name);
+      const destination = path.join(location.dir, entry.name);
+      try {
+        if (await sameTree(source, destination)) {
+          await rm(destination, { recursive: true, force: true });
+          cleanedLegacy.push(`${location.label}/${entry.name}`);
+        }
+      } catch {}
+    }
+  }
+  try {
+    const piSettings = path.join(target, '.pi/settings.json');
+    if (await pathExists(piSettings)) {
+      const txt = await readFile(piSettings, 'utf8');
+      if (txt.includes('.opencode/skills') || txt.includes('../.opencode')) {
+        await writeFile(piSettings, '{}\n');
+      }
+    }
+  } catch {}
+  return { installed, updated, cleanedLegacy, preservedRepoLocal };
+}