Skip to content

Commit c8300c6

Browse files
fix(cli): install the published skill set, not every SKILL.md in the repo (#3636)
Bare `hyperframes skills` passed `--skill '*'` to the upstream installer, which discovers every SKILL.md in the clone, so a full install put 26 skills on disk against the 20 the manifest publishes (the six repo-internal ones under .claude/skills / .agents/skills). It now resolves the canonical manifest and installs its names, the same path `skills update` uses; offline it warns and degrades to the pinned core set instead of the wildcard. Docs point the full set at `npx hyperframes skills` and say what `skills add --all` really pulls.
1 parent c5224ac commit c8300c6

7 files changed

Lines changed: 72 additions & 13 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ This repo ships AI agent skills via [vercel-labs/skills](https://github.com/verc
88

99
```bash
1010
npx hyperframes skills update # default: installs/refreshes the core set — workflows install on demand
11-
npx skills add heygen-com/hyperframes # interactive picker (terminal only — non-interactive without --skill installs everything)
11+
npx hyperframes skills # all 20 published skills at once
12+
npx skills add heygen-com/hyperframes # interactive picker (terminal only; --all also pulls the repo-internal skills under .claude/skills)
1213
```
1314

1415
**Creation workflows** route through one entry skill — read `/hyperframes` first: it orients you to the whole surface, confirms the brief up front (the intent layer), and maps "make me a…" intent — usually a video, but also a navigable deck (`/slideshow`) or a composition port (`/remotion-to-hyperframes`) — to a concrete workflow. Consult it before invoking a specific workflow:

‎CLAUDE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ This repo ships 20 AI agent skills via [vercel-labs/skills](https://github.com/v
88

99
```bash
1010
npx hyperframes skills update # default: installs/refreshes the core set — workflows install on demand
11-
npx skills add heygen-com/hyperframes # interactive picker (terminal only — non-interactive without --skill installs all 20)
12-
npx skills add heygen-com/hyperframes --all # all 20 at once — only on explicit request
11+
npx hyperframes skills # all 20 published skills at once — only on explicit request
12+
npx skills add heygen-com/hyperframes # interactive picker (terminal only; --all also pulls the 6 repo-internal skills under .claude/skills)
1313
npx skills add heygen-com/hyperframes --skill <name> # just one (bare name, no leading slash)
1414
```
1515

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ Install the HyperFrames skills, then describe the video you want:
4141
npx skills add heygen-com/hyperframes
4242
```
4343

44-
> The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas a non-interactive `skills add` without `--skill` installs all 20.
44+
> The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow 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 every `SKILL.md` in the repo — the 20 published skills plus six repo-internal ones under `.claude/skills` / `.agents/skills`. For the full published set use `npx hyperframes skills`.
4545
>
4646
> `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs from the current `main`, so reach for it when you need the newest copy of a skill.
4747

‎docs/guides/skills.mdx‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -110,12 +110,14 @@ You can invoke a workflow directly when you already know it is the right one, bu
110110

111111
## Install more only when you need it
112112

113-
Install the complete set deliberately with:
113+
Install the complete published set deliberately with:
114114

115115
```bash
116-
npx skills add heygen-com/hyperframes --all
116+
npx hyperframes skills
117117
```
118118

119+
(`npx skills add heygen-com/hyperframes --all` also works, but it installs every `SKILL.md` in the repository, including repo-internal skills that are not part of the published set.)
120+
119121
Or install one named skill:
120122

121123
```bash

‎docs/prompting/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ The installer shows a picker. Select the **core skills** below — every project
7272
| `/figma` | A Figma file / frame / URL → imported assets, brand tokens, and reconstructed motion |
7373

7474
<Tip>
75-
To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all`. And start HyperFrames prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents) — it loads the routing + composition context explicitly so the agent picks the right workflow and gets the rules right the first time.
75+
To skip the picker and install everything (core + every workflow) in one shot, run `npx hyperframes skills`. And start HyperFrames prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents) — it loads the routing + composition context explicitly so the agent picks the right workflow and gets the rules right the first time.
7676
</Tip>
7777

7878

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

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,11 @@ describe("hyperframes skills", () => {
240240
"add",
241241
"https://github.com/heygen-com/hyperframes",
242242
"--skill",
243-
"*",
243+
"hyperframes",
244+
"--skill",
245+
"hyperframes-core",
246+
"--skill",
247+
"pr-to-video",
244248
...GLOBAL_ARGS_TAIL,
245249
],
246250
],
@@ -253,7 +257,11 @@ describe("hyperframes skills", () => {
253257
"add",
254258
"https://github.com/heygen-com/hyperframes",
255259
"--skill",
256-
"*",
260+
"hyperframes",
261+
"--skill",
262+
"hyperframes-core",
263+
"--skill",
264+
"pr-to-video",
257265
...GLOBAL_ARGS_TAIL,
258266
],
259267
],
@@ -270,7 +278,11 @@ describe("hyperframes skills", () => {
270278
"add",
271279
"https://github.com/heygen-com/hyperframes",
272280
"--skill",
273-
"*",
281+
"hyperframes",
282+
"--skill",
283+
"hyperframes-core",
284+
"--skill",
285+
"pr-to-video",
274286
...GLOBAL_ARGS_TAIL,
275287
],
276288
],
@@ -799,6 +811,30 @@ describe("hyperframes skills update <names>", () => {
799811
expect(await commandExitCode()).toBe(0);
800812
});
801813

814+
it("bare `skills` offline never falls back to the wildcard: warns and installs the pinned core set", async () => {
815+
setPlatform("linux");
816+
const { checkSkills, presentSkills, FALLBACK_CORE_SKILLS } =
817+
await import("../utils/skillsManifest.js");
818+
const clack = await import("@clack/prompts");
819+
vi.mocked(clack.log.warn).mockClear();
820+
vi.mocked(checkSkills).mockRejectedValue(new Error("offline"));
821+
vi.mocked(presentSkills)
822+
.mockImplementationOnce(() => [])
823+
.mockImplementation((names: readonly string[]) => [...names]);
824+
825+
const { default: skillsCmd } = await import("./skills.js");
826+
await skillsCmd.run?.({ args: {}, rawArgs: [], cmd: skillsCmd } as never);
827+
828+
const args = state.spawnCalls[0]?.args ?? [];
829+
// The upstream `*` would rediscover the repo-internal skills (26 vs 20).
830+
expect(skillFlagValues(args)).not.toContain("*");
831+
expect(skillFlagValues(args).sort()).toEqual([...FALLBACK_CORE_SKILLS].sort());
832+
expect(vi.mocked(clack.log.warn)).toHaveBeenCalledWith(
833+
expect.stringContaining("published skill set"),
834+
);
835+
expect(await commandExitCode()).toBe(0);
836+
});
837+
802838
// The `check || update` CI contract: offline, a bare update can't verify
803839
// freshness — exiting 0 would let the chain pass while everything stays
804840
// stale. It must fail loudly instead.

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

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -301,7 +301,12 @@ export interface UpdateSkillsResult {
301301
* - the requested names (a workflow being routed to, e.g. `pr-to-video`),
302302
* - the core set (entry router + shared domain skills — see skillsManifest),
303303
* - with `refreshInstalled`, whatever is already installed (refreshed, so an
304-
* update never *expands* a deliberate partial install).
304+
* update never *expands* a deliberate partial install),
305+
* - with `all`, every skill the manifest publishes. The upstream `*` wildcard
306+
* is not used on any path: it also sweeps up the repo-internal skills under
307+
* `.claude/skills` / `.agents/skills` (26 installed vs 20 published,
308+
* observed 2026-09-04). Offline, where the published set is unknowable, the
309+
* full install warns and degrades to the pinned core set instead.
305310
*
306311
* Only targets that are actually missing or outdated are passed to
307312
* `skills add` (one spawn, one `--skill` flag per name); when everything is
@@ -313,6 +318,8 @@ export async function updateSkills(
313318
opts: {
314319
requested?: readonly string[];
315320
refreshInstalled?: boolean;
321+
/** Every skill the manifest publishes (bare `hyperframes skills`). */
322+
all?: boolean;
316323
strict?: boolean;
317324
cwd?: string;
318325
} = {},
@@ -347,7 +354,19 @@ export async function updateSkills(
347354
}
348355
check = null; // manifest unreachable (offline / rate-limited) — presence mode below
349356
}
350-
if (!check) return updateSkillsOffline(requested, { strict, cwd: opts.cwd });
357+
if (!check) {
358+
if (opts.all) {
359+
// The published set is unknowable offline. Say so and degrade to the
360+
// pinned core set — never the upstream wildcard, which would quietly
361+
// reinstate the 26-skill sweep this path exists to avoid.
362+
clack.log.warn(
363+
c.warn(
364+
"Can't resolve the published skill set (manifest unreachable) — installing the pinned core set only. Re-run `hyperframes skills` online for the full set.",
365+
),
366+
);
367+
}
368+
return updateSkillsOffline(requested, { strict, cwd: opts.cwd });
369+
}
351370

352371
// "removed" entries are lock-attributed leftovers, not manifest skills —
353372
// they are `skills update`'s prune concern, never an update target.
@@ -365,6 +384,7 @@ export async function updateSkills(
365384

366385
const targets = manifestSkills.filter(
367386
(s) =>
387+
opts.all === true ||
368388
requested.includes(s.name) ||
369389
isCoreSkill(s.name) ||
370390
(opts.refreshInstalled === true && s.status !== "missing"),
@@ -785,7 +805,7 @@ export default defineCommand({
785805
// the positional so bare `hyperframes skills` installs, while
786806
// `hyperframes skills check|update` does not also re-install.
787807
if (!args._?.[0]) {
788-
await installSkills("*");
808+
await updateSkills({ all: true });
789809
// Same as updateSkills: a full install supersedes the background
790810
// nudge's cached pre-install verdict.
791811
invalidateSkillsCache();

0 commit comments

Comments
 (0)