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 04:38:33 +00:00 · 2026-06-27 08:34:43 +08:00
parent e3edbd55cf
commit bf961d1268
23 changed files with 812 additions and 410 deletions
@@ -23,7 +23,8 @@
    "build:beat-analyzer": "node scripts/build-beat-analyzer.mjs",
    "build:copy": "node scripts/build-copy.mjs",
    "typecheck": "tsc --noEmit",
-    "gen:skills-manifest": "tsx scripts/gen-skills-manifest.ts"
+    "gen:skills-manifest": "tsx scripts/gen-skills-manifest.ts",
+    "gen:agent-dirs": "tsx scripts/sync-agent-dirs.ts"
  },
  "dependencies": {
    "@hono/node-server": "^1.8.0",
@@ -0,0 +1,169 @@
+// Generate (or verify) packages/cli/src/utils/agentDirs.generated.ts — the
+// home-relative GLOBAL skills directory for every agent the upstream
+// vercel-labs/skills CLI knows about, plus a marker dir that means "this agent
+// is installed on this machine".
+//
+//   bun run --cwd packages/cli gen:agent-dirs           # write/update (fetches upstream)
+//   bun run --cwd packages/cli gen:agent-dirs --check   # verify only (CI / pre-commit)
+//   bun packages/cli/scripts/sync-agent-dirs.ts --src <path/to/agents.ts>   # offline
+//
+// Why generated, not hand-maintained: `skills add --global` installs into the
+// per-agent dirs encoded in upstream's `src/agents.ts` (~70 agents). We mirror
+// the canonical store into those same dirs, so the list must track upstream. The
+// `skills` npm package exports nothing importable (CLI-only, bundled dist), so
+// we parse the source at a PINNED tag and commit the result — deterministic at
+// runtime, no network at install time. Bump SKILLS_REF and re-run on upgrade.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Pin to the upstream release whose dir layout we install against. Bump this
+// (and re-run) when the bundled `skills` version moves.
+const SKILLS_REPO = "vercel-labs/skills";
+const SKILLS_REF = "v1.5.13";
+const AGENTS_TS_URL = `https://raw.githubusercontent.com/${SKILLS_REPO}/${SKILLS_REF}/src/agents.ts`;
+
+const here = dirname(fileURLToPath(import.meta.url));
+const outPath = join(here, "..", "src", "utils", "agentDirs.generated.ts");
+
+const isCheck = process.argv.includes("--check");
+const srcFlag = process.argv.indexOf("--src");
+const srcPath = srcFlag !== -1 ? process.argv[srcFlag + 1] : undefined;
+
+// The base directories agents.ts builds globalSkillsDir from. Each is an env
+// override with a documented default — the mirror resolves them at runtime so a
+// machine with XDG_CONFIG_HOME / CODEX_HOME / CLAUDE_CONFIG_DIR set lands in the
+// same place the agent actually reads. We store the base NAME + suffix here
+// rather than a frozen path so that resolution stays faithful to upstream.
+const BASE_VARS = [
+  "home",
+  "configHome",
+  "codexHome",
+  "claudeHome",
+  "vibeHome",
+  "hermesHome",
+  "autohandHome",
+] as const;
+type BaseVar = (typeof BASE_VARS)[number];
+
+interface AgentGlobalDir {
+  agent: string;
+  base: BaseVar;
+  sub: string;
+}
+
+function posixJoin(parts: string[]): string {
+  return parts
+    .flatMap((p) => p.split("/"))
+    .filter((s) => s && s !== ".")
+    .join("/");
+}
+
+/** Resolve a globalSkillsDir expression to { base, sub }, or null if none. */
+function resolveGlobalExpr(expr: string): { base: BaseVar; sub: string } | null {
+  const e = expr.trim();
+  if (e === "undefined") return null; // agent defines no global skills dir
+  // openclaw's helper falls back to ~/.openclaw/skills when no variant is present.
+  if (e.startsWith("getOpenClawGlobalSkillsDir")) return { base: "home", sub: ".openclaw/skills" };
+  const m = e.match(/^join\(([\s\S]+)\)$/);
+  if (!m) throw new Error(`Unparseable globalSkillsDir: ${expr}`);
+  const args = m[1]!.split(",").map((a) => a.trim());
+  const first = args[0]!;
+  if (!(BASE_VARS as readonly string[]).includes(first)) {
+    throw new Error(`globalSkillsDir does not start with a known base var: ${expr}`);
+  }
+  const segs: string[] = [];
+  for (const raw of args.slice(1)) {
+    const lit = raw.match(/^['"]([^'"]*)['"]$/);
+    if (!lit) throw new Error(`Non-literal segment "${raw}" in globalSkillsDir: ${expr}`);
+    segs.push(lit[1]!);
+  }
+  return { base: first as BaseVar, sub: posixJoin(segs) };
+}
+
+function parseAgents(source: string): AgentGlobalDir[] {
+  const re = /^ {2}(?:"([a-z0-9-]+)"|'([a-z0-9-]+)'|([a-z0-9-]+)):\s*\{/gm;
+  const blocks: { key: string; pos: number }[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source))) blocks.push({ key: m[1] || m[2] || m[3]!, pos: m.index });
+  if (blocks.length < 60) {
+    throw new Error(`Parsed only ${blocks.length} agent blocks — upstream layout likely changed`);
+  }
+
+  const out: AgentGlobalDir[] = [];
+  for (let i = 0; i < blocks.length; i++) {
+    const seg = source.slice(blocks[i]!.pos, blocks[i + 1] ? blocks[i + 1]!.pos : source.length);
+    const gd = seg.match(/globalSkillsDir:\s*([\s\S]+?),\n/);
+    const expr = gd ? gd[1]!.trim().replace(/\s+/g, " ") : "undefined";
+    const resolved = resolveGlobalExpr(expr);
+    if (resolved === null) continue; // no global dir (e.g. eve, promptscript)
+    out.push({ agent: blocks[i]!.key, base: resolved.base, sub: resolved.sub });
+  }
+  return out;
+}
+
+function render(rows: AgentGlobalDir[]): string {
+  const lines = rows.map(
+    (r) =>
+      `  { agent: ${JSON.stringify(r.agent)}, base: ${JSON.stringify(r.base)}, sub: ${JSON.stringify(r.sub)} },`,
+  );
+  return `// @generated by packages/cli/scripts/sync-agent-dirs.ts — DO NOT EDIT.
+// Source: ${SKILLS_REPO}@${SKILLS_REF} (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 =
+${BASE_VARS.map((b) => `  | ${JSON.stringify(b)}`).join("\n")};
+
+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[] = [
+${lines.join("\n")}
+];
+`;
+}
+
+async function loadAgentsSource(): Promise<string> {
+  if (srcPath) return readFileSync(srcPath, "utf8");
+  const res = await fetch(AGENTS_TS_URL);
+  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${AGENTS_TS_URL}`);
+  return res.text();
+}
+
+const source = await loadAgentsSource();
+const rows = parseAgents(source);
+const next = render(rows);
+
+if (isCheck) {
+  let current = "";
+  try {
+    current = readFileSync(outPath, "utf8");
+  } catch {
+    /* missing → drift */
+  }
+  if (current !== next) {
+    console.error(
+      `agentDirs.generated.ts is out of date (parsed ${rows.length} agents from ${SKILLS_REPO}@${SKILLS_REF}).\n` +
+        `Run: bun run --cwd packages/cli gen:agent-dirs`,
+    );
+    process.exit(1);
+  }
+  console.log(`agentDirs.generated.ts is up to date (${rows.length} agents).`);
+} else {
+  writeFileSync(outPath, next, "utf8");
+  console.log(`Wrote ${rows.length} agents → ${outPath}`);
+}
@@ -574,12 +574,14 @@ async function scaffoldProject(
 }

 /**
- * Ensure the project's AI coding skills are present and current. Checks the
- * installed skills against the latest published on GitHub and only (re)installs
- * when something is outdated or missing — so re-running `init` on an already
- * up-to-date project is a no-op. Best-effort: if the version check can't reach
- * GitHub, it installs anyway. The install itself (`installAllSkills`) pulls the
- * full set straight from the GitHub repo.
+ * Ensure the AI coding skills are present and current. Checks the installed
+ * skills against the latest published on GitHub and only (re)installs when
+ * something is outdated or missing — so re-running `init` on an up-to-date
+ * machine is a no-op. Best-effort: if the version check can't reach GitHub, it
+ * installs anyway. The install itself (`installAllSkills`) installs the full set
+ * once GLOBALLY (~/.claude/skills + ~/.agents/skills) and mirrors it into every
+ * other installed agent, so it is project-independent — the check is global-first
+ * to match.
 */
 async function ensureSkillsCurrent(destDir: string): Promise<void> {
  const { installAllSkills } = await import("./skills.js");
@@ -596,11 +598,9 @@ async function ensureSkillsCurrent(destDir: string): Promise<void> {
  }

  if (needsInstall) {
-    // installAllSkills resolves the agent target set from destDir + the
-    // environment (Claude Code → claude-code; otherwise installed CLIs, else a
-    // Claude-Code + `.agents` floor). A freshly-scaffolded project has no agent
-    // folders yet, so this lands skills where the running agent will read them
-    // rather than spraying to every agent convention.
+    // installAllSkills installs the full set once globally and mirrors it into
+    // every installed agent's global dir — project-independent, so a freshly
+    // scaffolded project doesn't need any agent folders yet.
    await installAllSkills({ cwd: destDir });
  } else {
    console.log(c.success("AI coding skills are already up to date."));
@@ -54,19 +54,31 @@ vi.mock("@clack/prompts", () => ({
 // default returns nothing removed, and the prune test overrides per-call.
 vi.mock("../utils/skillsManifest.js", () => ({
  checkSkills: vi.fn(async () => ({ skills: [] })),
+  // installAllSkills resolves the HyperFrames skill names (lock-attributed) to
+  // scope the mirror; pin it so these arg-shape tests don't read a real lock.
+  hyperframesSkillNames: vi.fn(() => ["hyperframes"]),
 }));

-// Agent-target resolution probes the real cwd / PATH / env, which would make
-// the spawned-args assertions environment-dependent. Pin it to a fixed result
-// so these tests verify how the command BUILDS the spawn, not what's installed
-// on the test host. The resolver's own decision tree is covered in
-// skillsTargets.test.ts. buildSkillsAddArgs is reproduced (it's trivial) so the
-// arg shape under test stays real.
-vi.mock("../utils/skillsTargets.js", () => ({
-  resolveAgentTargets: vi.fn(() => ({ agents: ["claude-code", "universal"], reason: "test" })),
-  buildSkillsAddArgs: (agents: string[]) => ["--skill", "*", "--agent", ...agents, "--yes"],
+// The install fans out to other agents via mirrorGlobalSkills, which touches
+// the real $HOME. Stub it so these arg-shape tests never create symlinks in the
+// dev machine's agent dirs — the mirror has its own isolated-HOME unit tests.
+vi.mock("../utils/skillsMirror.js", () => ({
+  mirrorGlobalSkills: vi.fn(() => ({ source: null, mirrored: [] })),
 }));

+// The global install command this CLI runs (after `skills add <url>`).
+const GLOBAL_ARGS = [
+  "--skill",
+  "*",
+  "--global",
+  "--agent",
+  "claude-code",
+  "universal",
+  "--copy",
+  "--full-depth",
+  "--yes",
+] as const;
+
 function setPlatform(platform: NodeJS.Platform): void {
  Object.defineProperty(process, "platform", {
    value: platform,
@@ -101,7 +113,7 @@ describe("hyperframes skills", () => {
    process.exitCode = prevExitCode;
  });

-  it("sets GIT_CLONE_PROTECTION_ACTIVE=0 on the spawned skills CLI child (GH #316)", async () => {
+  it("sets clone-safe env on the spawned skills CLI child (GH #316 + LFS skip)", async () => {
    setPlatform("linux");

    const { default: skillsCmd } = await import("./skills.js");
@@ -113,6 +125,8 @@ describe("hyperframes skills", () => {
    expect(first!.args).toContain("skills");
    expect(first!.args).toContain("add");
    expect(first!.env?.GIT_CLONE_PROTECTION_ACTIVE).toBe("0");
+    // --full-depth clones the repo; skip LFS so we don't drag in unrelated blobs.
+    expect(first!.env?.GIT_LFS_SKIP_SMUDGE).toBe("1");
  });

  it.each([
@@ -120,35 +134,13 @@ describe("hyperframes skills", () => {
      "linux",
      "npx",
      ["--version"],
-      [
-        "skills",
-        "add",
-        "https://github.com/heygen-com/hyperframes",
-        "--skill",
-        "*",
-        "--agent",
-        "claude-code",
-        "universal",
-        "--yes",
-        "--copy",
-      ],
+      ["skills", "add", "https://github.com/heygen-com/hyperframes", ...GLOBAL_ARGS],
    ],
    [
      "darwin",
      "npx",
      ["--version"],
-      [
-        "skills",
-        "add",
-        "https://github.com/heygen-com/hyperframes",
-        "--skill",
-        "*",
-        "--agent",
-        "claude-code",
-        "universal",
-        "--yes",
-        "--copy",
-      ],
+      ["skills", "add", "https://github.com/heygen-com/hyperframes", ...GLOBAL_ARGS],
    ],
    [
      "win32",
@@ -162,13 +154,7 @@ describe("hyperframes skills", () => {
        "skills",
        "add",
        "https://github.com/heygen-com/hyperframes",
-        "--skill",
-        "*",
-        "--agent",
-        "claude-code",
-        "universal",
-        "--yes",
-        "--copy",
+        ...GLOBAL_ARGS,
      ],
    ],
  ] as const)(
@@ -201,11 +187,12 @@ describe("hyperframes skills", () => {
    await runSkillsUpdate();
    expect(process.exitCode).toBe(0);
    const args = state.spawnCalls[0]?.args ?? [];
-    // pulls the full set straight from GitHub
+    // pulls the full set straight from GitHub, globally, as a faithful clone
    expect(args).toContain("https://github.com/heygen-com/hyperframes");
-    // every skill, but to a scoped agent set — never the `--all` (= `--agent '*'`) spray
-    expect(args).toContain("--skill");
-    expect(args).toContain("--agent");
+    expect(args).toContain("--global");
+    expect(args).toContain("--copy");
+    expect(args).toContain("--full-depth");
+    // never the `--all` (= `--agent '*'`) spray
    expect(args).not.toContain("--all");
    // `--agent` must be followed by a concrete key, never the `'*'` wildcard
    const agentValue = args[args.indexOf("--agent") + 1];
@@ -6,11 +6,12 @@ import { buildNpxCommand } from "../utils/npxCommand.js";
 import { withMeta } from "../utils/updateCheck.js";
 import {
  checkSkills,
+  hyperframesSkillNames,
  SKILLS_CLI_LOCK_PATHS_VERIFIED_AT,
  type SkillDiff,
  type SkillsCheckResult,
 } from "../utils/skillsManifest.js";
-import { buildSkillsAddArgs, resolveAgentTargets } from "../utils/skillsTargets.js";
+import { mirrorGlobalSkills } from "../utils/skillsMirror.js";
 import type { Example } from "./_examples.js";

 export const examples: Example[] = [
@@ -35,15 +36,25 @@ function spawnNpx(args: string[], opts: { cwd?: string } = {}): Promise<void> {
  return new Promise((resolve, reject) => {
    const child = spawn(npx.command, npx.args, {
      stdio: "inherit",
-      timeout: 120_000,
+      // We install with --full-depth (a full `git clone` of the repo, the only
+      // path that bypasses the laggy skills.sh blob — see GLOBAL_INSTALL_ARGS),
+      // which is heavier than the blob fetch, so allow more headroom.
+      timeout: 300_000,
      cwd: opts.cwd,
-      // GH #316 — the upstream `skills` CLI shells out to `git clone`.
-      // When Git's clone-hook protection is active (shipped on by default in
-      // 2.45.1, reverted in 2.45.2, still present on many corporate and CI
-      // setups), a globally-registered `git lfs install` post-checkout hook
-      // aborts the clone. The args reaching this function are hardcoded — no
-      // user input reaches the spawn — so opting out here is safe.
-      env: { ...process.env, GIT_CLONE_PROTECTION_ACTIVE: "0" },
+      env: {
+        ...process.env,
+        // GH #316 — the upstream `skills` CLI shells out to `git clone`. When
+        // Git's clone-hook protection is active (default in 2.45.1, reverted in
+        // 2.45.2, still present on many corporate/CI setups), a globally
+        // registered `git lfs install` post-checkout hook aborts the clone. The
+        // args reaching this function are hardcoded (no user input), so opting
+        // out is safe.
+        GIT_CLONE_PROTECTION_ACTIVE: "0",
+        // Skills are text; the repo's LFS objects are unrelated binary assets.
+        // Skip the smudge so --full-depth doesn't drag down (or fail on) large
+        // LFS blobs the install doesn't need.
+        GIT_LFS_SKIP_SMUDGE: "1",
+      },
    });
    child.on("close", (code, signal) => {
      if (code === 0) resolve();
@@ -54,37 +65,37 @@ function spawnNpx(args: string[], opts: { cwd?: string } = {}): Promise<void> {
  });
 }

+// One faithful global install: --copy lands real files in Claude Code's global
+// store (~/.claude/skills, which Claude Code reads at global priority) plus the
+// shared universal store (~/.agents/skills). mirrorGlobalSkills then fans that
+// store out to every OTHER installed agent's global dir. Skills are
+// framework-general knowledge, so installing once globally beats copying a full
+// set into every project — and avoids the ~70-agent `--all` spray entirely.
+//
+// Why --copy: real files (not the upstream symlink default, which re-serialises
+// each SKILL.md's frontmatter) so an installed bundle byte-matches the published
+// manifest and `skills check` reads it as current. Why --full-depth: it forces a
+// full `git clone` of HEAD; without it even a full-URL `skills add` fetches the
+// skills.sh registry blob, which lags GitHub main by hours, so a fresh install
+// would read as several skills "outdated" (verified: blob → ~9 outdated;
+// --full-depth → all current).
+const GLOBAL_INSTALL_ARGS = [
+  "--skill",
+  "*",
+  "--global",
+  "--agent",
+  "claude-code",
+  "universal",
+  "--copy",
+  "--full-depth",
+  "--yes",
+];
+
 function runSkillsAdd(
  source: string,
  opts: { cwd?: string; extraArgs?: string[] } = {},
 ): Promise<void> {
-  // Targeting: an explicit `extraArgs` wins (callers/tests that know exactly
-  // what they want); otherwise resolve which agents to install to. We must NOT
-  // use the upstream `--all` (= `--skill '*' --agent '*' -y`), which sprays the
-  // skills into every one of ~70 agent conventions on the machine. Instead we
-  // install every skill (`--skill '*'`) to a scoped agent set: the project's
-  // existing skill folders, else the agent running us / installed agent CLIs,
-  // else a Claude-Code + `.agents` floor. See resolveAgentTargets.
-  let extraArgs = opts.extraArgs;
-  if (!extraArgs) {
-    const targets = resolveAgentTargets({
-      cwd: opts.cwd ?? process.cwd(),
-      env: process.env,
-      pathStr: process.env["PATH"] ?? "",
-      platform: process.platform,
-    });
-    console.log(c.dim(`Installing to: ${targets.agents.join(", ")} — ${targets.reason}`));
-    extraArgs = buildSkillsAddArgs(targets.agents);
-  }
-
-  // `--copy` writes real files into each target agent's skills dir, instead of
-  // the upstream default (a canonical `.agents/skills` store + per-agent
-  // symlinks). That default re-serialises each SKILL.md's frontmatter, so an
-  // installed bundle no longer byte-matches the published manifest — `skills
-  // check` then reports a freshly-installed set as outdated, and the symlinked
-  // layout doesn't reliably land where the agent actually reads. Real copies
-  // keep the install faithful to the manifest and detectable by `skills check`.
-  return spawnNpx(["skills", "add", source, ...extraArgs, "--copy"], opts);
+  return spawnNpx(["skills", "add", source, ...(opts.extraArgs ?? GLOBAL_INSTALL_ARGS)], opts);
 }

 // Skill names are kebab-case directory names. Refuse anything that isn't one
@@ -108,12 +119,34 @@ function runSkillsRemove(names: string[], opts: { global: boolean }): Promise<vo
  return spawnNpx(["skills", "remove", ...safe, ...(opts.global ? ["-g"] : []), "--yes"]);
 }

-// Use the full GitHub URL (not the `owner/repo` slug) so `skills add` git-clones
-// the repo directly at latest `main`, bypassing the skills.sh registry — which
-// can lag behind the repo. Our freshness check already resolves "latest"
-// straight from GitHub, so this keeps install/update consistent with check.
+// Use the full GitHub URL (not the `owner/repo` slug) as the clone source. The
+// freshness comes from --full-depth (see GLOBAL_INSTALL_ARGS), which clones the
+// repo at latest `main`; the URL just names what to clone. Our freshness check
+// resolves "latest" straight from GitHub too, so install and check agree.
 const SOURCES = [{ name: "HyperFrames", url: "https://github.com/heygen-com/hyperframes" }];

+// Fan HyperFrames' own skills out to every other installed agent. Scope by the
+// lock's source attribution (the same definition prune uses) — NOT by listing
+// ~/.claude/skills, which is shared with the user's other Claude skills (gstack,
+// personal, company). No-op when nothing is attributed or the global store is
+// absent, so it's safe to run unconditionally after any install. Best-effort: a
+// mirror failure must not fail the install.
+function mirrorToInstalledAgents(): void {
+  try {
+    const names = hyperframesSkillNames({ scope: "global" });
+    if (names.length === 0) return;
+    const { mirrored } = mirrorGlobalSkills({ skills: names });
+    const n = mirrored.length;
+    if (n > 0) {
+      console.log(
+        c.dim(`Linked skills into ${n} other agent ${n === 1 ? "directory" : "directories"}.`),
+      );
+    }
+  } catch {
+    // best-effort
+  }
+}
+
 export async function installAllSkills(
  opts: { cwd?: string; extraArgs?: string[]; strict?: boolean } = {},
 ): Promise<void> {
@@ -138,6 +171,8 @@ export async function installAllSkills(
      console.log(c.dim(`${source.name} skills skipped`));
    }
  }
+
+  mirrorToInstalledAgents();
 }

 // ── check ────────────────────────────────────────────────────────────────────
@@ -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"];
-}