specpipe 1.0.1 → 1.0.3

package/src/lib/agent-install.js

@@ -2,8 +2,8 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile, unlink, chmod, rmdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { log } from './logger.js';
-import { getTemplateDir, COMPONENTS } from './installer.js';
-import { emitSkillFile, emitRules, emitHooks, AGENTS, GUARDS_BEGIN, GUARDS_END } from './agents.js';
+import { getTemplateDir, COMPONENTS, skillAllowed } from './installer.js';
+import { emitSkillFile, emitRules, emitHooks, AGENTS, RULES_BEGIN, RULES_END } from './agents.js';
 
 /**
  * Emit one canonical skill file for a target agent and write it to targetDir.
@@ -38,10 +38,16 @@ export async function installSkillForAgent(agentId, canonicalRel, targetDir, { f
  * Install the full skill set for one agent into targetDir.
  * @returns {{ agent: string, copied: number, skipped: number, identical: number, paths: string[] }}
  */
-export async function installAgentSkills(agentId, targetDir, { force = false } = {}) {
+export async function installAgentSkills(agentId, targetDir, { force = false, skills = null } = {}) {
   let copied = 0, skipped = 0, identical = 0;
   const paths = [];
+  // Hermes (and any perProjectSkills:false agent) reads skills only from its global dir,
+  // never the project — emitting per-project skill files here would be dead. Skip them.
+  if (AGENTS[agentId]?.perProjectSkills === false) {
+    return { agent: agentId, label: AGENTS[agentId].label, copied, skipped, identical, paths };
+  }
   for (const relPath of COMPONENTS.skills) {
+    if (!skillAllowed(relPath, skills)) continue;
     const { result, path } = await installSkillForAgent(agentId, relPath, targetDir, { force });
     if (result === 'copied') copied++;
     else if (result === 'identical') identical++;
@@ -51,31 +57,32 @@ export async function installAgentSkills(agentId, targetDir, { force = false } =
   return { agent: agentId, label: AGENTS[agentId].label, copied, skipped, identical, paths };
 }
 
-const GUARDS_TEMPLATE_REL = 'rules/specpipe-guards.md';
+const RULES_TEMPLATE_REL = 'rules/specpipe-rules.md';
 
-function guardsSectionRegex() {
+function rulesSectionRegex() {
   const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  return new RegExp(esc(GUARDS_BEGIN) + '[\\s\\S]*?' + esc(GUARDS_END) + '\\n?', '');
+  return new RegExp(esc(RULES_BEGIN) + '[\\s\\S]*?' + esc(RULES_END) + '\\n?', '');
 }
 
-/** Merge (or replace) the specpipe guards section in a shared AGENTS.md. */
-export async function mergeAgentsMdGuards(targetDir, section) {
-  const p = join(targetDir, 'AGENTS.md');
+/** Merge (or replace) the specpipe rules section in a shared file (CLAUDE.md / AGENTS.md). */
+export async function mergeRulesSection(targetDir, fileRel, section) {
+  const p = join(targetDir, fileRel);
   let existing = '';
   try { existing = await readFile(p, 'utf-8'); } catch { /* new file */ }
-  const re = guardsSectionRegex();
+  const re = rulesSectionRegex();
   existing = re.test(existing)
     ? existing.replace(re, section)
     : (existing.trim() ? existing.trimEnd() + '\n\n' : '') + section;
+  await mkdir(dirname(p), { recursive: true });
   await writeFile(p, existing);
 }
 
-/** Remove the specpipe guards section from AGENTS.md (deletes file if now empty). */
-export async function stripAgentsMdGuards(targetDir) {
-  const p = join(targetDir, 'AGENTS.md');
+/** Remove the specpipe rules section from a shared file (deletes it if now empty). */
+export async function stripRulesSection(targetDir, fileRel) {
+  const p = join(targetDir, fileRel);
   let existing;
   try { existing = await readFile(p, 'utf-8'); } catch { return false; }
-  const stripped = existing.replace(guardsSectionRegex(), '').trim();
+  const stripped = existing.replace(rulesSectionRegex(), '').trim();
   if (stripped === existing.trim()) return false;
   if (stripped) await writeFile(p, stripped + '\n');
   else await unlink(p);
@@ -83,19 +90,19 @@ export async function stripAgentsMdGuards(targetDir) {
 }
 
 /**
- * Install an agent's guardrails: an owned rules file (Cursor/Antigravity/
- * OpenClaw/Hermes) or a merged section in a shared AGENTS.md (Codex).
- * Claude returns null — it uses native hooks instead.
+ * Install an agent's guardrails: a merged section in a shared file (Claude →
+ * .claude/CLAUDE.md, Codex → AGENTS.md) or an owned rules file (Cursor/
+ * Antigravity/OpenClaw/Hermes). Returns null only if the agent has no rules entry.
  */
 export async function installAgentRules(agentId, targetDir, { force = false } = {}) {
-  const body = await readFile(join(getTemplateDir(), GUARDS_TEMPLATE_REL), 'utf-8');
+  const body = await readFile(join(getTemplateDir(), RULES_TEMPLATE_REL), 'utf-8');
   const r = emitRules(agentId, body);
   if (!r) return null;
 
-  if (r.mode === 'agents-md') {
-    await mergeAgentsMdGuards(targetDir, r.content);
+  if (r.mode === 'merge') {
+    await mergeRulesSection(targetDir, r.path, r.content);
     log.copy(`${r.path} (specpipe operating-rules section)`);
-    return { mode: 'agents-md', path: r.path };
+    return { mode: 'merge', path: r.path };
   }
 
   const dst = join(targetDir, r.path);
@@ -117,12 +124,13 @@ export async function installAgentRules(agentId, targetDir, { force = false } =
 
 /**
  * Install an agent's ENFORCED (blocking) hooks: the guard scripts + the agent's
- * hook config file. Codex/Cursor only (verified payloads). Returns null otherwise.
+ * hook config file. Agents with a verified hook config (Claude/Codex/Cursor/
+ * Antigravity); returns null for agents without one.
  * The hook config is specpipe-owned; if a different one already exists, we skip
  * unless --force (don't clobber a user's hooks).
  */
-export async function installAgentHooks(agentId, targetDir, { force = false } = {}) {
-  const h = emitHooks(agentId);
+export async function installAgentHooks(agentId, targetDir, { force = false, hooks = null } = {}) {
+  const h = emitHooks(agentId, hooks);
   if (!h) return null;
 
   for (const { src, dst } of h.scripts) {
@@ -151,11 +159,16 @@ export async function installAgentHooks(agentId, targetDir, { force = false } =
   return { configPath: h.configPath };
 }
 
-/** Remove an agent's enforced-hook scripts + config (+ empty hooks dir). */
+/** Remove an agent's enforced-hook scripts + config (+ empty hooks/agent dirs). */
 export async function removeAgentHooks(agentId, targetDir) {
   const h = emitHooks(agentId);
   if (!h) return;
   for (const { dst } of h.scripts) { try { await unlink(join(targetDir, dst)); } catch { /* */ } }
   try { await unlink(join(targetDir, h.configPath)); } catch { /* */ }
   try { await rmdir(join(targetDir, h.hooksDir)); } catch { /* not empty / missing */ }
+  // Tidy the agent's container dir too (e.g. .codex/, .agents/) — its only specpipe
+  // content was the hook config + hooks/. rmdir is a no-op when the dir still holds
+  // other content (.claude/CLAUDE.md, .cursor/rules/, .agents/skills/ for a kept agent).
+  const agentDir = dirname(h.configPath);
+  if (agentDir && agentDir !== '.') { try { await rmdir(join(targetDir, agentDir)); } catch { /* not empty / missing */ } }
 }

package/src/lib/agents.js

@@ -91,7 +91,8 @@ export const AGENTS = {
     label: 'Claude Code',
     // Verified: code.claude.com/docs/en/skills
     skillTarget: (name, inner) => `.claude/skills/${name}/${inner}`,
-    globalRoot: '.claude/skills',
+    // Global (user-level) skills dir, relative to home. Verified: ~/.claude/skills/.
+    globalSkillRoot: '.claude/skills',
     skillFile: 'SKILL.md',
     hooks: 'native',
     capabilities: 'full',
@@ -104,9 +105,12 @@ export const AGENTS = {
     label: 'Antigravity',
     // Verified: official Google Codelab — .agents/skills/<name>/SKILL.md
     skillTarget: (name, inner) => `.agents/skills/${name}/${inner}`,
-    globalRoot: '.agents/skills',
+    // Global differs from the project path: Antigravity CLI reads ~/.gemini/antigravity-cli/skills/
+    // (the IDE uses ~/.gemini/config/skills/ and also reads ~/.agents/skills/). Verified: Google
+    // Antigravity codelab. We target the CLI's global dir.
+    globalSkillRoot: '.gemini/antigravity-cli/skills',
     skillFile: 'SKILL.md',
-    hooks: 'rules', // guards emitted to .agent/rules/ (plain markdown)
+    hooks: 'rules', // guards emitted to .agents/rules/ (plain markdown)
     capabilities: 'router-no-hooks',
     emitFrontmatter: fmNameDesc,
   },
@@ -114,7 +118,9 @@ export const AGENTS = {
     label: 'OpenClaw',
     // Verified: github.com/openclaw/openclaw  skills/<name>/SKILL.md
     skillTarget: (name, inner) => `skills/${name}/${inner}`,
-    globalRoot: 'skills',
+    // Verified (docs.openclaw.ai): global skills live in ~/.openclaw/skills/ (the `--global`
+    // target; OpenClaw also reads ~/.agents/skills/).
+    globalSkillRoot: '.openclaw/skills',
     skillFile: 'SKILL.md',
     hooks: 'none',
     capabilities: 'router-no-hooks',
@@ -122,9 +128,14 @@ export const AGENTS = {
   },
   hermes: {
     label: 'Hermes-Agent',
-    // Verified: github.com/NousResearch/hermes-agent  optional-skills/<cat>/<name>/SKILL.md
-    skillTarget: (name, inner) => `optional-skills/specpipe/${name}/${inner}`,
-    globalRoot: 'optional-skills/specpipe',
+    // Hermes discovers skills ONLY from ~/.hermes/skills/ ("the primary directory and source
+    // of truth") + explicitly-configured external_dirs — it does NOT scan the project/workspace.
+    // So per-project skill files are dead (never read); Hermes is global-only for skills. The
+    // skillTarget is still used to shape the GLOBAL emission (globalSkillRoot + name + inner).
+    // Source: hermes-agent.nousresearch.com/docs/user-guide/features/skills
+    skillTarget: (name, inner) => `${name}/${inner}`,
+    perProjectSkills: false,
+    globalSkillRoot: '.hermes/skills',
     skillFile: 'SKILL.md',
     hooks: 'none',
     capabilities: 'router-no-hooks',
@@ -136,7 +147,10 @@ export const AGENTS = {
     // Skills live in the vendor-neutral `.agents/skills/` (NOT `.codex/skills/`, which
     // is a known non-working path — openai/codex#15136). Custom-prompts are deprecated.
     skillTarget: (name, inner) => `.agents/skills/${name}/${inner}`,
-    globalRoot: '.agents/skills',
+    // Global differs from the project path: Codex reads user skills from ~/.codex/skills/
+    // (ships system skills in ~/.codex/skills/.system), NOT ~/.agents/skills/. Verified:
+    // developers.openai.com/codex/skills.
+    globalSkillRoot: '.codex/skills',
     skillFile: 'SKILL.md',
     hooks: 'agents-md', // guards fold into AGENTS.md (plain markdown, no frontmatter)
     capabilities: 'router-no-hooks',
@@ -149,7 +163,10 @@ export const AGENTS = {
     // Skills are on-demand (/skill, @skill) — the correct home, not always-on .mdc rules.
     // Guards stay an always-on .cursor/rules/*.mdc (see RULES.cursor).
     skillTarget: (name, inner) => `.cursor/skills/${name}/${inner}`,
-    globalRoot: '.cursor/skills',
+    // Cursor reads a user-level skills dir at ~/.cursor/skills/ (verified: cursor.com/docs/skills
+    // — it loads .cursor/skills, .agents/skills, ~/.cursor/skills, ~/.agents/skills, plus
+    // .claude/.codex for compat). So `--global` installs Cursor's own global skills here.
+    globalSkillRoot: '.cursor/skills',
     skillFile: 'SKILL.md',
     hooks: 'rules', // advisory now; Cursor DOES support blocking hooks (.cursor/hooks.json) — roadmapped
     capabilities: 'router-no-hooks',
@@ -205,6 +222,26 @@ export function emitSkillFile(agentId, canonicalRel, content) {
   return { path, content: compose(agent.emitFrontmatter(parsed, skill), body) };
 }
 
+/**
+ * Emit one skill file for an agent's GLOBAL (user-level) install. Same per-agent
+ * content transformation as emitSkillFile, but the returned path is rooted at the
+ * agent's home-relative globalSkillRoot — which differs from the project skillTarget
+ * for Codex (~/.codex/skills), Antigravity (~/.gemini/antigravity-cli/skills), etc.
+ * Returns null when the agent has no native global skills dir (Cursor) or the input
+ * isn't a skill file.
+ * @returns {{ path: string, content: string } | null} path is relative to the user's home dir
+ */
+export function emitSkillFileGlobal(agentId, canonicalRel, content) {
+  const agent = AGENTS[agentId];
+  if (!agent) throw new Error(`Unknown agent: ${agentId}`);
+  if (!agent.globalSkillRoot) return null;
+  const parts = parseSkillPath(canonicalRel);
+  if (!parts) return null;
+  const emitted = emitSkillFile(agentId, canonicalRel, content);
+  if (!emitted) return null;
+  return { path: `${agent.globalSkillRoot}/${parts.skill}/${parts.inner}`, content: emitted.content };
+}
+
 /** Tools a canonical skill declares (from its `allowed-tools` frontmatter). */
 function toolsOf(parsed) {
   const block = getKeyBlock(parsed, 'allowed-tools');
@@ -251,7 +288,12 @@ function adaptBody(agentId, body, tools) {
   let out = rewriteAsk(body);
 
   if (has('Agent') || has('Task')) {
-    out = `${out.replace(/\s*$/, '')}\n\n---\n\n## Running on ${AGENTS[agentId].label}\n\n` +
+    // Header is agent-NEUTRAL on purpose: codex and antigravity share the same
+    // emit path (.agents/skills/<name>/), so the caveat must be byte-identical
+    // between them or computeDesired's Map sees divergent content and a clean
+    // install false-flags the file as "customized". The caveat text is already
+    // runtime-agnostic, so a fixed heading loses nothing.
+    out = `${out.replace(/\s*$/, '')}\n\n---\n\n## Running outside Claude Code\n\n` +
       '- **Subagents:** parts of this skill describe Claude subagent orchestration ' +
       '(parallel waves, worktrees, auto-mode dispatch). If your runtime has no ' +
       'subagents, do that work yourself — one item at a time, sequentially, in this ' +
@@ -275,6 +317,6 @@ export function emitFile(agentId, templateRel, content) {
 // Guardrails (advisory rules) + enforced (blocking) hooks live in agent-guards.js;
 // re-exported here so callers keep importing them from agents.js.
 export {
-  GUARDS_BEGIN, GUARDS_END, HOOKS_SRC_DIR,
+  RULES_BEGIN, RULES_END, HOOKS_SRC_DIR,
   agentRulesMode, emitRules, agentHasHooks, emitHooks,
 } from './agent-guards.js';

package/src/lib/claude-global.js

@@ -4,14 +4,12 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { log } from './logger.js';
 import { getTemplateDir } from './installer.js';
+import { emitSkillFileGlobal } from './agents.js';
+import { buildHookConfig } from './hooks.js';
+import { hashContent } from './hasher.js';
 
-// Claude's global install (~/.claude/skills, ~/.claude/hooks, ~/.claude/settings.json).
-// Claude-only: it's Claude Code's own enforcement engine; other agents have no equivalent.
-
-/** Global skills directory: ~/.claude/skills/ */
-export function getGlobalSkillsDir() {
-  return join(homedir(), '.claude', 'skills');
-}
+// Global install. Skills install per-agent via installSkillGlobalForAgent (below);
+// hooks + settings stay Claude-only (Claude Code's native enforcement engine).
 
 /** Global hooks directory: ~/.claude/hooks/ */
 export function getGlobalHooksDir() {
@@ -19,14 +17,14 @@ export function getGlobalHooksDir() {
 }
 
 /**
- * Copy a hook to the global ~/.claude/hooks/ directory.
- * Strips the '.claude/hooks/' prefix so path-guard.sh lands at ~/.claude/hooks/path-guard.sh.
+ * Copy one guard script (kit-relative src, e.g. 'hooks/specpipe-shell-guard.sh') into
+ * the global ~/.claude/hooks/ dir. `key` is the home-relative manifest key.
  * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string }}
  */
-export async function installHookGlobal(hookRelPath, globalHooksDir, { force = false, globalFiles = {} } = {}) {
-  const stripped = hookRelPath.replace(/^\.claude\/hooks\//, '');
-  const src = join(getTemplateDir(), hookRelPath);
-  const dst = join(globalHooksDir, stripped);
+export async function installHookGlobal(srcRel, globalHooksDir, { force = false, globalFiles = {}, key } = {}) {
+  const base = srcRel.split('/').pop();
+  const src = join(getTemplateDir(), srcRel);
+  const dst = join(globalHooksDir, base);
 
   const { hashFile } = await import('./hasher.js');
   const srcHash = await hashFile(src);
@@ -35,14 +33,15 @@ export async function installHookGlobal(hookRelPath, globalHooksDir, { force = f
     try {
       const dstHash = await hashFile(dst);
       if (srcHash === dstHash) {
-        log.same(`~/.claude/hooks/${stripped} (identical)`);
+        log.same(`~/.claude/hooks/${base} (identical)`);
         return { result: 'identical', kitHash: srcHash };
       }
-      const savedKitHash = globalFiles[hookRelPath]?.kitHash;
-      if (savedKitHash && dstHash === savedKitHash) {
-        // fall through to copy
-      } else {
-        log.skip(`~/.claude/hooks/${stripped} (customized — use --force to overwrite)`);
+      // Overwrite only when the on-disk file is one WE wrote (matches the kit hash
+      // recorded in the manifest) — i.e. a stale specpipe version, safe to update.
+      // Otherwise the user changed it (or we never tracked it) → preserve.
+      const savedKitHash = globalFiles[key]?.kitHash;
+      if (!(savedKitHash && dstHash === savedKitHash)) {
+        log.skip(`~/.claude/hooks/${base} (customized — use --force to overwrite)`);
         return { result: 'skipped', kitHash: srcHash };
       }
     } catch { /* hash failed */ }
@@ -51,43 +50,15 @@ export async function installHookGlobal(hookRelPath, globalHooksDir, { force = f
   await mkdir(dirname(dst), { recursive: true });
   await fsCopyFile(src, dst);
   await chmod(dst, 0o755);
-  log.copy(`~/.claude/hooks/${stripped}`);
+  log.copy(`~/.claude/hooks/${base}`);
   return { result: 'copied', kitHash: srcHash };
 }
 
-/** Build hook entries for ~/.claude/settings.json pointing to globalHooksDir. */
-function buildGlobalHookEntries(globalHooksDir) {
-  // Normalize to forward slashes — bash on all platforms (WSL, Git Bash, macOS, Linux)
-  // requires forward slashes even when the host OS is Windows.
+/** Claude settings.json hook entries pointing to the absolute global hooks dir. */
+function buildGlobalHookEntries(globalHooksDir, hooksSet) {
+  // Forward slashes — bash needs them on every host (WSL, Git Bash, macOS, Linux).
   const dir = globalHooksDir.replace(/\\/g, '/');
-  const h = (file) => `"${dir}/${file}"`;
-  return {
-    PreToolUse: [
-      { matcher: 'Bash', hooks: [
-        { type: 'command', command: `bash ${h('path-guard.sh')}` },
-        { type: 'command', command: `bash ${h('sensitive-guard.sh')}` },
-      ]},
-      { matcher: 'Read|Write|Edit|MultiEdit|Grep', hooks: [
-        { type: 'command', command: `bash ${h('sensitive-guard.sh')}` },
-      ]},
-      { matcher: 'Edit|MultiEdit', hooks: [
-        { type: 'command', command: `node ${h('comment-guard.js')}` },
-      ]},
-      { matcher: 'Glob', hooks: [
-        { type: 'command', command: `node ${h('glob-guard.js')}` },
-      ]},
-    ],
-    PostToolUse: [
-      { matcher: 'Write|Edit|MultiEdit', hooks: [
-        { type: 'command', command: `node ${h('file-guard.js')}` },
-      ]},
-    ],
-    Stop: [
-      { matcher: '', hooks: [
-        { type: 'command', command: `bash ${h('self-review.sh')}` },
-      ]},
-    ],
-  };
+  return buildHookConfig('claude', dir, hooksSet)?.hooks || {};
 }
 
 function isDevkitHookCommand(command) {
@@ -113,7 +84,7 @@ function stripDevkitHooks(existingHooks) {
  * Merge devkit hook registrations into ~/.claude/settings.json.
  * Preserves any existing non-devkit hooks the user may have.
  */
-export async function mergeGlobalSettings(globalHooksDir) {
+export async function mergeGlobalSettings(globalHooksDir, hooksSet = null) {
   const settingsPath = join(homedir(), '.claude', 'settings.json');
   let existing = {};
   try {
@@ -121,7 +92,7 @@ export async function mergeGlobalSettings(globalHooksDir) {
   } catch { /* file doesn't exist yet — start fresh */ }
 
   const cleanedHooks = stripDevkitHooks(existing.hooks);
-  const newEntries = buildGlobalHookEntries(globalHooksDir);
+  const newEntries = buildGlobalHookEntries(globalHooksDir, hooksSet);
   const mergedHooks = { ...cleanedHooks };
   for (const [event, entries] of Object.entries(newEntries)) {
     mergedHooks[event] = [...(mergedHooks[event] || []), ...entries];
@@ -147,37 +118,44 @@ export async function removeGlobalHooksFromSettings() {
 }
 
 /**
- * Copy a skill to the global ~/.claude/skills/ directory.
- * Strips the 'skills/' prefix so sp-plan/SKILL.md lands at ~/.claude/skills/sp-plan/SKILL.md.
- * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string }}
+ * Install one skill file into an agent's GLOBAL (user-level) dir, with the agent's
+ * own content transformation (frontmatter, AskUserQuestion rewrite, subagent caveat).
+ * Works for every agent with a globalSkillRoot — Claude emits identity content, others
+ * get their own frontmatter. Idempotency is keyed on the EMITTED content (which differs
+ * from the kit source for non-Claude agents). The manifest key is the home-relative
+ * emitted path, unique per agent.
+ * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string, key: string } | null}
+ *   null when the agent has no global dir (Cursor) or the path isn't a skill file.
  */
-export async function installSkillGlobal(skillRelPath, globalSkillsDir, { force = false, globalFiles = {} } = {}) {
-  const stripped = skillRelPath.replace(/^skills\//, '');
-  const src = join(getTemplateDir(), skillRelPath);
-  const dst = join(globalSkillsDir, stripped);
+export async function installSkillGlobalForAgent(agentId, skillRelPath, { force = false, globalFiles = {} } = {}) {
+  const srcContent = await readFile(join(getTemplateDir(), skillRelPath), 'utf-8');
+  const emitted = emitSkillFileGlobal(agentId, skillRelPath, srcContent);
+  if (!emitted) return null;
 
-  const { hashFile } = await import('./hasher.js');
-  const srcHash = await hashFile(src);
+  const dst = join(homedir(), ...emitted.path.split('/'));
+  const display = `~/${emitted.path}`;
+  const key = emitted.path;
+  const srcHash = hashContent(emitted.content);
 
   if (existsSync(dst) && !force) {
     try {
-      const dstHash = await hashFile(dst);
-      if (srcHash === dstHash) {
-        log.same(`~/.claude/skills/${stripped} (identical)`);
-        return { result: 'identical', kitHash: srcHash };
+      const dstHash = hashContent(await readFile(dst, 'utf-8'));
+      if (dstHash === srcHash) {
+        log.same(`${display} (identical)`);
+        return { result: 'identical', kitHash: srcHash, key };
       }
-      const savedKitHash = globalFiles[skillRelPath]?.kitHash;
-      if (savedKitHash && dstHash === savedKitHash) {
-        // fall through to copy
-      } else {
-        log.skip(`~/.claude/skills/${stripped} (customized — use --force to overwrite)`);
-        return { result: 'skipped', kitHash: srcHash };
+      // Overwrite only a stale version we wrote (disk matches the recorded kit hash);
+      // otherwise the user customized it (or it's untracked) → preserve.
+      const savedKitHash = globalFiles[key]?.kitHash;
+      if (!(savedKitHash && dstHash === savedKitHash)) {
+        log.skip(`${display} (customized — use --force to overwrite)`);
+        return { result: 'skipped', kitHash: srcHash, key };
       }
-    } catch { /* hash failed, treat as conflict */ }
+    } catch { /* hash failed, treat as conflict → overwrite below */ }
   }
 
   await mkdir(dirname(dst), { recursive: true });
-  await fsCopyFile(src, dst);
-  log.copy(`~/.claude/skills/${stripped}`);
-  return { result: 'copied', kitHash: srcHash };
+  await writeFile(dst, emitted.content);
+  log.copy(display);
+  return { result: 'copied', kitHash: srcHash, key };
 }