From 604a25fbaaba5c3b9dac5deab1d51859fee2516c Mon Sep 17 00:00:00 2001 From: Wenbo Zhu Date: Wed, 4 Nov 2026 13:31:12 +0000 Subject: [PATCH] fix(cli): address skills install and update hints to the person (#7160) * fix(cli): address skills install and update hints to the person DeltaVerdict D5 fails any text an agent reads that tells the agent to install, update or remove skills, even when gated on the user. #7094 and #7102 fixed the update notice and skills/; the scaffolded CLAUDE.md and AGENTS.md, CLI output and the quickstart prompt still told the agent to run `skills update`. Reword them to state the fact and name the command the person runs ("For the user: ..."), matching the #7094 `_meta.updateNotice` style. The two scaffold templates stay byte-identical. No behavior changes. Co-Authored-By: Claude Opus 5.5 * fix(cli): address media-use repair and update --check hints to the person Review follow-up on #7160. The media-use SFX repair error and its `resolve --doctor` line still told the agent to run `npx hyperframes skills update media-use`; `update --check` printed a bare `Run: `; and the README addressed agents directly. Reword them in the "For the user:" form. The JSON `fix` field keeps the bare command. Pin the wording in tests: both scaffold templates, the stderr nudge, the `init --skip-skills` hint, the media-use error and doctor line, and the `update --check` output. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- README.md | 2 +- docs/quickstart.mdx | 12 +++++++++--- .../cli/src/commands/coreSkillContent.test.ts | 15 +++++++++++++++ packages/cli/src/commands/init.test.ts | 4 ++++ packages/cli/src/commands/init.ts | 6 ++++-- packages/cli/src/commands/skills.ts | 8 ++++---- packages/cli/src/commands/update.test.ts | 8 ++++++++ packages/cli/src/commands/update.ts | 6 ++++-- .../src/media-use/lib/bundled-sfx-provider.mjs | 2 +- packages/cli/src/media-use/resolve.mjs | 14 ++++++++++++-- packages/cli/src/media-use/resolve.test.mjs | 17 +++++++++++++++++ packages/cli/src/templates/_shared/AGENTS.md | 13 +++++++------ packages/cli/src/templates/_shared/CLAUDE.md | 13 +++++++------ .../cli/src/utils/skillsUpdateCheck.test.ts | 3 +++ packages/cli/src/utils/skillsUpdateCheck.ts | 2 +- 15 files changed, 97 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 8d074d503a..40b70a505d 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ For standalone skills (including OpenCode), use: npx skills add heygen-com/hyperframes ``` -> The picker opens with nothing pre-selected — the **Core Skills** group is all you need; `/slideshow`, `/remotion-to-hyperframes`, `/reverse-any-video`, `/style-sampling` and `/figma` install on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas `skills add --all` installs all 9 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`. +> The picker opens with nothing pre-selected — the **Core Skills** group is all you need; `/slideshow`, `/remotion-to-hyperframes`, `/reverse-any-video`, `/style-sampling` and `/figma` install on demand. Without the picker (a script or a CI job), `npx hyperframes skills update` installs exactly the core set, whereas `skills add --all` installs all 9 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`. > > `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs the skills from the release tag that matches your CLI version, so they match the CLI that runs them. diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index e66a8280de..293295ef94 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -55,13 +55,19 @@ system. ### The short way -If you already have a coding agent open in a folder, paste this. It installs the skills, makes the video, and opens -the preview. You only change the URL. +Unless the HyperFrames plugin is installed, install the skills once from a terminal in your project folder, then +open or restart your coding agent there: + +```bash +npx hyperframes skills update +``` + +Paste this into the agent. It makes the video and opens the preview. You only change the URL. ```text Set this folder up for HyperFrames and make me a video. -1. If the HyperFrames plugin is installed, use its bundled skills and launcher. Otherwise run: npx hyperframes skills update +1. If the HyperFrames plugin is installed, use its bundled skills and launcher. If the HyperFrames skills are missing, stop and tell me: I install them with npx hyperframes skills update 2. Then, using /hyperframes, make a 10-second product intro for https://example.com 3. Open the local preview when it is done and tell me the project folder. ``` diff --git a/packages/cli/src/commands/coreSkillContent.test.ts b/packages/cli/src/commands/coreSkillContent.test.ts index cefa8352bb..5c8f5a2c55 100644 --- a/packages/cli/src/commands/coreSkillContent.test.ts +++ b/packages/cli/src/commands/coreSkillContent.test.ts @@ -174,4 +174,19 @@ describe("media treatment routing documentation", () => { expect(template).not.toContain("run_in_background: true"); } }); + + // DeltaVerdict D5: text an agent reads may name the person's skills command but never + // tell the agent to install, update or remove skills, even gated on consent. + it("leaves installing and updating skills to the person in new project instructions", () => { + for (const file of ["AGENTS.md", "CLAUDE.md"]) { + const template = read("packages", "cli", "src", "templates", "_shared", file); + expect(template).toContain("do not run the install yourself"); + expect(template).toContain("For the user:\n> `npx hyperframes skills update `"); + for (const line of template.split("\n").filter((l) => /skills (update|add)/.test(l))) { + expect(line, file).not.toMatch( + /\b(Run|run|Re-run|Install|Update|Repair|Reinstall)\b[^`]*`npx (hyperframes )?skills/, + ); + } + } + }); }); diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts index 50c1c59340..f84e07d452 100644 --- a/packages/cli/src/commands/init.test.ts +++ b/packages/cli/src/commands/init.test.ts @@ -180,6 +180,10 @@ describe("hyperframes init flag rename", () => { expect(res.status).toBe(0); expect(res.stdout).not.toContain("Checking AI coding skills"); expect(res.stdout).not.toContain("temporarily ignored"); + // Installing skills is the person's step, so the hint is addressed to them. + expect(res.stdout).toContain( + "For the user: use your HyperFrames plugin, or install standalone skills with:", + ); } finally { rmSync(dir, { recursive: true, force: true }); } diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index 0e4d6862dc..f9d6c5acbc 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -690,7 +690,9 @@ async function keepSkillsCurrent(destDir: string): Promise { // "up to date"; the engine already reported what it could verify or // blind-install. Point at the recovery command instead. console.log( - c.dim("Skills freshness unverified — run `npx hyperframes skills update` when online."), + c.dim( + "Skills freshness unverified (offline?). For the user: `npx hyperframes skills update` refreshes them once online.", + ), ); } else if (result.installed.length === 0) { console.log(c.success("AI coding skills are already up to date.")); @@ -977,7 +979,7 @@ export default defineCommand({ console.log(); if (skipSkills) { console.log( - ` ${c.accent("1.")} Use your HyperFrames plugin, or install standalone skills:`, + ` ${c.accent("1.")} For the user: use your HyperFrames plugin, or install standalone skills with:`, ); console.log(` ${c.accent("npx hyperframes skills update")}`); } else { diff --git a/packages/cli/src/commands/skills.ts b/packages/cli/src/commands/skills.ts index 1237b6b447..9dc0e64f73 100644 --- a/packages/cli/src/commands/skills.ts +++ b/packages/cli/src/commands/skills.ts @@ -380,7 +380,7 @@ export async function updateSkills( // reinstate the 26-skill sweep this path exists to avoid. clack.log.warn( c.warn( - "Can't resolve the published skill set (manifest unreachable) — installing the pinned core set only. Re-run `hyperframes skills` online for the full set.", + "Can't resolve the published skill set (manifest unreachable) — installing the pinned core set only. For the user: `hyperframes skills` installs the full set once online.", ), ); } @@ -550,7 +550,7 @@ function renderCheck(result: SkillsCheckResult): void { if (!result.location) { console.log(` ${c.dim("No HyperFrames skills found in the usual locations.")}`); - console.log(` ${c.accent("Install: npx hyperframes skills")}`); + console.log(` ${c.accent("For the user: npx hyperframes skills installs them")}`); console.log(); return; } @@ -577,14 +577,14 @@ function renderCheck(result: SkillsCheckResult): void { printSkillSection( result, "missing", - "Available on demand (install with `hyperframes skills update `):", + "Available on demand (`hyperframes skills update ` installs one):", "◦", c.dim, (s) => !isCoreSkill(s.name), ); console.log(); if (result.updateAvailable) { - console.log(` ${c.accent("Update: npx hyperframes skills update")}`); + console.log(` ${c.accent("For the user: npx hyperframes skills update refreshes them")}`); } else { console.log(` ${c.success("◇")} ${c.success("Installed skills are up to date")}`); } diff --git a/packages/cli/src/commands/update.test.ts b/packages/cli/src/commands/update.test.ts index 2eb4257e5a..6702191b49 100644 --- a/packages/cli/src/commands/update.test.ts +++ b/packages/cli/src/commands/update.test.ts @@ -202,6 +202,14 @@ describe("hyperframes update --check", () => { expect(text).not.toContain("latest"); }); + it("names both commands for the person, not as a bare Run: line", async () => { + await runUpdate(ENTRIES.npm, { check: true }); + const text = stdout.join("\n"); + expect(text).toContain("For the user: run npm install -g hyperframes@0.9.8"); + expect(text).toContain("For the user: run hyperframes update"); + expect(text).not.toMatch(/\bRun:/); + }); + it.each([ ["npm", ENTRIES.npm, "npm install -g hyperframes@0.9.8"], ["pnpm", ENTRIES.pnpm, "pnpm add -g hyperframes@0.9.8"], diff --git a/packages/cli/src/commands/update.ts b/packages/cli/src/commands/update.ts index ff57d4776a..efd1786cfe 100644 --- a/packages/cli/src/commands/update.ts +++ b/packages/cli/src/commands/update.ts @@ -153,10 +153,12 @@ function printCheck(cli: CliReport, skills: SkillsReport): void { : c.success(`${cli.current} (${cli.checkedAt ? "latest" : "npm registry not reached"})`); console.log(` ${c.bold("CLI".padEnd(8))}${version}`); console.log(` ${" ".repeat(8)}${c.dim(where)}`); - if (cli.command) console.log(` ${" ".repeat(8)}${c.accent(`Run: ${cli.command}`)}`); + if (cli.command) { + console.log(` ${" ".repeat(8)}${c.accent(`For the user: run ${cli.command}`)}`); + } console.log(` ${c.bold("Skills".padEnd(8))}${skillsLine(skills)}`); if (skills.status === "checked" && skills.command) { - console.log(` ${" ".repeat(8)}${c.accent(`Run: ${skills.command}`)}`); + console.log(` ${" ".repeat(8)}${c.accent(`For the user: run ${skills.command}`)}`); } console.log(); } diff --git a/packages/cli/src/media-use/lib/bundled-sfx-provider.mjs b/packages/cli/src/media-use/lib/bundled-sfx-provider.mjs index 6522da28a9..f30edce9e3 100644 --- a/packages/cli/src/media-use/lib/bundled-sfx-provider.mjs +++ b/packages/cli/src/media-use/lib/bundled-sfx-provider.mjs @@ -27,7 +27,7 @@ export const BUNDLED_SFX_RECOVERY_COMMAND = "npx hyperframes skills update media export class BundledSfxAssetsError extends Error { constructor(health) { super( - `bundled SFX assets are missing or incomplete (${health.detail}). Repair the installed media-use skill: ${health.fix}`, + `bundled SFX assets are missing or incomplete (${health.detail}). For the user: \`${health.fix}\` repairs the installed media-use skill.`, ); this.name = "BundledSfxAssetsError"; this.code = health.code; diff --git a/packages/cli/src/media-use/resolve.mjs b/packages/cli/src/media-use/resolve.mjs index 3bb82c299a..7eb0b573b5 100644 --- a/packages/cli/src/media-use/resolve.mjs +++ b/packages/cli/src/media-use/resolve.mjs @@ -56,7 +56,11 @@ import { flushHeygenFailureTracking, versionLessThan, } from "./lib/heygen-cli.mjs"; -import { BundledSfxAssetsError, inspectBundledSfxAssets } from "./lib/bundled-sfx-provider.mjs"; +import { + BUNDLED_SFX_RECOVERY_COMMAND, + BundledSfxAssetsError, + inspectBundledSfxAssets, +} from "./lib/bundled-sfx-provider.mjs"; import { OPENVERSE_SFX_PROVIDER } from "./lib/sfx-provider.mjs"; import { writeSfxCredit } from "./lib/openverse.mjs"; import { @@ -1150,7 +1154,13 @@ function printDoctor(checks) { const freePath = heygenChecks.has(check.name) ? " — free-usage path: bgm/image/voice/avatar-video" : ""; - const fix = check.ok || !check.fix ? "" : ` — fix: ${check.fix}`; + // Repairing a skill is the person's step, so that fix is addressed to them, not to the agent. + const fix = + check.ok || !check.fix + ? "" + : check.fix === BUNDLED_SFX_RECOVERY_COMMAND + ? ` — For the user: \`${check.fix}\` repairs it` + : ` — fix: ${check.fix}`; console.log(`${prefix} ${check.detail}${freePath}${fix}`); } } diff --git a/packages/cli/src/media-use/resolve.test.mjs b/packages/cli/src/media-use/resolve.test.mjs index 14557d7746..9c44aebcad 100644 --- a/packages/cli/src/media-use/resolve.test.mjs +++ b/packages/cli/src/media-use/resolve.test.mjs @@ -280,6 +280,23 @@ test("missing bundled SFX install returns a typed recovery command", () => { assert.equal(parsed.fix, "npx hyperframes skills update media-use"); assert.match(parsed.error, /bundled SFX assets are missing or incomplete/); assert.match(parsed.error, /manifest not found/); + // Repairing a skill is the person's step: the message names it for them, not the agent. + assert.match(parsed.error, /For the user: `npx hyperframes skills update media-use` repairs/); + assert.doesNotMatch(parsed.error, /Repair the installed/); + cleanup(); +}); + +test("--doctor addresses the bundled SFX repair to the person", () => { + setup(); + const result = spawnResolve(["--doctor"], { + env: { + HOME: tmp, + PATH: tmp, + HYPERFRAMES_MEDIA_USE_SFX_DIR: join(tmp, "missing-sfx-library"), + }, + }); + assert.match(result.stdout, /For the user: `npx hyperframes skills update media-use` repairs it/); + assert.doesNotMatch(result.stdout, /fix: npx hyperframes skills/); cleanup(); }); diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md index c89627247c..45ab10842b 100644 --- a/packages/cli/src/templates/_shared/AGENTS.md +++ b/packages/cli/src/templates/_shared/AGENTS.md @@ -25,13 +25,14 @@ MP4. > **Tailwind v4 projects** (`hyperframes init --tailwind`): see `hyperframes-cli/references/init-and-scaffold.md` (Tailwind). > **Using a HyperFrames plugin?** Load skills from that installed bundle and follow -> its `hyperframes/references/plugin-installation.md` execution rules. Update via -> the plugin manager, not the standalone commands below. +> its `hyperframes/references/plugin-installation.md` execution rules. The person updates +> the plugin through its plugin manager; the standalone commands below do not apply. > -> **Standalone skill missing or stale?** Run `npx hyperframes skills update ` to install/refresh -> the specific skill you need, or bare `npx hyperframes skills update` to refresh the core set plus -> everything already installed — neither pulls the full set. Restart the agent session so -> newly installed skills load. +> **Standalone skill missing or stale?** Installing and updating skills is the person's step: +> tell them which skill is missing or stale, and do not run the install yourself. For the user: +> `npx hyperframes skills update ` installs/refreshes that skill, and bare +> `npx hyperframes skills update` refreshes the core set plus everything already installed — +> neither pulls the full set. Newly installed skills load in a new agent session. ## Commands diff --git a/packages/cli/src/templates/_shared/CLAUDE.md b/packages/cli/src/templates/_shared/CLAUDE.md index c89627247c..45ab10842b 100644 --- a/packages/cli/src/templates/_shared/CLAUDE.md +++ b/packages/cli/src/templates/_shared/CLAUDE.md @@ -25,13 +25,14 @@ MP4. > **Tailwind v4 projects** (`hyperframes init --tailwind`): see `hyperframes-cli/references/init-and-scaffold.md` (Tailwind). > **Using a HyperFrames plugin?** Load skills from that installed bundle and follow -> its `hyperframes/references/plugin-installation.md` execution rules. Update via -> the plugin manager, not the standalone commands below. +> its `hyperframes/references/plugin-installation.md` execution rules. The person updates +> the plugin through its plugin manager; the standalone commands below do not apply. > -> **Standalone skill missing or stale?** Run `npx hyperframes skills update ` to install/refresh -> the specific skill you need, or bare `npx hyperframes skills update` to refresh the core set plus -> everything already installed — neither pulls the full set. Restart the agent session so -> newly installed skills load. +> **Standalone skill missing or stale?** Installing and updating skills is the person's step: +> tell them which skill is missing or stale, and do not run the install yourself. For the user: +> `npx hyperframes skills update ` installs/refreshes that skill, and bare +> `npx hyperframes skills update` refreshes the core set plus everything already installed — +> neither pulls the full set. Newly installed skills load in a new agent session. ## Commands diff --git a/packages/cli/src/utils/skillsUpdateCheck.test.ts b/packages/cli/src/utils/skillsUpdateCheck.test.ts index 4d73b3cc2f..c279fa618b 100644 --- a/packages/cli/src/utils/skillsUpdateCheck.test.ts +++ b/packages/cli/src/utils/skillsUpdateCheck.test.ts @@ -191,6 +191,9 @@ describe("skillsUpdateCheck", () => { gate.noTty = true; const text = await noticeTextFor({ skillsOutdatedCount: 2, skillsMissingCount: 1 }); expect(text).toContain("3 HyperFrames skills out of date or missing"); + // The agent reads stderr too: the command is the person's to run (DeltaVerdict D5). + expect(text).toContain("For the user: npx hyperframes skills update"); + expect(text).not.toMatch(/\bRun:/); }); it("prints at most once a day per project", async () => { diff --git a/packages/cli/src/utils/skillsUpdateCheck.ts b/packages/cli/src/utils/skillsUpdateCheck.ts index c9f5b2af55..01d9b110b1 100644 --- a/packages/cli/src/utils/skillsUpdateCheck.ts +++ b/packages/cli/src/utils/skillsUpdateCheck.ts @@ -113,7 +113,7 @@ function skillsNoticeText(meta: SkillsUpdateMeta): string | null { const total = meta.outdated + meta.missing; if (total < 1) return null; const noun = total === 1 ? "skill" : "skills"; - return `\n ${total} HyperFrames ${noun} out of date or missing.\n Run: npx hyperframes skills update\n\n`; + return `\n ${total} HyperFrames ${noun} out of date or missing.\n For the user: npx hyperframes skills update refreshes them.\n\n`; } /**