feat(skills): every published skill reports its own run (#7176)

* feat(skills): every published skill reports its own run

`hyperframes events --skill=<name>` 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michael Wang
2026-11-04 23:32:35 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent fa318d9727
commit b503e55098
13 changed files with 67 additions and 23 deletions
+21 -10
View File
@@ -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)];
});
}
+16
View File
@@ -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"]);
+9 -9
View File
@@ -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
}
}
+2
View File
@@ -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.
+2
View File
@@ -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 <command>` 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.
+2
View File
@@ -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.
+3 -1
View File
@@ -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 <command>` (`/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 <dir> --skip-skills`. A website as the subject: `npx hyperframes capture <url> --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 <dir> --skip-skills --skill=hyperframes`. A website as the subject: `npx hyperframes capture <url> --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.
+2
View File
@@ -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:
+2
View File
@@ -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.
+2
View File
@@ -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.
+2 -3
View File
@@ -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 <video> --dir <project>` prints the video's probe and a `reverse` field.
`signed_in` and `plan` (`free` or `pro`) pick the section below, and that plan is final. Only a `null` plan is unknown:
+2
View File
@@ -5,6 +5,8 @@ description: Build a HyperFrames slideshow to present live - slides, fragment re
**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md).
**Usage beacon:** run `npx hyperframes events --skill=slideshow` 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 slideshow
A slideshow is a normal composition (the `/hyperframes` contract applies) plus one JSON island that says which scenes are slides and how they connect. The deliverable is a running deck, not an MP4.
+2
View File
@@ -5,6 +5,8 @@ description: Make a new episode in a proven video style - Collage Explainer, Fin
**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md).
**Usage beacon:** run `npx hyperframes events --skill=style-sampling` 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.
# A new episode from a style template
A good episode is one the series' own viewers would take for the next upload: its structure, pacing, look, graphics and sound, on a new topic, in the person's voice and, when the series has a presenter, their own face. Never use a creator's face, voice, footage, logo or show name.