Skip to content

Commit 7d28f29

Browse files
fix(cli): scope skill installs to relevant agents, not all ~70 via --all
`hyperframes skills`, `skills update`, and `init` all shelled out to `skills add ... --all`, which the upstream CLI expands to `--skill '*' --agent '*' -y` — every skill into every one of the ~70 agent conventions it knows about. A user who only runs Claude Code got skill folders for Cursor, Codex, and 50+ tools they never touch. Replace `--all` with a resolved target set (new resolveAgentTargets): 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, so honour it exactly. 2. Otherwise (blank project): a. Running under Claude Code (CLAUDECODE) → just claude-code. b. Else probe PATH for installed agent CLIs (claude, hermes, droid, cursor, codex, opencode, gemini) — the gstack approach. c. Else fall back to claude-code + the shared `.agents` universal dir, which Cursor, Codex, OpenCode, Gemini, Copilot and ~14 others read from in project scope. Never `--agent '*'`. Installs stay `--skill '*'` (all skills) + `--copy` (faithful, detectable by `skills check`); only the agent fan-out is scoped. The dir<->key map is explicit because dir names differ from upstream keys (`.factory`/droid, `.hermes`/hermes-agent) and many agents share `.agents` (-> the single `universal` key). Keys verified against vercel-labs/[email protected]. Verified end-to-end in an isolated project + HOME: the new args land exactly `.claude/skills` (19) + `.agents/skills` (19) and nothing else — 2 folders, not 50+. Pure resolver covered by skillsTargets.test.ts; command-arg shape and the "never --all" regression pinned in skills.test.ts. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 05af482 commit 7d28f29

5 files changed

Lines changed: 373 additions & 18 deletions

File tree

‎packages/cli/src/commands/init.ts‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -584,12 +584,6 @@ async function scaffoldProject(
584584
async function ensureSkillsCurrent(destDir: string): Promise<void> {
585585
const { installAllSkills } = await import("./skills.js");
586586
const { checkSkills } = await import("../utils/skillsManifest.js");
587-
// --all pulls every skill (incl. ones not yet installed); --yes keeps it
588-
// non-interactive. When Claude Code is driving, target its native dir so
589-
// skills land in .claude/skills/.
590-
const extraArgs = process.env["CLAUDECODE"]
591-
? ["--all", "--agent", "claude-code", "--yes"]
592-
: ["--all", "--yes"];
593587

594588
console.log();
595589
console.log(c.bold("Checking AI coding skills against GitHub..."));
@@ -602,7 +596,12 @@ async function ensureSkillsCurrent(destDir: string): Promise<void> {
602596
}
603597

604598
if (needsInstall) {
605-
await installAllSkills({ cwd: destDir, extraArgs });
599+
// installAllSkills resolves the agent target set from destDir + the
600+
// environment (Claude Code → claude-code; otherwise installed CLIs, else a
601+
// Claude-Code + `.agents` floor). A freshly-scaffolded project has no agent
602+
// folders yet, so this lands skills where the running agent will read them
603+
// rather than spraying to every agent convention.
604+
await installAllSkills({ cwd: destDir });
606605
} else {
607606
console.log(c.success("AI coding skills are already up to date."));
608607
}

‎packages/cli/src/commands/skills.test.ts‎

Lines changed: 50 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,17 @@ vi.mock("../utils/skillsManifest.js", () => ({
5656
checkSkills: vi.fn(async () => ({ skills: [] })),
5757
}));
5858

59+
// Agent-target resolution probes the real cwd / PATH / env, which would make
60+
// the spawned-args assertions environment-dependent. Pin it to a fixed result
61+
// so these tests verify how the command BUILDS the spawn, not what's installed
62+
// on the test host. The resolver's own decision tree is covered in
63+
// skillsTargets.test.ts. buildSkillsAddArgs is reproduced (it's trivial) so the
64+
// arg shape under test stays real.
65+
vi.mock("../utils/skillsTargets.js", () => ({
66+
resolveAgentTargets: vi.fn(() => ({ agents: ["claude-code", "universal"], reason: "test" })),
67+
buildSkillsAddArgs: (agents: string[]) => ["--skill", "*", "--agent", ...agents, "--yes"],
68+
}));
69+
5970
function setPlatform(platform: NodeJS.Platform): void {
6071
Object.defineProperty(process, "platform", {
6172
value: platform,
@@ -109,13 +120,35 @@ describe("hyperframes skills", () => {
109120
"linux",
110121
"npx",
111122
["--version"],
112-
["skills", "add", "https://github.com/heygen-com/hyperframes", "--all", "--copy"],
123+
[
124+
"skills",
125+
"add",
126+
"https://github.com/heygen-com/hyperframes",
127+
"--skill",
128+
"*",
129+
"--agent",
130+
"claude-code",
131+
"universal",
132+
"--yes",
133+
"--copy",
134+
],
113135
],
114136
[
115137
"darwin",
116138
"npx",
117139
["--version"],
118-
["skills", "add", "https://github.com/heygen-com/hyperframes", "--all", "--copy"],
140+
[
141+
"skills",
142+
"add",
143+
"https://github.com/heygen-com/hyperframes",
144+
"--skill",
145+
"*",
146+
"--agent",
147+
"claude-code",
148+
"universal",
149+
"--yes",
150+
"--copy",
151+
],
119152
],
120153
[
121154
"win32",
@@ -129,7 +162,12 @@ describe("hyperframes skills", () => {
129162
"skills",
130163
"add",
131164
"https://github.com/heygen-com/hyperframes",
132-
"--all",
165+
"--skill",
166+
"*",
167+
"--agent",
168+
"claude-code",
169+
"universal",
170+
"--yes",
133171
"--copy",
134172
],
135173
],
@@ -162,9 +200,16 @@ describe("hyperframes skills", () => {
162200
setPlatform("linux");
163201
await runSkillsUpdate();
164202
expect(process.exitCode).toBe(0);
203+
const args = state.spawnCalls[0]?.args ?? [];
165204
// pulls the full set straight from GitHub
166-
expect(state.spawnCalls[0]?.args).toContain("https://github.com/heygen-com/hyperframes");
167-
expect(state.spawnCalls[0]?.args).toContain("--all");
205+
expect(args).toContain("https://github.com/heygen-com/hyperframes");
206+
// every skill, but to a scoped agent set — never the `--all` (= `--agent '*'`) spray
207+
expect(args).toContain("--skill");
208+
expect(args).toContain("--agent");
209+
expect(args).not.toContain("--all");
210+
// `--agent` must be followed by a concrete key, never the `'*'` wildcard
211+
const agentValue = args[args.indexOf("--agent") + 1];
212+
expect(agentValue).not.toBe("*");
168213
});
169214

170215
// `skills add --all` never deletes, so update must separately prune skills the

‎packages/cli/src/commands/skills.ts‎

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import {
1010
type SkillDiff,
1111
type SkillsCheckResult,
1212
} from "../utils/skillsManifest.js";
13+
import { buildSkillsAddArgs, resolveAgentTargets } from "../utils/skillsTargets.js";
1314
import type { Example } from "./_examples.js";
1415

1516
export const examples: Example[] = [
@@ -57,14 +58,33 @@ function runSkillsAdd(
5758
source: string,
5859
opts: { cwd?: string; extraArgs?: string[] } = {},
5960
): Promise<void> {
61+
// Targeting: an explicit `extraArgs` wins (callers/tests that know exactly
62+
// what they want); otherwise resolve which agents to install to. We must NOT
63+
// use the upstream `--all` (= `--skill '*' --agent '*' -y`), which sprays the
64+
// skills into every one of ~70 agent conventions on the machine. Instead we
65+
// install every skill (`--skill '*'`) to a scoped agent set: the project's
66+
// existing skill folders, else the agent running us / installed agent CLIs,
67+
// else a Claude-Code + `.agents` floor. See resolveAgentTargets.
68+
let extraArgs = opts.extraArgs;
69+
if (!extraArgs) {
70+
const targets = resolveAgentTargets({
71+
cwd: opts.cwd ?? process.cwd(),
72+
env: process.env,
73+
pathStr: process.env["PATH"] ?? "",
74+
platform: process.platform,
75+
});
76+
console.log(c.dim(`Installing to: ${targets.agents.join(", ")} — ${targets.reason}`));
77+
extraArgs = buildSkillsAddArgs(targets.agents);
78+
}
79+
6080
// `--copy` writes real files into each target agent's skills dir, instead of
6181
// the upstream default (a canonical `.agents/skills` store + per-agent
6282
// symlinks). That default re-serialises each SKILL.md's frontmatter, so an
6383
// installed bundle no longer byte-matches the published manifest — `skills
6484
// check` then reports a freshly-installed set as outdated, and the symlinked
6585
// layout doesn't reliably land where the agent actually reads. Real copies
6686
// keep the install faithful to the manifest and detectable by `skills check`.
67-
return spawnNpx(["skills", "add", source, ...(opts.extraArgs ?? ["--all"]), "--copy"], opts);
87+
return spawnNpx(["skills", "add", source, ...extraArgs, "--copy"], opts);
6888
}
6989

7090
// Skill names are kebab-case directory names. Refuse anything that isn't one
@@ -244,12 +264,15 @@ const updateCommand = defineCommand({
244264
const dir = args.dir;
245265
const source = args.source;
246266

247-
// `skills add --all` re-fetches every skill to the latest AND installs ones
248-
// not yet present — so "update" pulls the full set, not just what is already
267+
// The install re-fetches every skill to the latest AND installs ones not yet
268+
// present — so "update" pulls the full set, not just what is already
249269
// installed. This is where `init` and the stale-skills nudge both lead.
270+
// runSkillsAdd resolves the agent target set itself (existing project
271+
// folders → installed CLIs → a Claude-Code + `.agents` floor); we no longer
272+
// spray to every agent via `--all`.
250273
//
251274
// Note: the upstream `skills add` CLI has no `--dir` flag (it installs into
252-
// detected agent dirs), so `--dir` here scopes only the *prune* detection
275+
// the resolved agent dirs), so `--dir` here scopes only the *prune* detection
253276
// below, not the install. `--source` likewise drives where the prune's
254277
// "latest" manifest comes from; the install always targets the canonical
255278
// HyperFrames repo so `update` reliably pulls the published set.
@@ -259,14 +282,14 @@ const updateCommand = defineCommand({
259282
// fails (no npx, `skills add` exits non-zero) it must exit non-zero too —
260283
// otherwise the `||` chain passes while nothing actually changed.
261284
try {
262-
await installAllSkills({ extraArgs: ["--all", "--yes"], strict: true });
285+
await installAllSkills({ strict: true });
263286
} catch (err) {
264287
clack.log.error(c.error(`Update failed: ${(err as Error).message}`));
265288
process.exitCode = 1;
266289
return;
267290
}
268291

269-
// `skills add --all` never deletes, so a skill renamed or dropped upstream
292+
// `skills add` never deletes, so a skill renamed or dropped upstream
270293
// (e.g. graphic-overlays → talking-head-recut) would linger forever. Prune
271294
// skills the lock attributes to our source that the manifest no longer
272295
// ships, so `check || update` fully reconciles the install to the manifest.
Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
import { afterEach, describe, expect, it } from "vitest";
2+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
5+
import { buildSkillsAddArgs, resolveAgentTargets } from "./skillsTargets.js";
6+
7+
const tmpDirs: string[] = [];
8+
9+
function tempDir(prefix: string): string {
10+
const dir = mkdtempSync(join(tmpdir(), prefix));
11+
tmpDirs.push(dir);
12+
return dir;
13+
}
14+
15+
/** A project root containing the given `<host>/skills` folders. */
16+
function projectWith(...hostDirs: string[]): string {
17+
const root = tempDir("hf-targets-proj-");
18+
for (const host of hostDirs) mkdirSync(join(root, host, "skills"), { recursive: true });
19+
return root;
20+
}
21+
22+
/** A PATH-style string pointing at a dir that contains the given fake executables. */
23+
function pathWith(...bins: string[]): string {
24+
const dir = tempDir("hf-targets-bin-");
25+
for (const bin of bins) writeFileSync(join(dir, bin), "");
26+
return dir;
27+
}
28+
29+
afterEach(() => {
30+
for (const dir of tmpDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
31+
});
32+
33+
describe("resolveAgentTargets", () => {
34+
const blank = { env: {}, pathStr: "", platform: "linux" as const };
35+
36+
// ── 1. Existing project folders win, mapped dir → upstream key ──────────────
37+
38+
it("honours an existing `.hermes/skills` folder, nothing else", () => {
39+
const result = resolveAgentTargets({ ...blank, cwd: projectWith(".hermes") });
40+
expect(result.agents).toEqual(["hermes-agent"]);
41+
});
42+
43+
it("maps `.factory` → droid and `.kiro` → kiro-cli (dir names differ from keys)", () => {
44+
const result = resolveAgentTargets({ ...blank, cwd: projectWith(".factory", ".kiro") });
45+
expect(result.agents).toEqual(["droid", "kiro-cli"]);
46+
});
47+
48+
it("maps the shared `.agents` dir to the single `universal` key", () => {
49+
const result = resolveAgentTargets({ ...blank, cwd: projectWith(".agents") });
50+
expect(result.agents).toEqual(["universal"]);
51+
});
52+
53+
it("returns claude-code first across multiple existing folders", () => {
54+
const result = resolveAgentTargets({ ...blank, cwd: projectWith(".agents", ".claude") });
55+
expect(result.agents).toEqual(["claude-code", "universal"]);
56+
});
57+
58+
it("existing folders take precedence over CLAUDECODE and PATH", () => {
59+
const result = resolveAgentTargets({
60+
cwd: projectWith(".hermes"),
61+
env: { CLAUDECODE: "1" },
62+
pathStr: pathWith("claude", "cursor"),
63+
platform: "linux",
64+
});
65+
expect(result.agents).toEqual(["hermes-agent"]);
66+
});
67+
68+
// ── 2a. Claude Code env on a blank project ──────────────────────────────────
69+
70+
it("targets just claude-code when running under Claude Code", () => {
71+
const result = resolveAgentTargets({
72+
...blank,
73+
cwd: projectWith(),
74+
env: { CLAUDECODE: "1" },
75+
});
76+
expect(result.agents).toEqual(["claude-code"]);
77+
});
78+
79+
// ── 2b. gstack route: installed agent CLIs on PATH ──────────────────────────
80+
81+
it("detects installed agent CLIs on PATH (blank project, no CLAUDECODE)", () => {
82+
const result = resolveAgentTargets({
83+
cwd: projectWith(),
84+
env: {},
85+
pathStr: pathWith("claude", "hermes"),
86+
platform: "linux",
87+
});
88+
expect(result.agents).toEqual(["claude-code", "hermes-agent"]);
89+
});
90+
91+
it("collapses universal-bucket CLIs (cursor/codex/…) to a single `universal`", () => {
92+
const result = resolveAgentTargets({
93+
cwd: projectWith(),
94+
env: {},
95+
pathStr: pathWith("cursor", "codex", "gemini"),
96+
platform: "linux",
97+
});
98+
expect(result.agents).toEqual(["universal"]);
99+
});
100+
101+
// ── 2c. Floor ───────────────────────────────────────────────────────────────
102+
103+
it("falls back to claude-code + universal (.claude + .agents) when nothing is found", () => {
104+
const result = resolveAgentTargets({ ...blank, cwd: projectWith() });
105+
expect(result.agents).toEqual(["claude-code", "universal"]);
106+
});
107+
108+
// ── Invariant: never the `--all` spray ──────────────────────────────────────
109+
110+
it("never returns the `'*'` wildcard agent", () => {
111+
for (const cwd of [projectWith(), projectWith(".hermes"), projectWith(".claude")]) {
112+
const result = resolveAgentTargets({ ...blank, cwd });
113+
expect(result.agents).not.toContain("*");
114+
expect(result.agents.length).toBeGreaterThan(0);
115+
}
116+
});
117+
});
118+
119+
describe("buildSkillsAddArgs", () => {
120+
it("installs every skill to the given agents, non-interactive — not `--all`", () => {
121+
expect(buildSkillsAddArgs(["claude-code", "universal"])).toEqual([
122+
"--skill",
123+
"*",
124+
"--agent",
125+
"claude-code",
126+
"universal",
127+
"--yes",
128+
]);
129+
});
130+
});

0 commit comments

Comments
 (0)