feat(cli): skills freshness — version check, manifest, global install + multi-agent mirror (#1753)

* feat(cli): add skills version check, update, and freshness manifest Give the HyperFrames skill bundle a content fingerprint so agents and users can tell whether installed skills are the latest version, on any platform that can run the CLI. - skills-manifest.json (repo root): per-skill sha256 over the whole skill directory; minimal {source, skills}, no version/timestamp so it is fully deterministic. Generated by scripts/gen-skills-manifest.ts. - `hyperframes skills check` [--json]: compares installed skills to the manifest; exits non-zero when something is outdated (agent/CI gate). - `hyperframes skills update`: thin wrapper over `npx skills update`. - Passive nudge on render/lint/validate when skills are stale (24h cache, same opt-out as the CLI self-update notice). - "latest" resolved via `git ls-remote` + SHA-pinned raw URL to dodge GitHub raw-CDN lag, falling back to the main branch URL. - CI job + lefthook hook keep skills-manifest.json in sync with skills/. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): add execFile to child_process mock in skills test skills.test.ts mocks node:child_process but only declared execFileSync and spawn. Loading skills.js transitively loads skillsManifest.ts, which runs promisify(execFile) at module load, so vitest threw on the missing execFile named export. Add a bare stub — these tests never invoke it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(cli): init installs all skills; skills update pulls the full set Make `hyperframes init` the single place skills are pulled in full, and make "update" mean "get everything" rather than "refresh what's there". - init now always installs/refreshes ALL skills (incl. ones not yet present) instead of prompting "Install AI coding skills?" — opt out with `init --skip-skills`. Both the interactive and non-interactive paths pass `--all --yes` so the complete set is fetched. - `hyperframes skills update` switches from `npx skills update` (which only refreshes already-installed skills) to `skills add --all`, so it installs missing skills too — the same install step init runs. - SKILL.md documents init-installs-all and the new update semantics. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(cli): skills check treats missing skills as needing an update The full skill set is now the goal (init and `skills update` both pull all, including ones not installed), so a partial install is no longer "a choice" — it's something to fix. - diffSkills: updateAvailable is now true when anything is outdated OR missing (local-only still doesn't count). So `skills check` exits non-zero — and renders "Update:" instead of "up to date" — whenever a skill is missing, not just when one is stale. - The passive render/lint/validate nudge follows suit: it now counts missing alongside outdated ("N skills out of date or missing"), tracked via a new skillsMissingCount cache field. - SKILL.md documents the stricter check. Note: platforms that intentionally vendor only a subset of skills (e.g. a Codex snapshot) will now see check report non-zero. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): install/update skills straight from the GitHub repo `skills add owner/repo` can resolve through the skills.sh registry, which lags behind the repo — so `update` could install a stale version while `check` (which resolves latest directly from GitHub) keeps reporting "outdated", an endless loop. Switch the install source to the full GitHub URL (https://github.com/heygen-com/hyperframes), which makes `skills add` git-clone the repo directly at latest main, bypassing the registry. This covers `hyperframes skills`, `hyperframes skills update`, and `init`'s skill install — all of which go through SOURCES. Now install/update and check agree on what "latest" means. The init "install skills" hint now points at `npx hyperframes skills update` so the manual path uses the same GitHub-direct fetch. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(cli): init checks skills against GitHub, installs only when stale `hyperframes init` now runs the skills version check first and only (re)installs when something is outdated or missing — instead of unconditionally re-pulling every time. Re-running init on an already-current project is now a no-op ("skills are already up to date"). - New ensureSkillsCurrent() helper, shared by both the interactive and non-interactive init paths (no duplicated install logic). - The check resolves "latest" straight from GitHub (same source the install uses); best-effort — if it can't reach GitHub it installs anyway. - SKILL.md updated to describe the check-then-install behavior. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(cli): address skills manifest review feedback From the PR review (points 1, 2, 4, 5): 1. Remove the `local-only` skill status. checkSkills only ever hashes manifest-listed skills, so a local-only status could never appear in the end-to-end output — and making it appear would wrongly flag unrelated skills (the `.../skills` dir is shared across sources). diffSkills now reports only on manifest skills; skills on disk that aren't in the manifest are ignored. 2. Drop the redundant per-directory sort in listFilesSorted — the single final out.sort() is what guarantees a deterministic hash (verified: manifest unchanged). 4. resolveLatestManifest local-path detection now uses path.isAbsolute, so Windows absolute paths (C:\...) are treated as local instead of falling through to a remote fetch. 5. fetchManifest validates the response shape (asSkillsManifest) instead of a blind `as` cast, so a CDN error page served as 200 fails with a clear error rather than a cryptic crash later in diffSkills. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): strict skills update + auto-discover any agent host Address PR review (Magi blocker + James/Rames robustness): - Blocker (Magi): `skills update` is the documented recovery path for `skills check || skills update`, but it delegated to installAllSkills() which swallowed missing-npx and failed `skills add` as "skipped", exiting 0 even when nothing changed. Add a strict mode that throws on failure; update sets a non-zero exit (init stays best-effort). New tests simulate a non-zero `skills add` (exit 1) and the success path. - Robustness (James/Rames #2): the upstream `skills` CLI installs into ~72 agent conventions; a hard-coded list (4, or even 11) can't track that. Replace defaultSkillRoots with discoverSkillRoots — it scans cwd + $HOME for any `<host>/skills/<manifest-skill>/SKILL.md` (plus the XDG `.config/<host>/skills`), so detection is structural and future-proof, no closed list. agentFromDir infers the host from the path. - Tests (Rames #3): temp-fixture detection tests for every convention × {project, global}, scope priority, claude-code preference, the no-install case, the --dir override, and an unknown/new host (proving the no-closed-list property). - Docs (Rames #4/#5): SKILL.md notes init's best-effort GitHub round-trip; findRepoManifest climbs 16 levels (was 8) for deep monorepos. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): resolve CodeQL file-system race + de-flake Windows npx test Two CI fixes: - CodeQL (high, js/file-system-race) at gen-skills-manifest.ts: the existsSync(outPath) precheck followed by writeFileSync(outPath) is a check-then-write race. Read the committed manifest directly in a try/catch instead (missing/unreadable ⇒ "no committed manifest"), so there's no precheck to race against. Behavior is unchanged. - Windows Tests: npxCommand.test.ts's real `npx --version` smoke test cold-starts slower than vitest's 5s default on Windows runners and timed out. Give the test 60s headroom (and a 30s exec timeout). Kept as a real execution check — mocking would reduce it to a tautology. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): repair garbled npx smoke-test timeout comment The explanatory comment for the 60s timeout was scrambled across the callback/timeout arguments, failing oxfmt --check (and thus preflight, which in turn skipped preview-parity and failed the regression gate). Move it above the it() call so it no longer sits between call arguments. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): install skills once globally + symlink-mirror to every agent The previous install path sprayed a full ~6.7MB skill copy into each of the ~70 agent conventions `skills add --all` knows (a fresh init produced 40+ dirs / 341MB, incl. a stray dotless `agent/` from the Eve convention). Install ONCE, globally, as one faithful copy, then symlink it everywhere: - `skills add <url> --skill '*' --global --agent claude-code universal --copy` lands real files in ~/.claude/skills (Claude Code reads this at global priority) and ~/.agents/skills (the shared universal store). - mirrorGlobalSkills() fans that store out to every OTHER installed agent's GLOBAL dir (~/.cursor/skills, goose -> ~/.config/goose/skills, ...) — but only for agents present on the machine (marker dir exists), so nothing is sprayed. Unix: per-skill relative symlink into the store (one source of truth, auto-fresh on update); Windows: copy (symlinks need admin / Developer Mode there — the same fallback upstream and gstack make). Why global: skills are framework-general knowledge, not project content; Claude Code (and most agents) prioritize the personal/global scope, so the global copy is the one actually loaded — and it installs once instead of multiplying per project. The per-agent dir list is GENERATED from upstream's src/agents.ts at a pinned tag (the `skills` package exports nothing importable), committed as agentDirs.generated.ts and resolved env-faithfully at runtime (XDG_CONFIG_HOME / CODEX_HOME / CLAUDE_CONFIG_DIR honored). Regenerate with `bun run --cwd packages/cli gen:agent-dirs` when the pin moves. Covers all 70 agents that define a global dir (eve/promptscript define none); the bare project-dir agents (openclaw, astrbot) are namespaced globally, so the stray-`agent/` footgun is gone. `skills check` now scans global ($HOME) before project (cwd) to match the runtime load order — so it reports on the copy the agent will really use, not a stale project copy a newer global install silently overrides. Test plan: - skills.test.ts: install spawns the global --copy args, never --all; update stays strict + exits non-zero on failure. - skillsMirror.test.ts: Unix relative symlinks, Windows copy, XDG_CONFIG_HOME honored, install-owned stores skipped, marker-gating, idempotent refresh, generated-table shape. - skillsManifest.test.ts: check is global-first. - Full CLI suite green (981); oxlint / oxfmt / tsc clean; gen:agent-dirs --check clean (offline + network produce byte-identical output). - Benchmark (isolated HOME, local CLI): claude+hermes and all 70 agents — ~/.claude + ~/.agents real (19 each), every installed agent's global dir = 19 symlinks into the store, zero spray into unseeded agents, check global-first. (The 9 "outdated" check reports are the separate skills.sh registry lag, not this change.) - .fallowrc.jsonc: exempt the codegen script's inherent parser complexity and the parallel-case duplication in skillsManifest.test.ts (same rationale the config already uses for SlideshowPanel.test.ts / hyperframes-player.test.ts). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): install skills with --full-depth so a fresh install reads as current `skills add <url>` without --full-depth fetches from the skills.sh registry blob ("Fetching skills"), which lags GitHub main by hours — so a freshly installed/updated set read as ~9 skills "outdated" right after install, and `skills update` couldn't fix it (it re-fetched the same stale blob → death loop). --full-depth switches it to a real `git clone` of HEAD ("Cloning repository"), the only path that yields the genuine latest. - Add --full-depth to the global install args. Verified (isolated HOME): blob path → 10 current / 9 outdated; --full-depth → 19 current / 0 outdated. - The clone is heavier than the blob fetch, so set GIT_LFS_SKIP_SMUDGE=1 (skills are text; the repo's LFS objects are unrelated binaries the install doesn't need) and raise the spawn timeout 120s → 300s. - Correct the stale comment that claimed a full URL already bypasses skills.sh — it doesn't; only --full-depth does. Benchmark (skills-bench, local CLI): B.death-loop and J1.init-detect-and-refresh flip FAIL → PASS (install/update/init now 19/0); mirror smoke reports 19 current / 0 outdated. (spine still reflects the raw documented `skills add <slug>` command — the upstream skills.sh path, not this CLI.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(skills): drop --skip-skills from workflow init so new projects refresh skills The creation workflows scaffolded with `hyperframes init … --skip-skills`, which skipped the skills currency check. Now that init installs globally, is a no-op when already current, and pulls the genuine latest (via --full-depth), there's no reason to skip it: removing --skip-skills means every new project runs the check and refreshes the global skill set from GitHub when it's stale. Add a one-line note to each workflow (embedded-captions, faceless-explainer, motion-graphics, music-to-video, pr-to-video, product-launch-video) and the hyperframes-cli + /hyperframes router explaining what init does. skills-manifest.json regenerated by the pre-commit hook to match the edited skill bundles. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): scope agent mirror to HyperFrames' own skills, not the whole store mirrorGlobalSkills listed every */SKILL.md in ~/.claude/skills and fanned them out — but that store is shared, so a user's gstack / personal / company Claude skills would get symlinked (and, since linkOrCopy removes the target first, could overwrite a same-named skill) into Cursor / Codex / Goose / etc. Scope the mirror to HyperFrames' own skills via the upstream lock's source attribution — the same definition the prune already uses (skillsAttributedToSource) — never a directory listing. New hyperframesSkillNames() reads the global lock and returns only skills attributed to heygen-com/hyperframes; the mirror intersects that allow-list with what's in the store. Empty (no lock / nothing attributed) → mirror nothing, never everything. Also fixes the cosmetic "director(ies)" log typo (now singular/plural-aware) and extracts the fan-out into mirrorToInstalledAgents() to keep installAllSkills under the complexity gate. Regression: skillsMirror.test.ts asserts a foreign gstack skill in the store is neither mirrored out nor allowed to replace another agent's same-named skill; the skills-bench harness seeds ~/.claude/skills/gstack and asserts it never leaks to any agent. 1045 CLI tests + lint/types/fallow green. Addresses Magi's request-changes on #1753. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-09-03 23:03:09 +00:00 · 2026-06-27 08:34:43 +08:00
parent e3edbd55cf
commit bf961d1268
23 changed files with 812 additions and 410 deletions
@@ -0,0 +1,101 @@
+// @generated by packages/cli/scripts/sync-agent-dirs.ts — DO NOT EDIT.
+// Source: vercel-labs/skills@v1.5.13 (src/agents.ts). Regenerate with:
+//   bun run --cwd packages/cli gen:agent-dirs
+//
+// Each entry is one agent the upstream `skills` CLI installs to. The agent's
+// GLOBAL skills directory is `join(<base>, <sub>)`, where `base` is one of the
+// env-overridable home dirs below (resolved at runtime by skillsMirror.ts, so
+// XDG_CONFIG_HOME / CODEX_HOME / CLAUDE_CONFIG_DIR are honored). Agents with no
+// global skills dir upstream (eve, promptscript) are omitted.
+
+/** Env-overridable base dirs, matching upstream agents.ts. */
+export type AgentDirBase =
+  | "home"
+  | "configHome"
+  | "codexHome"
+  | "claudeHome"
+  | "vibeHome"
+  | "hermesHome"
+  | "autohandHome";
+
+export interface AgentGlobalDir {
+  /** Upstream agent key. */
+  agent: string;
+  /** Base directory the global skills dir is rooted at. */
+  base: AgentDirBase;
+  /** POSIX suffix joined onto the resolved base. */
+  sub: string;
+}
+
+export const AGENT_GLOBAL_DIRS: readonly AgentGlobalDir[] = [
+  { agent: "aider-desk", base: "home", sub: ".aider-desk/skills" },
+  { agent: "amp", base: "configHome", sub: "agents/skills" },
+  { agent: "antigravity", base: "home", sub: ".gemini/antigravity/skills" },
+  { agent: "antigravity-cli", base: "home", sub: ".gemini/antigravity-cli/skills" },
+  { agent: "astrbot", base: "home", sub: ".astrbot/data/skills" },
+  { agent: "autohand-code", base: "autohandHome", sub: "skills" },
+  { agent: "augment", base: "home", sub: ".augment/skills" },
+  { agent: "bob", base: "home", sub: ".bob/skills" },
+  { agent: "claude-code", base: "claudeHome", sub: "skills" },
+  { agent: "openclaw", base: "home", sub: ".openclaw/skills" },
+  { agent: "cline", base: "home", sub: ".agents/skills" },
+  { agent: "codearts-agent", base: "home", sub: ".codeartsdoer/skills" },
+  { agent: "codebuddy", base: "home", sub: ".codebuddy/skills" },
+  { agent: "codemaker", base: "home", sub: ".codemaker/skills" },
+  { agent: "codestudio", base: "home", sub: ".codestudio/skills" },
+  { agent: "codex", base: "codexHome", sub: "skills" },
+  { agent: "command-code", base: "home", sub: ".commandcode/skills" },
+  { agent: "continue", base: "home", sub: ".continue/skills" },
+  { agent: "cortex", base: "home", sub: ".snowflake/cortex/skills" },
+  { agent: "crush", base: "home", sub: ".config/crush/skills" },
+  { agent: "cursor", base: "home", sub: ".cursor/skills" },
+  { agent: "deepagents", base: "home", sub: ".deepagents/agent/skills" },
+  { agent: "devin", base: "configHome", sub: "devin/skills" },
+  { agent: "dexto", base: "home", sub: ".agents/skills" },
+  { agent: "droid", base: "home", sub: ".factory/skills" },
+  { agent: "firebender", base: "home", sub: ".firebender/skills" },
+  { agent: "forgecode", base: "home", sub: ".forge/skills" },
+  { agent: "gemini-cli", base: "home", sub: ".gemini/skills" },
+  { agent: "github-copilot", base: "home", sub: ".copilot/skills" },
+  { agent: "goose", base: "configHome", sub: "goose/skills" },
+  { agent: "hermes-agent", base: "hermesHome", sub: "skills" },
+  { agent: "inference-sh", base: "home", sub: ".inferencesh/skills" },
+  { agent: "jazz", base: "home", sub: ".jazz/skills" },
+  { agent: "junie", base: "home", sub: ".junie/skills" },
+  { agent: "iflow-cli", base: "home", sub: ".iflow/skills" },
+  { agent: "kilo", base: "home", sub: ".kilocode/skills" },
+  { agent: "kimi-code-cli", base: "home", sub: ".agents/skills" },
+  { agent: "kiro-cli", base: "home", sub: ".kiro/skills" },
+  { agent: "kode", base: "home", sub: ".kode/skills" },
+  { agent: "lingma", base: "home", sub: ".lingma/skills" },
+  { agent: "loaf", base: "home", sub: ".agents/skills" },
+  { agent: "mcpjam", base: "home", sub: ".mcpjam/skills" },
+  { agent: "mistral-vibe", base: "vibeHome", sub: "skills" },
+  { agent: "moxby", base: "home", sub: ".moxby/skills" },
+  { agent: "mux", base: "home", sub: ".mux/skills" },
+  { agent: "opencode", base: "configHome", sub: "opencode/skills" },
+  { agent: "openhands", base: "home", sub: ".openhands/skills" },
+  { agent: "ona", base: "home", sub: ".ona/skills" },
+  { agent: "pi", base: "home", sub: ".pi/agent/skills" },
+  { agent: "qoder", base: "home", sub: ".qoder/skills" },
+  { agent: "qoder-cn", base: "home", sub: ".qoder-cn/skills" },
+  { agent: "qwen-code", base: "home", sub: ".qwen/skills" },
+  { agent: "replit", base: "configHome", sub: "agents/skills" },
+  { agent: "reasonix", base: "home", sub: ".reasonix/skills" },
+  { agent: "rovodev", base: "home", sub: ".rovodev/skills" },
+  { agent: "roo", base: "home", sub: ".roo/skills" },
+  { agent: "tabnine-cli", base: "home", sub: ".tabnine/agent/skills" },
+  { agent: "terramind", base: "home", sub: ".terramind/skills" },
+  { agent: "tinycloud", base: "home", sub: ".tinycloud/skills" },
+  { agent: "trae", base: "home", sub: ".trae/skills" },
+  { agent: "trae-cn", base: "home", sub: ".trae-cn/skills" },
+  { agent: "warp", base: "home", sub: ".agents/skills" },
+  { agent: "windsurf", base: "home", sub: ".codeium/windsurf/skills" },
+  { agent: "zed", base: "home", sub: ".agents/skills" },
+  { agent: "zencoder", base: "home", sub: ".zencoder/skills" },
+  { agent: "zenflow", base: "home", sub: ".zencoder/skills" },
+  { agent: "neovate", base: "home", sub: ".neovate/skills" },
+  { agent: "pochi", base: "home", sub: ".pochi/skills" },
+  { agent: "adal", base: "home", sub: ".adal/skills" },
+  { agent: "universal", base: "configHome", sub: "agents/skills" },
+];
@@ -191,18 +191,21 @@ describe("checkSkills install detection", () => {
    expect(res.agent).toBe(agent);
  });

-  it("prefers project scope over global, regardless of convention order", async () => {
+  it("prefers global scope over project (matches how agents load skills)", async () => {
    const project = join(root, "project");
    const home = join(root, "home");
    mkdirSync(project, { recursive: true });
    mkdirSync(home, { recursive: true });
    const source = writeManifest(root);
-    installSkill(join(home, ".claude/skills"), "alpha"); // global, higher-priority host
-    installSkill(join(project, ".hermes/skills"), "alpha"); // project, lower-priority host
+    installSkill(join(home, ".claude/skills"), "alpha"); // global — what the agent actually loads
+    installSkill(join(project, ".hermes/skills"), "alpha"); // project — overridden by the global copy

+    // Claude Code (and most agents) give the personal/global scope priority over
+    // the project scope, and HyperFrames installs globally — so check reports on
+    // the global copy the agent will really use, not a stale project copy.
    const res = await checkSkills({ source, cwd: project, home });
-    expect(res.location).toBe(join(project, ".hermes/skills"));
-    expect(res.agent).toBe("hermes");
+    expect(res.location).toBe(join(home, ".claude/skills"));
+    expect(res.agent).toBe("claude-code");
  });

  it("reports no location and an available update when nothing is installed", async () => {
@@ -252,7 +252,13 @@ function scopeForDir(dir: string, home: string, cwd: string): "project" | "globa
 * Find the first skill root that actually contains HyperFrames skills. A
 * `--dir` override (if given) is treated as a `.../skills` directory directly;
 * its scope is inferred (see scopeForDir) so removed-detection reads the right
- * lock. Otherwise scan project (cwd) then global ($HOME), auto-discovering hosts.
+ * lock. Otherwise scan global ($HOME) then project (cwd), auto-discovering hosts.
+ *
+ * Global is checked FIRST to match how agents actually load skills: Claude Code
+ * (and most others) give the personal/global scope priority over the project
+ * scope, and HyperFrames now installs globally. Checking global-first means
+ * `check` reports on the copy the agent will really use — not a stale project
+ * copy that a newer global install silently overrides.
 */
 function locateInstall(
  skillNames: string[],
@@ -268,8 +274,8 @@ function locateInstall(
      : null;
  }
  const roots = [
-    ...discoverSkillRoots(opts.cwd ?? process.cwd(), "project"),
    ...discoverSkillRoots(opts.home ?? homedir(), "global"),
+    ...discoverSkillRoots(opts.cwd ?? process.cwd(), "project"),
  ];
  for (const root of roots) {
    if (skillNames.some((n) => existsSync(join(root.dir, n, "SKILL.md")))) return root;
@@ -400,6 +406,22 @@ function readSkillLock(path: string): SkillLock | null {
  }
 }

+/**
+ * The skill names the upstream lock attributes to HyperFrames, for a scope.
+ * The mirror MUST scope by this — never by listing `~/.claude/skills`, which is
+ * shared across sources, so a directory listing would fan a user's gstack /
+ * personal / company skills out to every agent. Same source-attribution the
+ * prune uses. Empty when the lock is absent (we can't attribute → mirror none).
+ */
+export function hyperframesSkillNames(opts: {
+  scope: "project" | "global";
+  cwd?: string;
+  home?: string;
+}): string[] {
+  const lockPath = lockPathForScope(opts.scope, { cwd: opts.cwd, home: opts.home });
+  return skillsAttributedToSource(readSkillLock(lockPath), DEFAULT_REPO_SLUG);
+}
+
 interface RemovedResult {
  removed: SkillDiff[];
  /** The lock was absent at the expected path — removed-detection silently no-ops. */
@@ -0,0 +1,218 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readlinkSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { mirrorGlobalSkills } from "./skillsMirror.js";
+import { AGENT_GLOBAL_DIRS } from "./agentDirs.generated.js";
+
+const tmpDirs: string[] = [];
+
+// Resolve agent dirs under the isolated HOME with default (unset) env, so the
+// dev machine's real XDG_CONFIG_HOME / CODEX_HOME never leak into the test.
+const ENV: NodeJS.ProcessEnv = {};
+
+function makeHome(): string {
+  const home = mkdtempSync(join(tmpdir(), "mirror-home-"));
+  tmpDirs.push(home);
+  return home;
+}
+
+/** Seed real skill bundles under ~/.claude/skills (the canonical global store). */
+function seedStore(home: string, skills: string[]): void {
+  for (const name of skills) {
+    const dir = join(home, ".claude", "skills", name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "SKILL.md"), `# ${name}\n`, "utf8");
+  }
+}
+
+/** Pretend an agent is installed by creating its marker dir. */
+function installMarker(home: string, marker: string): void {
+  mkdirSync(join(home, ...marker.split("/")), { recursive: true });
+}
+
+afterEach(() => {
+  for (const d of tmpDirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+describe("mirrorGlobalSkills", () => {
+  it("no-ops when there is no global Claude store", () => {
+    const home = makeHome();
+    const result = mirrorGlobalSkills({
+      skills: ["hyperframes"],
+      home,
+      platform: "linux",
+      env: ENV,
+    });
+    expect(result.source).toBeNull();
+    expect(result.mirrored).toEqual([]);
+  });
+
+  it("mirrors the store into installed agents as relative symlinks (Unix)", () => {
+    const home = makeHome();
+    seedStore(home, ["hyperframes", "hyperframes-core"]);
+    installMarker(home, ".cursor"); // cursor present
+    installMarker(home, ".config/goose"); // goose present (XDG base)
+    // windsurf NOT installed (no ~/.codeium/windsurf)
+
+    const { mirrored } = mirrorGlobalSkills({
+      skills: ["hyperframes", "hyperframes-core"],
+      home,
+      platform: "linux",
+      env: ENV,
+    });
+    const agents = mirrored.map((m) => m.agent);
+    expect(agents).toContain("cursor");
+    expect(agents).toContain("goose");
+    expect(agents).not.toContain("windsurf");
+
+    const link = join(home, ".cursor", "skills", "hyperframes");
+    expect(lstatSync(link).isSymbolicLink()).toBe(true);
+    expect(isAbsolute(readlinkSync(link))).toBe(false); // relative target
+    expect(realpathSync(link)).toBe(realpathSync(join(home, ".claude", "skills", "hyperframes")));
+    expect(existsSync(join(link, "SKILL.md"))).toBe(true);
+
+    // goose lands in the XDG config dir (~/.config/goose), not ~/.goose
+    expect(
+      existsSync(join(home, ".config", "goose", "skills", "hyperframes-core", "SKILL.md")),
+    ).toBe(true);
+  });
+
+  // The blocker Magi flagged: ~/.claude/skills is shared, so a user's gstack /
+  // personal / company skills live there too. The mirror must fan out ONLY
+  // HyperFrames' own skills (the lock-attributed allow-list), never everything
+  // in the store — and must not remove/replace a same-named skill already in
+  // another agent's dir.
+  it("only mirrors the allow-listed skills, never other sources' (gstack)", () => {
+    const home = makeHome();
+    seedStore(home, ["hyperframes", "gstack"]); // gstack is a foreign skill in the store
+    installMarker(home, ".cursor");
+    // cursor already has its OWN gstack skill from another source — must survive.
+    const foreign = join(home, ".cursor", "skills", "gstack");
+    mkdirSync(foreign, { recursive: true });
+    writeFileSync(join(foreign, "SKILL.md"), "# gstack (cursor's own, not ours)\n", "utf8");
+
+    mirrorGlobalSkills({ skills: ["hyperframes"], home, platform: "linux", env: ENV });
+
+    // our skill got linked
+    expect(lstatSync(join(home, ".cursor", "skills", "hyperframes")).isSymbolicLink()).toBe(true);
+    // gstack was NOT mirrored from the store...
+    expect(existsSync(join(home, ".claude", "skills", "gstack"))).toBe(true); // still in store
+    // ...and cursor's pre-existing gstack was neither replaced with a symlink nor removed
+    expect(lstatSync(foreign).isSymbolicLink()).toBe(false);
+    expect(readFileSync(join(foreign, "SKILL.md"), "utf8")).toContain("cursor's own");
+  });
+
+  it("honors XDG_CONFIG_HOME for config-based agents", () => {
+    const home = makeHome();
+    const xdg = makeHome(); // a separate absolute XDG config root
+    seedStore(home, ["hyperframes"]);
+    mkdirSync(join(xdg, "goose"), { recursive: true }); // goose marker under XDG
+
+    const { mirrored } = mirrorGlobalSkills({
+      skills: ["hyperframes"],
+      home,
+      platform: "linux",
+      env: { XDG_CONFIG_HOME: xdg },
+    });
+    expect(mirrored.map((m) => m.agent)).toContain("goose");
+    expect(existsSync(join(xdg, "goose", "skills", "hyperframes", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(home, ".config", "goose", "skills"))).toBe(false);
+  });
+
+  it("copies instead of symlinking on Windows", () => {
+    const home = makeHome();
+    seedStore(home, ["hyperframes"]);
+    installMarker(home, ".cursor");
+
+    mirrorGlobalSkills({ skills: ["hyperframes"], home, platform: "win32", env: ENV });
+    const target = join(home, ".cursor", "skills", "hyperframes");
+    expect(lstatSync(target).isSymbolicLink()).toBe(false);
+    expect(lstatSync(target).isDirectory()).toBe(true);
+    expect(existsSync(join(target, "SKILL.md"))).toBe(true);
+  });
+
+  it("never mirrors onto the install-owned stores (.claude / .agents)", () => {
+    const home = makeHome();
+    seedStore(home, ["hyperframes"]);
+    installMarker(home, ".agents"); // .agents present (the universal install creates it)
+
+    const { mirrored } = mirrorGlobalSkills({
+      skills: ["hyperframes"],
+      home,
+      platform: "linux",
+      env: ENV,
+    });
+    expect(mirrored.map((m) => m.agent)).not.toContain("claude-code");
+    // the .agents-family agents (cline/dexto/…) map to .agents/skills and are skipped
+    expect(mirrored.map((m) => m.agent)).not.toContain("cline");
+    // ~/.agents/skills is the real universal store — must stay untouched (no link created)
+    expect(existsSync(join(home, ".agents", "skills"))).toBe(false);
+  });
+
+  it("is idempotent and refreshes stale entries", () => {
+    const home = makeHome();
+    seedStore(home, ["hyperframes"]);
+    installMarker(home, ".cursor");
+
+    mirrorGlobalSkills({ skills: ["hyperframes"], home, platform: "linux", env: ENV });
+    // second run must not throw and must leave a valid link
+    const { mirrored } = mirrorGlobalSkills({
+      skills: ["hyperframes"],
+      home,
+      platform: "linux",
+      env: ENV,
+    });
+    expect(mirrored.map((m) => m.agent)).toContain("cursor");
+    const link = join(home, ".cursor", "skills", "hyperframes");
+    expect(realpathSync(link)).toBe(realpathSync(join(home, ".claude", "skills", "hyperframes")));
+  });
+});
+
+describe("AGENT_GLOBAL_DIRS (generated table)", () => {
+  it("is a non-trivial, well-formed table", () => {
+    const validBases = new Set([
+      "home",
+      "configHome",
+      "codexHome",
+      "claudeHome",
+      "vibeHome",
+      "hermesHome",
+      "autohandHome",
+    ]);
+    expect(AGENT_GLOBAL_DIRS.length).toBeGreaterThan(50);
+    for (const e of AGENT_GLOBAL_DIRS) {
+      expect(validBases.has(e.base)).toBe(true);
+      expect(e.sub.endsWith("skills")).toBe(true);
+      expect(e.sub.startsWith("/")).toBe(false); // a suffix, not an absolute path
+    }
+  });
+
+  it("covers the major agents at their real bases", () => {
+    const byAgent = new Map(AGENT_GLOBAL_DIRS.map((e) => [e.agent, e]));
+    expect(byAgent.get("claude-code")).toMatchObject({ base: "claudeHome", sub: "skills" });
+    expect(byAgent.get("cursor")).toMatchObject({ base: "home", sub: ".cursor/skills" });
+    expect(byAgent.get("codex")).toMatchObject({ base: "codexHome", sub: "skills" });
+    expect(byAgent.get("goose")).toMatchObject({ base: "configHome", sub: "goose/skills" });
+    expect(byAgent.get("windsurf")).toMatchObject({
+      base: "home",
+      sub: ".codeium/windsurf/skills",
+    });
+    expect(byAgent.get("droid")).toMatchObject({ base: "home", sub: ".factory/skills" });
+    // bare-dir-in-project agents become namespaced globally (no footgun)
+    expect(byAgent.get("openclaw")).toMatchObject({ base: "home", sub: ".openclaw/skills" });
+    // agents with no upstream global dir are omitted
+    expect(byAgent.has("eve")).toBe(false);
+    expect(byAgent.has("promptscript")).toBe(false);
+  });
+});
@@ -0,0 +1,135 @@
+// Fan the canonical global skills store out to every OTHER installed agent.
+//
+// `skills add --global --agent claude-code universal --copy` writes REAL files
+// to two global stores: the Claude store (~/.claude/skills — what Claude Code
+// reads, at global priority) and the shared universal store (~/.agents/skills,
+// which Cursor/Codex/… read in PROJECT scope and the .agents-family agents read
+// globally). But every other agent reads its OWN global dir (~/.cursor/skills,
+// goose → ~/.config/goose/skills, …), which upstream's --global does NOT
+// populate.
+//
+// So we mirror the canonical Claude store into each of those per-agent dirs, but
+// only for agents the machine actually has (their marker dir exists). On Unix
+// each skill is a relative symlink back into the store (one source of truth,
+// near-zero size, auto-fresh on update); on Windows it's a copy, because
+// symlinks there need admin / Developer Mode and otherwise silently dangle —
+// the same fallback the upstream `skills` CLI and gstack both make.
+//
+// Agent dirs are resolved through the same env-overridable base dirs upstream
+// uses (XDG_CONFIG_HOME, CODEX_HOME, CLAUDE_CONFIG_DIR, …), so a machine with
+// those set mirrors into the exact dir the agent reads.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { AGENT_GLOBAL_DIRS, type AgentDirBase } from "./agentDirs.generated.js";
+
+export interface MirrorResult {
+  /** The store mirrored from, or null when no global Claude store was found. */
+  source: string | null;
+  /** Agents whose global dir was (re)populated. */
+  mirrored: { agent: string; dir: string }[];
+}
+
+/** Resolve each env-overridable base dir exactly as upstream agents.ts does. */
+function resolveBases(home: string, env: NodeJS.ProcessEnv): Record<AgentDirBase, string> {
+  const xdg = env["XDG_CONFIG_HOME"]?.trim();
+  return {
+    home,
+    configHome: xdg && isAbsolute(xdg) ? xdg : join(home, ".config"),
+    codexHome: env["CODEX_HOME"]?.trim() || join(home, ".codex"),
+    claudeHome: env["CLAUDE_CONFIG_DIR"]?.trim() || join(home, ".claude"),
+    vibeHome: env["VIBE_HOME"]?.trim() || join(home, ".vibe"),
+    hermesHome: env["HERMES_HOME"]?.trim() || join(home, ".hermes"),
+    autohandHome: env["AUTOHAND_HOME"]?.trim() || join(home, ".autohand"),
+  };
+}
+
+/** Skill bundle names directly under a store (a dir/symlink with a SKILL.md). */
+function listSkillDirs(store: string): string[] {
+  return readdirSync(store, { withFileTypes: true })
+    .filter(
+      (e) => (e.isDirectory() || e.isSymbolicLink()) && existsSync(join(store, e.name, "SKILL.md")),
+    )
+    .map((e) => e.name);
+}
+
+/**
+ * Point `targetSkill` at `sourceSkill`. Any prior entry (our symlink, a stale
+ * copy, or a previous install) is removed first so the mirror always reflects
+ * the canonical store — that's the whole point of "update".
+ */
+function linkOrCopy(sourceSkill: string, targetSkill: string, platform: NodeJS.Platform): void {
+  rmSync(targetSkill, { recursive: true, force: true });
+  if (platform === "win32") {
+    cpSync(sourceSkill, targetSkill, { recursive: true });
+  } else {
+    symlinkSync(relative(dirname(targetSkill), sourceSkill), targetSkill);
+  }
+}
+
+/**
+ * Populate one agent's global dir from the store. Best-effort and idempotent;
+ * per-skill failures don't abort the others. Returns false if the dir couldn't
+ * be created at all.
+ */
+function mirrorInto(
+  targetDir: string,
+  source: string,
+  skills: string[],
+  platform: NodeJS.Platform,
+): boolean {
+  try {
+    mkdirSync(targetDir, { recursive: true });
+  } catch {
+    return false;
+  }
+  for (const skill of skills) {
+    try {
+      linkOrCopy(join(source, skill), join(targetDir, skill), platform);
+    } catch {
+      // best-effort per skill
+    }
+  }
+  return true;
+}
+
+/**
+ * Mirror the global Claude store into every installed agent's global skills
+ * dir. Best-effort and idempotent: a no-op when the store is absent, and per
+ * skill failures (permissions, races) don't abort the rest.
+ */
+export function mirrorGlobalSkills(opts: {
+  skills: readonly string[];
+  home?: string;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+}): MirrorResult {
+  const home = opts.home ?? homedir();
+  const platform = opts.platform ?? process.platform;
+  const bases = resolveBases(home, opts.env ?? process.env);
+
+  // The two stores the global --copy install writes as real files. The mirror
+  // reads from the Claude store and must never link/copy onto either of them.
+  const source = join(bases.claudeHome, "skills");
+  const universalStore = join(home, ".agents", "skills");
+  if (!existsSync(source)) return { source: null, mirrored: [] };
+
+  // Mirror ONLY HyperFrames' own skills (by name), NEVER everything in the
+  // store: ~/.claude/skills is shared, so a user's gstack / personal / company
+  // skills live there too and must not be fanned out to (or overwrite) other
+  // agents. `opts.skills` is the lock-attributed HyperFrames set (see
+  // hyperframesSkillNames).
+  const allowed = new Set(opts.skills);
+  const skills = listSkillDirs(source).filter((name) => allowed.has(name));
+  if (skills.length === 0) return { source, mirrored: [] };
+
+  const mirrored: { agent: string; dir: string }[] = [];
+  for (const { agent, base, sub } of AGENT_GLOBAL_DIRS) {
+    const targetDir = join(bases[base], ...sub.split("/").filter(Boolean));
+    if (targetDir === source || targetDir === universalStore) continue; // install-owned
+    if (!existsSync(dirname(targetDir))) continue; // agent not installed (no marker)
+    if (mirrorInto(targetDir, source, skills, platform)) mirrored.push({ agent, dir: targetDir });
+  }
+  return { source, mirrored };
+}
@@ -1,130 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { buildSkillsAddArgs, resolveAgentTargets } from "./skillsTargets.js";
-
-const tmpDirs: string[] = [];
-
-function tempDir(prefix: string): string {
-  const dir = mkdtempSync(join(tmpdir(), prefix));
-  tmpDirs.push(dir);
-  return dir;
-}
-
-/** A project root containing the given `<host>/skills` folders. */
-function projectWith(...hostDirs: string[]): string {
-  const root = tempDir("hf-targets-proj-");
-  for (const host of hostDirs) mkdirSync(join(root, host, "skills"), { recursive: true });
-  return root;
-}
-
-/** A PATH-style string pointing at a dir that contains the given fake executables. */
-function pathWith(...bins: string[]): string {
-  const dir = tempDir("hf-targets-bin-");
-  for (const bin of bins) writeFileSync(join(dir, bin), "");
-  return dir;
-}
-
-afterEach(() => {
-  for (const dir of tmpDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
-});
-
-describe("resolveAgentTargets", () => {
-  const blank = { env: {}, pathStr: "", platform: "linux" as const };
-
-  // ── 1. Existing project folders win, mapped dir → upstream key ──────────────
-
-  it("honours an existing `.hermes/skills` folder, nothing else", () => {
-    const result = resolveAgentTargets({ ...blank, cwd: projectWith(".hermes") });
-    expect(result.agents).toEqual(["hermes-agent"]);
-  });
-
-  it("maps `.factory` → droid and `.kiro` → kiro-cli (dir names differ from keys)", () => {
-    const result = resolveAgentTargets({ ...blank, cwd: projectWith(".factory", ".kiro") });
-    expect(result.agents).toEqual(["droid", "kiro-cli"]);
-  });
-
-  it("maps the shared `.agents` dir to the single `universal` key", () => {
-    const result = resolveAgentTargets({ ...blank, cwd: projectWith(".agents") });
-    expect(result.agents).toEqual(["universal"]);
-  });
-
-  it("returns claude-code first across multiple existing folders", () => {
-    const result = resolveAgentTargets({ ...blank, cwd: projectWith(".agents", ".claude") });
-    expect(result.agents).toEqual(["claude-code", "universal"]);
-  });
-
-  it("existing folders take precedence over CLAUDECODE and PATH", () => {
-    const result = resolveAgentTargets({
-      cwd: projectWith(".hermes"),
-      env: { CLAUDECODE: "1" },
-      pathStr: pathWith("claude", "cursor"),
-      platform: "linux",
-    });
-    expect(result.agents).toEqual(["hermes-agent"]);
-  });
-
-  // ── 2a. Claude Code env on a blank project ──────────────────────────────────
-
-  it("targets just claude-code when running under Claude Code", () => {
-    const result = resolveAgentTargets({
-      ...blank,
-      cwd: projectWith(),
-      env: { CLAUDECODE: "1" },
-    });
-    expect(result.agents).toEqual(["claude-code"]);
-  });
-
-  // ── 2b. gstack route: installed agent CLIs on PATH ──────────────────────────
-
-  it("detects installed agent CLIs on PATH (blank project, no CLAUDECODE)", () => {
-    const result = resolveAgentTargets({
-      cwd: projectWith(),
-      env: {},
-      pathStr: pathWith("claude", "hermes"),
-      platform: "linux",
-    });
-    expect(result.agents).toEqual(["claude-code", "hermes-agent"]);
-  });
-
-  it("collapses universal-bucket CLIs (cursor/codex/…) to a single `universal`", () => {
-    const result = resolveAgentTargets({
-      cwd: projectWith(),
-      env: {},
-      pathStr: pathWith("cursor", "codex", "gemini"),
-      platform: "linux",
-    });
-    expect(result.agents).toEqual(["universal"]);
-  });
-
-  // ── 2c. Floor ───────────────────────────────────────────────────────────────
-
-  it("falls back to claude-code + universal (.claude + .agents) when nothing is found", () => {
-    const result = resolveAgentTargets({ ...blank, cwd: projectWith() });
-    expect(result.agents).toEqual(["claude-code", "universal"]);
-  });
-
-  // ── Invariant: never the `--all` spray ──────────────────────────────────────
-
-  it("never returns the `'*'` wildcard agent", () => {
-    for (const cwd of [projectWith(), projectWith(".hermes"), projectWith(".claude")]) {
-      const result = resolveAgentTargets({ ...blank, cwd });
-      expect(result.agents).not.toContain("*");
-      expect(result.agents.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-describe("buildSkillsAddArgs", () => {
-  it("installs every skill to the given agents, non-interactive — not `--all`", () => {
-    expect(buildSkillsAddArgs(["claude-code", "universal"])).toEqual([
-      "--skill",
-      "*",
-      "--agent",
-      "claude-code",
-      "universal",
-      "--yes",
-    ]);
-  });
-});
@@ -1,158 +0,0 @@
-// Decide WHICH agents a `skills add` should install to, so HyperFrames never
-// sprays its skills into every one of the ~70 agent conventions the upstream
-// `skills` CLI knows about (its `--all` is shorthand for `--agent '*'`).
-//
-// The policy, in priority order:
-//   1. If the project already has agent skill folders (`.claude/skills`,
-//      `.hermes/skills`, …), install ONLY to those. An existing folder is the
-//      strongest signal of intent — honour it exactly, add nothing else.
-//   2. Otherwise (blank project), pick targets from the machine:
-//      2a. Running under Claude Code (`CLAUDECODE`) → just claude-code.
-//      2b. Else probe the PATH for installed agent CLIs (the gstack approach:
-//          an executable on PATH means that agent is actually installed here).
-//      2c. Else fall back to the floor: claude-code + the shared `.agents`
-//          universal dir (which Cursor, Codex, OpenCode, Gemini, Copilot and a
-//          dozen others read from in project scope).
-//
-// All paths are PROJECT-scoped (the default for `skills add` without `--global`),
-// which is why the dir map below is the project-scope layout.
-
-import { existsSync, statSync } from "node:fs";
-import { delimiter, join } from "node:path";
-
-/**
- * Project-scope host directory → the upstream `skills` `--agent` key that
- * installs into it. The dir name deliberately differs from the key for several
- * agents (`.factory` ↔ `droid`, `.hermes` ↔ `hermes-agent`), and many agents
- * share the `.agents` universal dir, so the mapping is explicit rather than
- * derived. Keys verified against vercel-labs/skills@v1.5.13.
- */
-const DIR_TO_KEY: Readonly<Record<string, string>> = {
-  ".claude": "claude-code",
-  ".agents": "universal",
-  ".hermes": "hermes-agent",
-  ".factory": "droid",
-  ".kiro": "kiro-cli",
-};
-
-/**
- * Agent CLIs we probe for on PATH, paired with the project-scope host dir each
- * installs into. Several (Cursor, Codex, OpenCode, Gemini) share `.agents`, so
- * detecting any of them resolves — via DIR_TO_KEY — to the single `universal`
- * key and one write to `.agents/skills`. OpenClaw is intentionally absent: its
- * project skills dir is a bare `skills/`, which collides with common project
- * layouts, so we never auto-target it (an existing folder or explicit `--agent`
- * still works upstream).
- */
-const DETECTABLE: ReadonlyArray<{ bin: string; dir: string }> = [
-  { bin: "claude", dir: ".claude" },
-  { bin: "hermes", dir: ".hermes" },
-  { bin: "droid", dir: ".factory" },
-  { bin: "cursor", dir: ".agents" },
-  { bin: "codex", dir: ".agents" },
-  { bin: "opencode", dir: ".agents" },
-  { bin: "gemini", dir: ".agents" },
-];
-
-export interface ResolveTargetsInput {
-  /** Project root the install targets (cwd, or the init destination). */
-  cwd: string;
-  /** Process env — read for the `CLAUDECODE` signal. */
-  env: NodeJS.ProcessEnv;
-  /** PATH string for the on-PATH binary probe. */
-  pathStr: string;
-  /** Platform — selects the executable extensions probed on Windows. */
-  platform: NodeJS.Platform;
-}
-
-export interface ResolvedTargets {
-  /** Upstream `--agent` keys to install to (never `'*'`). */
-  agents: string[];
-  /** Short human-readable explanation of why these were chosen. */
-  reason: string;
-}
-
-function isDir(path: string): boolean {
-  try {
-    return existsSync(path) && statSync(path).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-/** True if `bin` resolves on any PATH entry (Windows also tries .exe/.cmd/.bat). */
-function isOnPath(bin: string, pathStr: string, platform: NodeJS.Platform): boolean {
-  const exts = platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
-  for (const dir of pathStr.split(delimiter)) {
-    if (!dir) continue;
-    for (const ext of exts) {
-      try {
-        if (existsSync(join(dir, bin + ext))) return true;
-      } catch {
-        // Unreadable PATH entry — skip it.
-      }
-    }
-  }
-  return false;
-}
-
-/** Map a set of host dirs to deduped `--agent` keys, claude-code first (DIR_TO_KEY order). */
-function keysForDirs(dirs: ReadonlySet<string>): string[] {
-  return Object.entries(DIR_TO_KEY)
-    .filter(([dir]) => dirs.has(dir))
-    .map(([, key]) => key);
-}
-
-/** Agent skill folders that already exist under the project root. */
-function existingProjectAgents(cwd: string): string[] {
-  const dirs = new Set<string>();
-  for (const dir of Object.keys(DIR_TO_KEY)) {
-    if (isDir(join(cwd, dir, "skills"))) dirs.add(dir);
-  }
-  return keysForDirs(dirs);
-}
-
-/** Agent CLIs installed on this machine (by PATH probe), as `--agent` keys. */
-function detectInstalledAgents(pathStr: string, platform: NodeJS.Platform): string[] {
-  const dirs = new Set<string>();
-  for (const { bin, dir } of DETECTABLE) {
-    if (isOnPath(bin, pathStr, platform)) dirs.add(dir);
-  }
-  return keysForDirs(dirs);
-}
-
-/**
- * Resolve the `--agent` targets for an install. See the file header for the
- * full policy. Pure: all inputs are passed in, so it is fully unit-testable.
- */
-export function resolveAgentTargets(input: ResolveTargetsInput): ResolvedTargets {
-  // 1. Honour what the project already has — nothing more.
-  const existing = existingProjectAgents(input.cwd);
-  if (existing.length > 0) {
-    return { agents: existing, reason: `existing project skill folders (${existing.join(", ")})` };
-  }
-
-  // 2a. Strongest live signal: the agent running this command.
-  if (input.env["CLAUDECODE"]) {
-    return { agents: ["claude-code"], reason: "running under Claude Code" };
-  }
-
-  // 2b. gstack approach: agent CLIs actually installed on this machine.
-  const detected = detectInstalledAgents(input.pathStr, input.platform);
-  if (detected.length > 0) {
-    return { agents: detected, reason: `installed agent CLIs (${detected.join(", ")})` };
-  }
-
-  // 2c. Floor: Claude Code + the shared `.agents` universal dir. Never `--agent '*'`.
-  return { agents: ["claude-code", "universal"], reason: "default (.claude + .agents)" };
-}
-
-/**
- * Build the `skills add` arguments for a resolved target set: every skill
- * (`--skill '*'`) to the chosen agents only, non-interactive. This replaces the
- * upstream `--all` (= `--skill '*' --agent '*' -y`) so the agent fan-out is
- * scoped instead of universal.
- */
-export function buildSkillsAddArgs(agents: string[]): string[] {
-  return ["--skill", "*", "--agent", ...agents, "--yes"];
-}