From b503e5509824d4ac55d7d4f69822535a24375b83 Mon Sep 17 00:00:00 2001 From: Michael Wang Date: Wed, 4 Nov 2026 23:32:35 +0000 Subject: [PATCH] feat(skills): every published skill reports its own run (#7176) * feat(skills): every published skill reports its own run `hyperframes events --skill=` exists so a skill can say it ran, but only reverse-any-video and figma asked the agent to call it, so the other skills' use was invisible. Each of the nine published skills now opens with a one-line usage beacon naming itself. The line says what it sends (the skill's name only) and that the telemetry opt-out applies. The router's `init` line also passes `--skill=hyperframes`, so renders of new projects carry the skill. check-core-skills fails a core skill that lacks its own beacon; each core skill's size budget grows by 192 B for the line. Co-Authored-By: Claude Opus 5.5 * fix(skills): say the usage beacon goes out with the CLI's usual telemetry The beacon line said it sends only the skill's name. The events command uses the CLI's normal telemetry, which also carries machine details, the install id and, when signed in, the account. The line now says so. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- scripts/check-core-skills.mjs | 31 +++++++++++++------- scripts/check-core-skills.test.mjs | 16 ++++++++++ skills-manifest.json | 18 ++++++------ skills/figma/SKILL.md | 2 ++ skills/hyperframes-cli/SKILL.md | 2 ++ skills/hyperframes-registry/SKILL.md | 2 ++ skills/hyperframes/SKILL.md | 4 ++- skills/media-use/SKILL.md | 2 ++ skills/remotion-to-hyperframes/SKILL.md | 2 ++ skills/reverse-any-video/SKILL.md | 2 ++ skills/reverse-any-video/references/start.md | 5 ++-- skills/slideshow/SKILL.md | 2 ++ skills/style-sampling/SKILL.md | 2 ++ 13 files changed, 67 insertions(+), 23 deletions(-) diff --git a/scripts/check-core-skills.mjs b/scripts/check-core-skills.mjs index 5dba43757d..b6a127b0af 100644 --- a/scripts/check-core-skills.mjs +++ b/scripts/check-core-skills.mjs @@ -11,17 +11,18 @@ const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), ".."); // Every installed skill's description is listed on every turn; an entry is read in full when it opens. export const DESCRIPTION_MAX = 320; +// Each budget carries +192 B for the usage beacon line (`beaconProblems`). export const CORE_SKILLS = { - hyperframes: 7168, + hyperframes: 7360, // +256 B for the `_meta.updateNotice` line: the agent relays it, the person updates. - "hyperframes-cli": 7424, - "hyperframes-registry": 5120, - "media-use": 5120, - figma: 7168, - slideshow: 5120, - "remotion-to-hyperframes": 5120, - "reverse-any-video": 5120, - "style-sampling": 5120, + "hyperframes-cli": 7616, + "hyperframes-registry": 5312, + "media-use": 5312, + figma: 7360, + slideshow: 5312, + "remotion-to-hyperframes": 5312, + "reverse-any-video": 5312, + "style-sampling": 5312, }; /** @param {string} skill */ @@ -83,6 +84,16 @@ function nameProblems(skill, content, skillDir, commands) { ]; } +/** The skill's own `skill_invoked` beacon, so every run of it is counted by name. */ +export const beaconCommand = (skill) => `npx hyperframes events --skill=${skill}\``; + +/** @param {string} skill @param {string} content */ +export function beaconProblems(skill, content) { + return content.includes(beaconCommand(skill)) + ? [] + : [`${skill}/SKILL.md does not run \`npx hyperframes events --skill=${skill}\` as it starts`]; +} + /** @param {string} root */ export function checkCoreSkills(root = REPO_ROOT) { const commands = registeredCommands(readFileSync(join(root, "packages/cli/src/cli.ts"), "utf8")); @@ -90,7 +101,7 @@ export function checkCoreSkills(root = REPO_ROOT) { const file = skillFile(skill, root); const content = readFileSync(file, "utf8"); const names = maxBytes === null ? [] : nameProblems(skill, content, dirname(file), commands); - return [...sizeProblems(skill, content, maxBytes), ...names]; + return [...sizeProblems(skill, content, maxBytes), ...names, ...beaconProblems(skill, content)]; }); } diff --git a/scripts/check-core-skills.test.mjs b/scripts/check-core-skills.test.mjs index e244ed70b6..5917c7bb14 100644 --- a/scripts/check-core-skills.test.mjs +++ b/scripts/check-core-skills.test.mjs @@ -4,6 +4,7 @@ import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { + beaconProblems, checkCoreSkills, descriptionOf, missingPaths, @@ -53,6 +54,21 @@ test("reverse builds the project with init --video and asks for the run's total assert.match(read("SKILL.md"), /`init --video` put the video in/); }); +test("flags a skill that never reports its own run", () => { + assert.deepEqual( + beaconProblems("slideshow", "Run `npx hyperframes events --skill=slideshow` first."), + [], + ); + assert.equal( + beaconProblems("slideshow", "Run `npx hyperframes events --skill=figma` first.").length, + 1, + ); + assert.equal( + beaconProblems("slideshow", "`npx hyperframes events --skill=slideshow-x`").length, + 1, + ); +}); + test("reads the registered commands, quoted or not", () => { const source = `const commandLoaders = {\n init: () => x,\n "catch-up": () => y,\n};`; assert.deepEqual([...registeredCommands(source)], ["init", "catch-up"]); diff --git a/skills-manifest.json b/skills-manifest.json index b17fc312f5..1b56fdc7d3 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -2,39 +2,39 @@ "source": "heygen-com/hyperframes", "skills": { "figma": { - "hash": "0f023e6cfb3ce1d3", + "hash": "ce769362c969a9f6", "files": 2 }, "hyperframes": { - "hash": "ceaef1d1899f6fb7", + "hash": "7db75badd2151d6c", "files": 77 }, "hyperframes-cli": { - "hash": "b5b7082fbe598d2f", + "hash": "571fffd79a7d42f9", "files": 13 }, "hyperframes-registry": { - "hash": "287a62b1aa25be6a", + "hash": "a032ccc5c7948ac2", "files": 13 }, "media-use": { - "hash": "0c544b3348658b88", + "hash": "00b59a0640cb5086", "files": 118 }, "remotion-to-hyperframes": { - "hash": "a7a000334b36c7d0", + "hash": "73b82d19db2ed8c9", "files": 76 }, "reverse-any-video": { - "hash": "3dc998eaebc6f4f7", + "hash": "49f0f8041808abc6", "files": 5 }, "slideshow": { - "hash": "749dbf7d724ca04a", + "hash": "1ab359d60230a336", "files": 2 }, "style-sampling": { - "hash": "0670f6826ea02c49", + "hash": "57ab128ce08aa2ac", "files": 2 } } diff --git a/skills/figma/SKILL.md b/skills/figma/SKILL.md index dce7c4de0e..2978b51309 100644 --- a/skills/figma/SKILL.md +++ b/skills/figma/SKILL.md @@ -5,6 +5,8 @@ description: Bring Figma into a HyperFrames video - rendered assets, brand token **Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Usage beacon:** run `npx hyperframes events --skill=figma` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. + # Figma → HyperFrames Every import happens at build time and freezes a local file with its source recorded under `.media/`, so renders never call Figma and re-running a command re-imports only what changed. Assets, tokens and components go over REST with a token; motion and shader data need a Figma connector, or a native export from the person. diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index 43afdb9adf..ae0300e623 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -5,6 +5,8 @@ description: The HyperFrames CLI by job - scaffold, check, look at frames, edit **Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Usage beacon:** run `npx hyperframes events --skill=hyperframes-cli` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. + # HyperFrames CLI Run `npx hyperframes ` unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has `--help`; most take `--json`, and a failure prints `✗ …`, a `Fix:` line and exits non-zero. diff --git a/skills/hyperframes-registry/SKILL.md b/skills/hyperframes-registry/SKILL.md index 3db24f9e47..f03773cfcd 100644 --- a/skills/hyperframes-registry/SKILL.md +++ b/skills/hyperframes-registry/SKILL.md @@ -5,6 +5,8 @@ description: About 450 ready-made HyperFrames blocks and components installed as **Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Usage beacon:** run `npx hyperframes events --skill=hyperframes-registry` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. + # HyperFrames registry Starting from an item is faster and usually better than writing the effect yourself, and an installed item is ordinary source in your project: change it, cut it down, restyle it. diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index bebb5cdf3c..e7d20ca595 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -5,11 +5,13 @@ description: Read first to make, edit, animate or render any video with HyperFra **Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](references/plugin-installation.md). +**Usage beacon:** run `npx hyperframes events --skill=hyperframes` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. + # HyperFrames HyperFrames renders HTML to video by seeking a paused timeline frame by frame, so every render is identical; the person edits the same files in the Studio preview. Use it unless another framework or a plain browser recording is asked for. Run the CLI as `npx hyperframes ` (`/hyperframes-cli`); at the start of a new video, `npx hyperframes usage --json` reports the person's remaining plan usage (say "unknown" when it is). -`index.html` is the root composition: it declares the video's variables and mounts one scene per sub-composition from `compositions/`. Media and fonts live in `assets/`. A new project: `npx hyperframes init --skip-skills`. A website as the subject: `npx hyperframes capture --json`. +`index.html` is the root composition: it declares the video's variables and mounts one scene per sub-composition from `compositions/`. Media and fonts live in `assets/`. A new project: `npx hyperframes init --skip-skills --skill=hyperframes`. A website as the subject: `npx hyperframes capture --json`. Build what was asked: no voiceover or captions and no new aspect ratio unless the request or the source calls for them; a film over ~15 s that tells something gets music and sound on its visible actions unless the person asked for silence (`references/sound.md`). A new video is 1920×1080 at 30 fps. A question, a hold or a loose idea gets an answer or a proposal, not an edit. Before hand-writing a named effect, transition, caption style, chart or card, search the registry (`/hyperframes-registry`). Any media (a presenter or avatar, footage, voice, music): `/media-use`, which says when HeyGen is needed and what is free. Show real things from their source (the product's screens, the brand's logo, a real place's imagery); draw only what has none. diff --git a/skills/media-use/SKILL.md b/skills/media-use/SKILL.md index be4c5e177a..40861a71bb 100644 --- a/skills/media-use/SKILL.md +++ b/skills/media-use/SKILL.md @@ -5,6 +5,8 @@ description: Get or make any media for a HyperFrames video - music, sound effect **Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Usage beacon:** run `npx hyperframes events --skill=media-use` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. + # Media in HyperFrames Media lands as a local file in the project's `assets/` with a ledger record; renders never fetch. One verb finds or makes it: diff --git a/skills/remotion-to-hyperframes/SKILL.md b/skills/remotion-to-hyperframes/SKILL.md index 5a0d36c06a..df4fb15cf8 100644 --- a/skills/remotion-to-hyperframes/SKILL.md +++ b/skills/remotion-to-hyperframes/SKILL.md @@ -5,6 +5,8 @@ description: Bring existing video code or footage into HyperFrames and verify it **Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Usage beacon:** run `npx hyperframes events --skill=remotion-to-hyperframes` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. + # Import into HyperFrames HyperFrames is the container: its tracks, sub-compositions and variables are editable in Studio whatever runs inside a clip. Bring each part in at the highest level it supports and record which level you used. diff --git a/skills/reverse-any-video/SKILL.md b/skills/reverse-any-video/SKILL.md index 9be05d436c..1ac23d5318 100644 --- a/skills/reverse-any-video/SKILL.md +++ b/skills/reverse-any-video/SKILL.md @@ -5,6 +5,8 @@ description: Rebuild any video file as an editable HyperFrames project - motion **Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Usage beacon:** run `npx hyperframes events --skill=reverse-any-video` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. + # Reverse a video The result is a HyperFrames project whose render matches the original frame for frame and stays editable. Build to the `/hyperframes` contract and work the way you normally would, with ffmpeg, python and your own eyes. Reverse videos the person has the right to use. diff --git a/skills/reverse-any-video/references/start.md b/skills/reverse-any-video/references/start.md index 69ebe855be..825214136f 100644 --- a/skills/reverse-any-video/references/start.md +++ b/skills/reverse-any-video/references/start.md @@ -5,9 +5,8 @@ their language, warm and short, no file names, step numbers or tool names. They and any page they need (sign-in, upgrade, add-on credits) goes in your message as a plain link they can click, in case the browser did not open. -For you, not them: run `npx hyperframes events --skill=reverse-any-video` as you start, and -`npx hyperframes events --skill=reverse-any-video --event=skill_completed --outcome=success` when you hand over the -video (`--outcome=error` when you stop without one). +For you, not them: run `npx hyperframes events --skill=reverse-any-video --event=skill_completed --outcome=success` +when you hand over the video (`--outcome=error` when you stop without one). Also for you: `npx hyperframes reverse start