Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.mdxindex 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 twoscope 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 globalbundles 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.tsindex 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 ordiff --git a/packages/cli/src/commands/skills.ts b/packages/cli/src/commands/skills.tsindex 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.mdindex 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