harness-everything 0.2.2 → 0.4.0

package/scripts/lib/manifest.js

@@ -2,20 +2,11 @@
 // precisely those paths instead of sweeping shared directories that may also
 // hold content from other tools, the user's own manual additions, or
 // self-evolve's locally-generated skills.
-//
-// The manifest always lives at <platform-home>/harness-everything/manifest.json
-// - e.g. .claude/harness-everything/manifest.json, .cursor/harness-everything/
-// manifest.json, or (global scope) ~/.agents/harness-everything/manifest.json.
-// harness-everything/ is a subfolder this package exclusively owns inside a
-// directory that already belongs to that platform (or, for global scope, the
-// shared ~/.agents convention) - nothing else creates a directory literally
-// named "harness-everything" there, so nesting under it is what makes "the
-// manifest can only describe our own installs" actually true.
 const fs = require('fs');
 const path = require('path');
 
 const PACKAGE_NAME = 'harness-everything';
-const HARNESS_AUTHOR = 'Miya Daniel | Harness Core Team';
+const HARNESS_AUTHOR = 'Miya Daniel';
 const HARNESS_DIR_NAME = 'harness-everything';
 
 function getHarnessDir(homeDir) {
@@ -27,15 +18,14 @@ function getManifestPath(homeDir) {
 }
 
 function readManifest(manifestPath) {
-  if (!fs.existsSync(manifestPath)) {
-    return { package: PACKAGE_NAME, skills: [] };
-  }
+  if (!fs.existsSync(manifestPath)) return { package: PACKAGE_NAME, skills: [], agents: [] };
   try {
     const data = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
     if (!Array.isArray(data.skills)) data.skills = [];
+    if (!Array.isArray(data.agents)) data.agents = [];
     return data;
   } catch (e) {
-    return { package: PACKAGE_NAME, skills: [] };
+    return { package: PACKAGE_NAME, skills: [], agents: [] };
   }
 }
 
@@ -44,29 +34,95 @@ function writeManifest(manifestPath, data) {
   fs.writeFileSync(manifestPath, JSON.stringify(data, null, 2), 'utf8');
 }
 
-function recordSkillInstall(manifestPath, packageVersion, skillId, dirPath) {
+function isManifestEmpty(data) {
+  return (data.skills || []).length === 0 &&
+    (data.generated || []).length === 0 &&
+    (data.agents || []).length === 0;
+}
+
+// `references/` is copied by the installer into the same Harness-owned
+// bookkeeping directory as manifest.json. Once the manifest contains no
+// owned artifacts, both are package-owned leftovers and can be removed as a
+// unit without touching the platform home around them.
+function removeManifestArtifactsIfEmpty(manifestPath, data) {
+  if (!isManifestEmpty(data)) return false;
+  if (fs.existsSync(manifestPath)) fs.unlinkSync(manifestPath);
+  const harnessDir = path.dirname(manifestPath);
+  const referencesDir = path.join(harnessDir, 'references');
+  if (fs.existsSync(referencesDir)) fs.rmSync(referencesDir, { recursive: true, force: true });
+  try {
+    if (fs.existsSync(harnessDir) && fs.readdirSync(harnessDir).length === 0) fs.rmdirSync(harnessDir);
+  } catch (e) {
+    // Another owned runtime artifact may still live here; leave it intact.
+  }
+  return true;
+}
+
+function recordSkillInstall(manifestPath, packageVersion, skillId, dirPath, linkInfo = {}) {
   const data = readManifest(manifestPath);
   data.package = PACKAGE_NAME;
   data.version = packageVersion;
   data.updatedAt = new Date().toISOString();
   const idx = data.skills.findIndex(s => s.dirPath === dirPath);
   const entry = { id: skillId, dirPath, installedAt: new Date().toISOString() };
+  if (linkInfo.kind && linkInfo.kind !== 'copy') {
+    entry.kind = linkInfo.kind;
+    entry.canonicalPath = linkInfo.canonicalPath;
+  }
   if (idx !== -1) data.skills[idx] = entry;
   else data.skills.push(entry);
   writeManifest(manifestPath, data);
 }
 
-// Removes one skill entry, and - once no skills remain in it - deletes the
-// manifest file itself rather than leaving an empty bookkeeping file behind.
+function recordAgentInstall(manifestPath, packageVersion, agentId, filePath) {
+  const data = readManifest(manifestPath);
+  data.package = PACKAGE_NAME;
+  data.version = packageVersion;
+  data.updatedAt = new Date().toISOString();
+  const idx = data.agents.findIndex(agent => agent.filePath === filePath);
+  const entry = { id: agentId, filePath, installedAt: new Date().toISOString() };
+  if (idx !== -1) data.agents[idx] = entry;
+  else data.agents.push(entry);
+  writeManifest(manifestPath, data);
+}
+
+function recordGeneratedSkill(manifestPath, skillId, dirPath, description, triggers = []) {
+  const data = readManifest(manifestPath);
+  if (!Array.isArray(data.generated)) data.generated = [];
+  data.updatedAt = new Date().toISOString();
+  const idx = data.generated.findIndex(s => s.dirPath === dirPath || s.id === skillId);
+  const entry = {
+    id: skillId,
+    dirPath,
+    description,
+    triggers: Array.isArray(triggers) ? triggers : [],
+    generatedAt: new Date().toISOString()
+  };
+  if (idx !== -1) data.generated[idx] = { ...data.generated[idx], ...entry };
+  else data.generated.push(entry);
+  writeManifest(manifestPath, data);
+}
+
+function removeGeneratedSkill(manifestPath, dirPath) {
+  if (!fs.existsSync(manifestPath)) return;
+  const data = readManifest(manifestPath);
+  if (!Array.isArray(data.generated)) return;
+  data.generated = data.generated.filter(s => s.dirPath !== dirPath);
+  if (!removeManifestArtifactsIfEmpty(manifestPath, data)) writeManifest(manifestPath, data);
+}
+
 function removeSkillFromManifest(manifestPath, dirPath) {
   if (!fs.existsSync(manifestPath)) return;
   const data = readManifest(manifestPath);
   data.skills = data.skills.filter(s => s.dirPath !== dirPath);
-  if (data.skills.length === 0) {
-    fs.unlinkSync(manifestPath);
-  } else {
-    writeManifest(manifestPath, data);
-  }
+  if (!removeManifestArtifactsIfEmpty(manifestPath, data)) writeManifest(manifestPath, data);
+}
+
+function removeAgentFromManifest(manifestPath, filePath) {
+  if (!fs.existsSync(manifestPath)) return;
+  const data = readManifest(manifestPath);
+  data.agents = data.agents.filter(agent => agent.filePath !== filePath);
+  if (!removeManifestArtifactsIfEmpty(manifestPath, data)) writeManifest(manifestPath, data);
 }
 
 module.exports = {
@@ -78,5 +134,9 @@ module.exports = {
   readManifest,
   writeManifest,
   recordSkillInstall,
+  recordAgentInstall,
+  recordGeneratedSkill,
+  removeGeneratedSkill,
   removeSkillFromManifest,
-};
+  removeAgentFromManifest,
+};

package/scripts/lib/path-boundary.js

@@ -0,0 +1,90 @@
+const fs = require('fs');
+const path = require('path');
+
+function boundaryError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function realpath(p) {
+  const resolver = fs.realpathSync.native || fs.realpathSync;
+  return resolver(p);
+}
+
+// Resolve the deepest existing ancestor first, then append missing segments.
+// This preserves the physical location of an existing junction/symlink even
+// when the final file has not been created yet.
+function canonicalizePath(candidate) {
+  const absolute = path.resolve(candidate);
+  const missing = [];
+  let cursor = absolute;
+
+  while (true) {
+    try {
+      fs.lstatSync(cursor);
+      return path.join(realpath(cursor), ...missing);
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error.code)) throw error;
+      const parent = path.dirname(cursor);
+      if (parent === cursor) return path.join(cursor, ...missing);
+      missing.unshift(path.basename(cursor));
+      cursor = parent;
+    }
+  }
+}
+
+function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (
+    relative !== '..' &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  );
+}
+
+// A caller may intentionally choose a symlink as the boundary root. Links
+// below that root are rejected so a later write/delete cannot follow an alias
+// whose target was changed after the initial lexical path check.
+function assertNoLinkComponents(root, candidate) {
+  const lexicalRoot = path.resolve(root);
+  const lexicalCandidate = path.resolve(candidate);
+  const relative = path.relative(lexicalRoot, lexicalCandidate);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return;
+
+  let cursor = lexicalRoot;
+  for (const segment of relative ? relative.split(path.sep) : []) {
+    cursor = path.join(cursor, segment);
+    try {
+      if (fs.lstatSync(cursor).isSymbolicLink()) {
+        throw boundaryError('LINK_COMPONENT_IN_BOUNDARY', `Link component is not allowed below boundary: ${cursor}`);
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') break;
+      throw error;
+    }
+  }
+}
+
+function assertContainedPath(root, candidate) {
+  if (typeof root !== 'string' || typeof candidate !== 'string') {
+    throw boundaryError('INVALID_BOUNDARY_PATH', 'Boundary root and candidate must be strings');
+  }
+
+  assertNoLinkComponents(root, candidate);
+  const physicalRoot = canonicalizePath(root);
+  const physicalCandidate = canonicalizePath(candidate);
+  if (!isWithin(physicalRoot, physicalCandidate)) {
+    throw boundaryError(
+      'PATH_OUTSIDE_BOUNDARY',
+      `Path escapes boundary: ${candidate} is outside ${root}`
+    );
+  }
+  return { root: physicalRoot, target: physicalCandidate };
+}
+
+module.exports = {
+  assertContainedPath,
+  canonicalizePath,
+  isWithin,
+};

package/scripts/lib/prompts.js

@@ -159,7 +159,7 @@ function interactiveSingleSelect(items) {
       readline.cursorTo(process.stdout, 0);
       for (let i = 0; i < items.length; i++) {
         const item = items[i];
-        const isSelected = item.checked ? '(o)' : '( )';
+        const isSelected = item.checked ? '[x]' : '[ ]';
         const isCurrent = i === cursor ? '> ' : '  ';
         readline.clearLine(process.stdout, 0);
         process.stdout.write(`${isCurrent}${isSelected} ${item.name}\n`);

package/scripts/lib/skills.js

@@ -9,23 +9,37 @@ function copyDir(src, dest) {
   for (const entry of entries) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      copyDir(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
+    if (entry.isDirectory()) copyDir(srcPath, destPath);
+    else fs.copyFileSync(srcPath, destPath);
   }
 }
 
+function isLinkPath(p) {
+  try { return fs.lstatSync(p).isSymbolicLink(); } catch (e) { return false; }
+}
+
+function pathPresent(p) {
+  return isLinkPath(p) || fs.existsSync(p);
+}
+
+function removePathSafely(p) {
+  if (pathPresent(p)) fs.rmSync(p, { recursive: true, force: true });
+}
+
+// `.agents/skills/` is the canonical per-scope store used for deduplication.
+// Some hosts consume that path natively (for example Codex project skills),
+// while others link from their own native directories (Continue/Hermes).
+function getCanonicalSkillsDir({ isGlobal, workspaceRoot, userHome }) {
+  return path.join(isGlobal ? userHome : workspaceRoot, '.agents', 'skills');
+}
+
 function getAvailableSkills(harnessSourceDir) {
   const dirs = fs.readdirSync(harnessSourceDir, { withFileTypes: true });
   const skills = [];
   for (const dir of dirs) {
     if (dir.isDirectory() && !dir.name.startsWith('.') && !['bin', 'docs', 'hooks', 'scripts', 'node_modules'].includes(dir.name)) {
       const skillPath = path.join(harnessSourceDir, dir.name, 'SKILL.md');
-      if (fs.existsSync(skillPath)) {
-        skills.push(dir.name);
-      }
+      if (fs.existsSync(skillPath)) skills.push(dir.name);
     }
   }
   return skills.sort();
@@ -42,7 +56,16 @@ function parseFrontmatter(skillMdPath) {
       const m = yaml.match(new RegExp(`^${key}:\\s*(.*)$`, 'm'));
       return m ? m[1].trim().replace(/^['"]|['"]$/g, '') : '';
     };
-    return { name: get('name'), description: get('description'), author: get('author'), version: get('version') };
+    const getMeta = (key) => {
+      const m = yaml.match(new RegExp(`^[ \\t]+${key}:\\s*(.*)$`, 'm'));
+      return m ? m[1].trim().replace(/^['"]|['"]$/g, '') : '';
+    };
+    return {
+      name: get('name'),
+      description: get('description'),
+      author: getMeta('author') || get('author'),
+      version: getMeta('version') || get('version'),
+    };
   } catch (e) {
     return null;
   }
@@ -54,32 +77,104 @@ function getSkillInfo(harnessSourceDir, skillDirName) {
   return { id: skillDirName, name: fm.name || skillDirName, description: fm.description || '' };
 }
 
-// The one signal that lets uninstall tell "a skill this package shipped"
-// apart from anything else living in the same shared skills folder (Cursor/
-// Copilot/Codex/Continue skills keep their platform-native location, so it's
-// still a shared folder) - including a user's own manually-installed skills
-// and self-evolve's locally-generated `skills/generated/*` skills, neither
-// of which carry this author string.
 function isHarnessSkillDir(dirPath) {
   const fm = parseFrontmatter(path.join(dirPath, 'SKILL.md'));
   return !!fm && fm.author === manifest.HARNESS_AUTHOR;
 }
 
-// targetDirs entries: { path, label, manifestPath } - manifestPath is that
-// target's own <platform-home>/harness-everything/manifest.json.
-function installSkillsToTargets({ chosenSkills, targetDirs, harnessSourceDir, packageVersion }) {
+function ensureCanonicalSkill({ canonicalDir, skillName, harnessSourceDir }) {
+  const dest = path.join(canonicalDir, skillName);
+  removePathSafely(dest);
+  copyDir(path.join(harnessSourceDir, skillName), dest);
+  return dest;
+}
+
+function linkOrCopySkill({ dest, canonicalSkillDir, harnessSourceDir, skillName, linkMode }) {
+  removePathSafely(dest);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+  if (linkMode === 'copy') {
+    copyDir(path.join(harnessSourceDir, skillName), dest);
+    return { kind: 'copy' };
+  }
+
+  const symlinkType = process.platform === 'win32' ? 'junction' : 'dir';
+  try {
+    fs.symlinkSync(canonicalSkillDir, dest, symlinkType);
+    return { kind: symlinkType === 'junction' ? 'junction' : 'symlink', canonicalPath: canonicalSkillDir };
+  } catch (e) {
+    if (linkMode === 'symlink') throw new Error(`Failed to create symlink at ${dest}: ${e.message}`);
+    copyDir(path.join(harnessSourceDir, skillName), dest);
+    return { kind: 'copy' };
+  }
+}
+
+function installSkillsToTargets({ chosenSkills, targetDirs, harnessSourceDir, packageVersion, canonicalDir, linkMode = 'auto' }) {
+  const useCanonical = !!canonicalDir && linkMode !== 'copy';
+  const canonicalSkillDirs = {};
+  if (useCanonical) {
+    for (const skillName of chosenSkills) {
+      canonicalSkillDirs[skillName] = ensureCanonicalSkill({ canonicalDir, skillName, harnessSourceDir });
+    }
+  }
+
   for (const target of targetDirs) {
     fs.mkdirSync(target.path, { recursive: true });
+    const refSrc = path.join(harnessSourceDir, 'references');
+    if (fs.existsSync(refSrc)) {
+      const refDest = path.join(path.dirname(target.manifestPath), 'references');
+      if (fs.existsSync(refDest)) fs.rmSync(refDest, { recursive: true, force: true });
+      copyDir(refSrc, refDest);
+    }
+
+    const targetIsCanonical = useCanonical && path.resolve(target.path) === path.resolve(canonicalDir);
     for (const skillName of chosenSkills) {
-      const src = path.join(harnessSourceDir, skillName);
       const dest = path.join(target.path, skillName);
-      if (fs.existsSync(dest)) {
-        fs.rmSync(dest, { recursive: true, force: true });
+      let result;
+      if (!useCanonical) {
+        removePathSafely(dest);
+        copyDir(path.join(harnessSourceDir, skillName), dest);
+        result = { kind: 'copy' };
+      } else if (targetIsCanonical) {
+        result = { kind: 'copy' };
+      } else {
+        result = linkOrCopySkill({ dest, canonicalSkillDir: canonicalSkillDirs[skillName], harnessSourceDir, skillName, linkMode });
+      }
+      manifest.recordSkillInstall(target.manifestPath, packageVersion, skillName, dest, result);
+      const suffix = result.kind === 'copy' ? '' : ` (${result.kind} -> ${path.relative(path.dirname(dest), result.canonicalPath)})`;
+      console.log(`  ✅ Installed skill: ${target.label}${skillName}/${suffix}`);
+    }
+  }
+}
+
+function installAgentsToTarget({ target, harnessSourceDir, packageVersion }) {
+  const sourceDir = path.join(harnessSourceDir, 'fable-mode', 'agents');
+  if (!fs.existsSync(sourceDir) || !target || !target.path || !target.manifestPath) return;
+
+  fs.mkdirSync(target.path, { recursive: true });
+  const trackedPaths = new Set((manifest.readManifest(target.manifestPath).agents || []).map(agent => agent.filePath));
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destPath = path.join(target.path, entry.name);
+    if (fs.existsSync(destPath)) {
+      const source = fs.readFileSync(sourcePath, 'utf8');
+      const existing = fs.readFileSync(destPath, 'utf8');
+      if (source !== existing) {
+        console.warn(`  ⚠️ Preserved existing agent without overwrite: ${destPath}`);
+        continue;
+      }
+      if (!trackedPaths.has(destPath)) {
+        console.warn(`  ⚠️ Preserved pre-existing identical agent without claiming ownership: ${destPath}`);
+        continue;
       }
-      copyDir(src, dest);
-      manifest.recordSkillInstall(target.manifestPath, packageVersion, skillName, dest);
-      console.log(`  ✅ Installed skill: ${target.label}${skillName}/`);
+    } else {
+      fs.copyFileSync(sourcePath, destPath);
+      console.log(`  ✅ Installed agent: ${target.label}${entry.name}`);
     }
+    const agentInfo = parseFrontmatter(sourcePath);
+    const agentName = (agentInfo && agentInfo.name) || entry.name.replace(/\.md$/i, '');
+    manifest.recordAgentInstall(target.manifestPath, packageVersion, agentName, destPath);
   }
 }
 
@@ -87,20 +182,22 @@ function manifestTrackedSkills(manifestPath, scopeLabel) {
   const data = manifest.readManifest(manifestPath);
   const results = [];
   for (const entry of data.skills || []) {
-    if (fs.existsSync(entry.dirPath) && isHarnessSkillDir(entry.dirPath)) {
-      results.push({ id: entry.id, scope: scopeLabel, dirPath: entry.dirPath, parentPath: path.dirname(entry.dirPath), manifestPath });
-    }
+    const linked = isLinkPath(entry.dirPath);
+    if (!linked && (!fs.existsSync(entry.dirPath) || !isHarnessSkillDir(entry.dirPath))) continue;
+    results.push({
+      id: entry.id,
+      scope: scopeLabel,
+      dirPath: entry.dirPath,
+      parentPath: path.dirname(entry.dirPath),
+      manifestPath,
+      canonicalPath: entry.canonicalPath || null,
+    });
   }
   return results;
 }
 
-// Returns every skill this package can currently account for, scoped local +
-// global. Never lists a directory just because it happens to live under a
-// known skills folder - only manifest-recorded installs (or, as a fallback
-// for pre-manifest / pre-reorg installs, directories that still self-identify
-// via the author marker) qualify. This is what keeps "uninstall skills" from
-// ever touching a skill this package didn't put there.
-function getInstalledSkills(workspaceRoot, userHome) {
+function getInstalledSkills(workspaceRoot, userHome, opts = {}) {
+  const includeLegacy = opts.includeLegacy !== false;
   const results = [];
   const globalAgentsDir = path.join(userHome, '.agents');
 
@@ -110,30 +207,32 @@ function getInstalledSkills(workspaceRoot, userHome) {
     { home: path.join(workspaceRoot, '.github'), scope: 'local (Copilot)' },
     { home: path.join(workspaceRoot, '.codex'), scope: 'local (Codex)' },
     { home: path.join(workspaceRoot, '.continue'), scope: 'local (Continue)' },
-    { home: path.join(userHome, '.claude'), scope: 'global (Claude)' },
+    { home: path.join(workspaceRoot, '.hermes'), scope: 'local (Hermes)' },
+    { home: path.join(userHome, '.claude'), scope: 'global' },
     { home: globalAgentsDir, scope: 'global' },
+    { home: path.join(userHome, '.continue'), scope: 'global' },
+    { home: path.join(userHome, '.hermes'), scope: 'global' },
   ];
   for (const { home, scope } of manifestHomes) {
     results.push(...manifestTrackedSkills(manifest.getManifestPath(home), scope));
   }
 
-  // Legacy fallback for installs that predate per-platform manifests (or the
-  // old self-invented .harness/ local root, or - for Codex specifically - an
-  // earlier version's mistaken `.agents/skills` target; Codex's real project
-  // skills directory is `.codex/skills/`): scan the raw directories
-  // directly, but only ever list an entry that still self-identifies via the
-  // author marker - never a blind directory listing.
+  if (!includeLegacy) return results;
+
   const legacyDirs = [
     { path: path.join(workspaceRoot, '.harness', 'skills'), scope: 'local (legacy .harness)', manifestPath: manifest.getManifestPath(path.join(workspaceRoot, '.claude')) },
     { path: path.join(workspaceRoot, '.claude', 'harness-everything', 'skills'), scope: 'local (Claude legacy erroneous path)', manifestPath: manifest.getManifestPath(path.join(workspaceRoot, '.claude')) },
     { path: path.join(workspaceRoot, '.cursor', 'skills'), scope: 'local (Cursor)', manifestPath: manifest.getManifestPath(path.join(workspaceRoot, '.cursor')) },
     { path: path.join(workspaceRoot, '.github', 'skills'), scope: 'local (Copilot)', manifestPath: manifest.getManifestPath(path.join(workspaceRoot, '.github')) },
-    { path: path.join(workspaceRoot, '.codex', 'skills'), scope: 'local (Codex)', manifestPath: manifest.getManifestPath(path.join(workspaceRoot, '.codex')) },
-    { path: path.join(workspaceRoot, '.agents', 'skills'), scope: 'local (Codex, legacy .agents path)', manifestPath: manifest.getManifestPath(path.join(workspaceRoot, '.codex')) },
+    { path: path.join(workspaceRoot, '.codex', 'skills'), scope: 'local (Codex legacy .codex path)', manifestPath: manifest.getManifestPath(path.join(workspaceRoot, '.codex')) },
+    { path: path.join(workspaceRoot, '.agents', 'skills'), scope: 'local (shared Agent Skills)', manifestPath: manifest.getManifestPath(path.join(workspaceRoot, '.codex')) },
     { path: path.join(workspaceRoot, '.continue', 'skills'), scope: 'local (Continue)', manifestPath: manifest.getManifestPath(path.join(workspaceRoot, '.continue')) },
     { path: path.join(globalAgentsDir, 'skills'), scope: 'global', manifestPath: manifest.getManifestPath(globalAgentsDir) },
+    { path: path.join(userHome, '.continue', 'skills'), scope: 'global', manifestPath: manifest.getManifestPath(path.join(userHome, '.continue')) },
+    { path: path.join(userHome, '.hermes', 'skills'), scope: 'global', manifestPath: manifest.getManifestPath(path.join(userHome, '.hermes')) },
   ];
-  const known = new Set(results.map(r => r.dirPath));
+
+  const known = new Set(results.flatMap(r => r.canonicalPath ? [r.dirPath, r.canonicalPath] : [r.dirPath]));
   for (const item of legacyDirs) {
     if (!fs.existsSync(item.path)) continue;
     try {
@@ -148,27 +247,68 @@ function getInstalledSkills(workspaceRoot, userHome) {
         }
       }
     } catch (e) {
-      // ignore unreadable dirs
+      // Ignore unreadable fallback directories.
     }
   }
   return results;
 }
 
-function removeSkill(entry) {
-  if (fs.existsSync(entry.dirPath)) {
-    fs.rmSync(entry.dirPath, { recursive: true, force: true });
+function getInstalledAgents(workspaceRoot, userHome) {
+  const homes = [
+    { home: path.join(workspaceRoot, '.claude'), scope: 'local (Claude)' },
+    { home: path.join(userHome, '.claude'), scope: 'global (Claude)' },
+  ];
+  const results = [];
+  for (const { home, scope } of homes) {
+    const manifestPath = manifest.getManifestPath(home);
+    const data = manifest.readManifest(manifestPath);
+    for (const entry of data.agents || []) {
+      if (entry.filePath && fs.existsSync(entry.filePath)) results.push({ ...entry, scope, manifestPath });
+    }
   }
-  if (entry.manifestPath) {
-    manifest.removeSkillFromManifest(entry.manifestPath, entry.dirPath);
+  return results;
+}
+
+function removeSkill(entry, ctx = {}) {
+  const wasLink = isLinkPath(entry.dirPath);
+  removePathSafely(entry.dirPath);
+  if (entry.manifestPath) manifest.removeSkillFromManifest(entry.manifestPath, entry.dirPath);
+
+  if (!ctx.workspaceRoot || !ctx.userHome) return;
+
+  if (wasLink && entry.canonicalPath) {
+    const stillInUse = getInstalledSkills(ctx.workspaceRoot, ctx.userHome, { includeLegacy: false }).some(
+      s => s.dirPath === entry.canonicalPath || s.canonicalPath === entry.canonicalPath
+    );
+    if (!stillInUse) removePathSafely(entry.canonicalPath);
+  } else if (!wasLink) {
+    const dependents = getInstalledSkills(ctx.workspaceRoot, ctx.userHome, { includeLegacy: false }).filter(
+      s => s.canonicalPath === entry.dirPath
+    );
+    for (const dep of dependents) {
+      removePathSafely(dep.dirPath);
+      if (dep.manifestPath) manifest.removeSkillFromManifest(dep.manifestPath, dep.dirPath);
+    }
   }
 }
 
+function removeAgent(entry) {
+  if (entry.filePath && fs.existsSync(entry.filePath)) fs.unlinkSync(entry.filePath);
+  if (entry.manifestPath) manifest.removeAgentFromManifest(entry.manifestPath, entry.filePath);
+}
+
 module.exports = {
   copyDir,
   getAvailableSkills,
   getSkillInfo,
   isHarnessSkillDir,
+  isLinkPath,
+  pathPresent,
+  getCanonicalSkillsDir,
   installSkillsToTargets,
+  installAgentsToTarget,
   getInstalledSkills,
+  getInstalledAgents,
   removeSkill,
-};
+  removeAgent,
+};