Skip to content

Write HTML. Render video. Built for agents.

fix(cli): honour HYPERFRAMES_SKIP_SKILLS in skills update and bare skills (#5743)

kevin6dba67a0c3a0
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index 50867b6a7b..0ed9b94395 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -1648,6 +1648,10 @@ adds it. `check` and `update` both accept `--json`, plus `--dir` and `--source`
to point removed-detection at a different skills directory or source — those two
scope the prune, not the install.
+Set `HYPERFRAMES_SKIP_SKILLS=1` when something else manages the skills (CI, tests,
+or an install pinned to one commit). `skills update` and bare `skills` then exit 0
+with a one-line notice and leave the installed skills unchanged.
+
The CLI installs from the current HyperFrames GitHub source and links the global
bundles into whichever compatible agents it finds. After scaffolding, `init`
also refreshes the core set plus any HyperFrames skills you already have.
diff --git a/packages/cli/src/commands/skills.test.ts b/packages/cli/src/commands/skills.test.ts
index 20591e09bd..979c18069f 100644
--- a/packages/cli/src/commands/skills.test.ts
+++ b/packages/cli/src/commands/skills.test.ts
@@ -640,6 +640,87 @@ describe("hyperframes skills", () => {
expect(await commandExitCode()).toBe(1);
});
+ // GH #5695: the router runs `skills update <workflow>` before every workflow, so a
+ // team that pins its skills and sets HYPERFRAMES_SKIP_SKILLS=1 (like `init`
+ // honours) must not have that pin replaced by the latest upstream skills.
+ describe("with HYPERFRAMES_SKIP_SKILLS=1", () => {
+ beforeEach(() => {
+ vi.stubEnv("HYPERFRAMES_SKIP_SKILLS", "1");
+ invalidateSkillsCache.mockClear();
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ });
+
+ it("named `skills update` leaves a pinned install alone and exits 0", async () => {
+ setPlatform("linux");
+ const logSpy = vi.spyOn(console, "log");
+ const { checkSkills } = await import("../utils/skillsManifest.js");
+
+ await runSkillsUpdateWith(["product-launch-video"]);
+
+ expect(state.spawnCalls).toHaveLength(0);
+ expect(vi.mocked(checkSkills)).not.toHaveBeenCalled();
+ expect(invalidateSkillsCache).not.toHaveBeenCalled();
+ expect(await commandExitCode()).toBe(0);
+ expect(String(logSpy.mock.calls.at(-1)?.[0] ?? "")).toMatch(/managed externally/);
+ });
+
+ it("bare `skills update` neither installs nor prunes", async () => {
+ setPlatform("linux");
+ const { checkSkills } = await import("../utils/skillsManifest.js");
+ vi.mocked(checkSkills).mockImplementation(
+ async () =>
+ ({
+ ...DEFAULT_CHECK,
+ skills: [...DEFAULT_CHECK.skills, { name: "graphic-overlays", status: "removed" }],
+ }) as never,
+ );
+
+ await runSkillsUpdate();
+
+ expect(state.spawnCalls).toHaveLength(0);
+ expect(vi.mocked(checkSkills)).not.toHaveBeenCalled();
+ expect(await commandExitCode()).toBe(0);
+ });
+
+ it("bare `skills` does not install the full set", async () => {
+ setPlatform("linux");
+
+ const { default: skillsCmd } = await import("./skills.js");
+ await skillsCmd.run?.({ args: {}, rawArgs: [], cmd: skillsCmd } as never);
+
+ expect(state.spawnCalls).toHaveLength(0);
+ expect(invalidateSkillsCache).not.toHaveBeenCalled();
+ expect(await commandExitCode()).toBe(0);
+ });
+
+ it("--json reports the skip as parseable JSON", async () => {
+ setPlatform("linux");
+ const logSpy = vi.spyOn(console, "log");
+
+ await runSkillsUpdateWith(["pr-to-video"], { json: true });
+
+ expect(await commandExitCode()).toBe(0);
+ const parsed = JSON.parse(String(logSpy.mock.calls.at(-1)?.[0] ?? "")) as {
+ skipped?: boolean;
+ requested?: string[];
+ };
+ expect(parsed.skipped).toBe(true);
+ expect(parsed.requested).toEqual(["pr-to-video"]);
+ });
+
+ it("still rejects flag-like skill names", async () => {
+ setPlatform("linux");
+
+ await runSkillsUpdateWith(["--all"]);
+
+ expect(state.spawnCalls).toHaveLength(0);
+ expect(await commandExitCode()).toBe(1);
+ });
+ });
+
// The stale-24h-cache regression: the skills commands are excluded from the
// background nudge pipeline (cli.ts), so unless they drop the cached verdict
// themselves, a successful install keeps the pre-install "N out of date or
diff --git a/packages/cli/src/commands/skills.ts b/packages/cli/src/commands/skills.ts
index 5920bc27c4..38d4d60a95 100644
--- a/packages/cli/src/commands/skills.ts
+++ b/packages/cli/src/commands/skills.ts
@@ -615,6 +615,37 @@ const checkCommand = defineCommand({
},
});
+// ── externally managed installs ────────────────────────────────────────────────
+
+/**
+ * `HYPERFRAMES_SKIP_SKILLS=1` means something other than this CLI owns the skills
+ * install: CI, tests, or a team that pins the skills to one commit. `init` and the
+ * background nudge already stand down for it; the install commands must too, or
+ * the router's trigger-time `skills update <workflow>` replaces a pinned install
+ * with the latest upstream skills (GH #5695).
+ */
+function skillsManagedExternally(): boolean {
+ return process.env["HYPERFRAMES_SKIP_SKILLS"] === "1";
+}
+
+const SKILLS_MANAGED_EXTERNALLY_NOTICE =
+ "HYPERFRAMES_SKIP_SKILLS=1: skills are managed externally, so the installed skills were left unchanged.";
+
+/** The skip line for an externally managed install: JSON for agents, one dim line for humans. */
+function reportSkillsManagedExternally(requested: readonly string[], json: boolean): void {
+ if (json) {
+ console.log(
+ JSON.stringify(
+ withMeta({ skipped: true, reason: SKILLS_MANAGED_EXTERNALLY_NOTICE, requested }),
+ null,
+ 2,
+ ),
+ );
+ return;
+ }
+ console.log(c.dim(SKILLS_MANAGED_EXTERNALLY_NOTICE));
+}
+
// ── update ───────────────────────────────────────────────────────────────────
/**
@@ -713,6 +744,13 @@ const updateCommand = defineCommand({
return;
}
+ // Exit 0 without installing, pruning or touching the nudge cache: the pinned
+ // install is the one the caller wants, so the router's step keeps working.
+ if (skillsManagedExternally()) {
+ reportSkillsManagedExternally(requested, args.json === true);
+ return;
+ }
+
// Targeted, not full-set: refresh the core set (entry router + shared
// domain skills) plus whatever is already installed, plus anything named
// above. Without names a deliberate partial install stays partial
@@ -813,6 +851,10 @@ export default defineCommand({
// the positional so bare `hyperframes skills` installs, while
// `hyperframes skills check|update` does not also re-install.
if (!args._?.[0]) {
+ if (skillsManagedExternally()) {
+ reportSkillsManagedExternally([], false);
+ return;
+ }
await updateSkills({ all: true });
// Same as updateSkills: a full install supersedes the background
// nudge's cached pre-install verdict.
diff --git a/skills/hyperframes/references/skill-lifecycle.md b/skills/hyperframes/references/skill-lifecycle.md
index 7b2c4718aa..f3b21def1a 100644
--- a/skills/hyperframes/references/skill-lifecycle.md
+++ b/skills/hyperframes/references/skill-lifecycle.md
@@ -15,6 +15,8 @@ HyperFrames installs the core set eagerly and workflow skills lazily.
The `--skip-skills` CLI flag is temporarily ignored. CI and tests may opt out with `HYPERFRAMES_SKIP_SKILLS=1`.
+`HYPERFRAMES_SKIP_SKILLS=1` also makes `skills update` (bare or named) and bare `skills` exit 0 without installing or pruning, so an install pinned to one commit stays pinned.
+
## Diagnose and update
```bash