Skip to content

Commit 6857bb0

Browse files
Vitozhu04claude
andauthored
docs(skills): stop directing the agent to install, update or remove skills (#7102)
A third-party skill-trust grader (DeltaVerdict D5) fails any skill text that has the agent modify its own skills, even when disclosed or gated on the user. Reword the skill lifecycle, plugin, CLI and scaffold text so it states facts the agent can relay (skills are versioned with the CLI; the person installs and updates them, and which command does it) instead of commands for the agent to run. Every agent-run `init` example passes --skip-skills, since init otherwise installs missing core skills; the plugin header, plugin-cli and sfx messages are person-addressed; the person's install commands are marked as theirs; /style-sampling joins the on-demand lists. Regenerate skills-manifest.json and update the pinned reverse init regex. Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent e04b722 commit 6857bb0

17 files changed

Lines changed: 57 additions & 57 deletions

File tree

‎scripts/check-core-skills.test.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ test("reverse builds the project with init --video and asks for the run's total
4343
const start = read("references/start.md");
4444
assert.match(
4545
start,
46-
/`npx hyperframes init <project> --video <video> --keep-original --skip-transcribe`/,
46+
/`npx hyperframes init <project> --video <video> --keep-original --skip-transcribe --skip-skills`/,
4747
);
4848
assert.match(
4949
start,

‎skills-manifest.json‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,39 +2,39 @@
22
"source": "heygen-com/hyperframes",
33
"skills": {
44
"figma": {
5-
"hash": "af57c9b6411c81f5",
5+
"hash": "0f023e6cfb3ce1d3",
66
"files": 2
77
},
88
"hyperframes": {
9-
"hash": "12d5d6dc2258dbcb",
9+
"hash": "c7c2479d8aee134b",
1010
"files": 77
1111
},
1212
"hyperframes-cli": {
13-
"hash": "ce9f4c1ff4fcb4ee",
13+
"hash": "3c21101c387ca6c3",
1414
"files": 13
1515
},
1616
"hyperframes-registry": {
17-
"hash": "449c8ee5190d9044",
17+
"hash": "287a62b1aa25be6a",
1818
"files": 13
1919
},
2020
"media-use": {
21-
"hash": "7598d83dcc385308",
21+
"hash": "732e7fea80a421cf",
2222
"files": 118
2323
},
2424
"remotion-to-hyperframes": {
25-
"hash": "1775bffb149795f6",
25+
"hash": "a7a000334b36c7d0",
2626
"files": 76
2727
},
2828
"reverse-any-video": {
29-
"hash": "4a4cce69e724e838",
29+
"hash": "3dc998eaebc6f4f7",
3030
"files": 5
3131
},
3232
"slideshow": {
33-
"hash": "c8a591e2aa7a6d86",
33+
"hash": "749dbf7d724ca04a",
3434
"files": 2
3535
},
3636
"style-sampling": {
37-
"hash": "d85dc18bb2852a19",
37+
"hash": "99809938d12ad2c4",
3838
"files": 2
3939
}
4040
}

‎skills/figma/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: figma
33
description: Bring Figma into a HyperFrames video - rendered assets, brand tokens, components, storyboard frames as reconstructed motion (frames read as states, not slides), shaders and connector-assisted motion. Use when the person pastes a figma.com link or asks to use a Figma design, frame, logo or brand.
44
---
55

6-
**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.
6+
**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md).
77

88
# Figma → HyperFrames
99

‎skills/hyperframes-cli/SKILL.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: hyperframes-cli
33
description: The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
44
---
55

6-
**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.
6+
**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md).
77

88
# HyperFrames CLI
99

@@ -15,7 +15,7 @@ A `--json` result may carry `_meta.updateNotice`: a newer HyperFrames release is
1515

1616
| Job | Commands |
1717
| --- | --- |
18-
| Start | `init <dir>` (blank; `--example <name>` only when asked), `capture <url>` |
18+
| Start | `init <dir> --skip-skills` (blank; `--example <name>` only when asked), `capture <url>` |
1919
| Read a project | `info`, `compositions`, `timeline --json`, `docs <topic>` |
2020
| Check it | `lint` while writing; `check --json` as the gate (lint, runtime, layout, contrast) |
2121
| Look at it | `snapshot` (`--at <t,…>`, `--range START,END`, `--composition <id>`, `--zoom`, `--angle`, `--against <video>`), `keyframes`, `compare`, `audio` |
@@ -24,7 +24,7 @@ A `--json` result may carry `_meta.updateNotice`: a newer HyperFrames release is
2424
| Media and sound | `media-treatment`, `grade-compare`, `remove-background`, `tts`, `transcribe`, `beats`, `normalize-audio` (`/media-use`) |
2525
| Show and ship | `preview`, `present` (`/slideshow`), `render`, `publish`, `cloud`, `lambda`, `cloudrun` |
2626
| Desktop app | `open`, `catch-up` |
27-
| Upkeep | `doctor`, `browser`, `upgrade`, `skills`, `usage`, `clean`, `feedback` |
27+
| Upkeep | `doctor`, `browser`, `upgrade`, `usage`, `clean`, `feedback` |
2828

2929
`validate`, `inspect` and `layout` are deprecated aliases of `check`; `events` is telemetry for skills' own scripts. Don't run them.
3030

‎skills/hyperframes-cli/references/init-and-scaffold.md‎

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,18 @@
22

33
<!-- registry-items: allow=blank,landscape-4k,portrait-4k,square-4k,media-use -->
44

5-
Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, run transcription, and install AI coding skills.
5+
Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, and run transcription.
66

77
## init
88

99
```bash
10-
npx hyperframes init my-video # centered blank (TTY: wizard)
11-
npx hyperframes init my-video --example warm-grain # pick an example
12-
npx hyperframes init my-video --resolution portrait
13-
npx hyperframes init my-video --video clip.mp4 # with video file
14-
npx hyperframes init my-video --audio track.mp3 # with audio file
15-
npx hyperframes init my-video --tailwind # Tailwind v4 browser runtime
16-
npx hyperframes init my-video --non-interactive # CI — flag-only, same blank
10+
npx hyperframes init my-video --skip-skills # centered blank (TTY: wizard)
11+
npx hyperframes init my-video --skip-skills --example warm-grain # pick an example
12+
npx hyperframes init my-video --skip-skills --resolution portrait
13+
npx hyperframes init my-video --skip-skills --video clip.mp4 # with video file
14+
npx hyperframes init my-video --skip-skills --audio track.mp3 # with audio file
15+
npx hyperframes init my-video --skip-skills --tailwind # Tailwind v4 browser runtime
16+
npx hyperframes init my-video --skip-skills --non-interactive # CI — flag-only, same blank
1717
```
1818

1919
**Default depends on TTY**: in a terminal, the CLI prompts for example/options (default: centered blank). Outside a TTY (CI, agents, piped output) it auto-switches to non-interactive and scaffolds that blank. Pass `--example` only to start from a named example. Pass `--non-interactive` to force flag-only mode on a TTY.
@@ -24,7 +24,7 @@ Other useful flags:
2424

2525
- `--resolution` — preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k`, `portrait-4k`, `square` (1080×1080), `square-4k`. Aliases: `1080p`, `4k`, `uhd`, `1080p-square`, `4k-square`.
2626
- `--skill=<slug>` — record the owning skill (e.g. `hyperframes`) in `hyperframes.json`, so every later render of this project — re-renders, `npm run render`, `--batch` — is attributed to it on usage telemetry without re-passing the flag. You rarely pass it by hand.
27-
- `--skip-skills` — leave AI coding skills alone: `init` does not install the core set. `HYPERFRAMES_SKIP_SKILLS=1` does the same.
27+
- `--skip-skills` — leave AI coding skills alone: `init` does not install the core set. `HYPERFRAMES_SKIP_SKILLS=1` does the same. Always pass it: without it `init` installs any missing core skill, and installing skills is the person's step. When a core skill is missing, tell the person they can install it with `npx hyperframes skills update`.
2828
- `--skip-transcribe` — don't auto-transcribe `--audio` / `--video` with Whisper.
2929
- `--model`, `--language` — Whisper model / language for the auto-transcription.
3030

@@ -72,8 +72,4 @@ into a fresh output directory; never merge or reuse a blocked attempt's partial
7272

7373
## skills
7474

75-
```bash
76-
npx hyperframes skills # install HyperFrames skills for AI coding tools
77-
```
78-
79-
One-time setup that adds the HyperFrames skill pack (/hyperframes with its references, /hyperframes-cli, /hyperframes-registry, /media-use, /figma, /slideshow, /remotion-to-hyperframes, /reverse-any-video) to the local AI coding environment so agents follow the framework conventions. Re-run after major HyperFrames upgrades.
75+
`npx hyperframes skills` is the person's one-time setup: it adds the HyperFrames skill pack (/hyperframes with its references, /hyperframes-cli, /hyperframes-registry, /media-use, /figma, /slideshow, /remotion-to-hyperframes, /reverse-any-video, /style-sampling) to the local AI coding environment so agents follow the framework conventions. Skills are versioned with the CLI; after a HyperFrames upgrade the person can refresh them with `npx hyperframes skills update`. Tell them when that applies; do not run it yourself.

‎skills/hyperframes-registry/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: hyperframes-registry
33
description: About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.
44
---
55

6-
**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.
6+
**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md).
77

88
# HyperFrames registry
99

‎skills/hyperframes/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@ name: hyperframes
33
description: Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.
44
---
55

6-
**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](references/plugin-installation.md) when this skill is inside a HyperFrames plugin.
6+
**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](references/plugin-installation.md).
77

88
# HyperFrames
99

1010
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).
1111

12-
`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>`. A website as the subject: `npx hyperframes capture <url> --json`.
12+
`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`.
1313

1414
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.
1515

‎skills/hyperframes/references/plugin-installation.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,10 @@
33
Check the directory two levels above the loaded `SKILL.md` for `plugin.json`,
44
`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, or
55
`.cursor-plugin/plugin.json` identifying `hyperframes`, or a Gemini extension manifest.
6-
That directory is `<PLUGIN_ROOT>`. If none exists, this is a standalone skill;
7-
follow the normal installation and freshness instructions.
6+
That directory is `<PLUGIN_ROOT>`. If none exists, this is a standalone skill
7+
install; run `npx hyperframes` directly.
88

9-
For a plugin installation, these rules replace the standalone update commands
10-
in every skill and reference:
9+
For a plugin installation, these rules apply in every skill and reference:
1110

1211
- Do not run `hyperframes skills update`, `skills check`, or `npx skills add`.
1312
The agent's plugin manager owns installation and updates. Read the skill at
@@ -37,7 +36,7 @@ in every skill and reference:
3736
project or a temporary directory. Pass this plugin root and launcher convention
3837
to any delegated agent so it does not fall back to global skills.
3938

40-
To get newer skills, use the client's plugin update flow and reload the session.
41-
Do not silently update an installed plugin during a video task.
39+
Newer skills come through the client's plugin update flow and a session reload,
40+
which the person runs. Do not update an installed plugin yourself.
4241

4342
The launcher suppresses CLI update notices as well as standalone skill refreshes, including when running an older CLI with a stale notice cache. It passes the release as `HYPERFRAMES_PLUGIN_VERSION` for plugin-aware helpers and as `HYPERFRAMES_SKILL_PKG_VERSION` for the existing helper-package bootstrap. Our release process versions those packages together.

‎skills/hyperframes/references/skill-lifecycle.md‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
# Skill installation and freshness
22

3-
Read this reference when installing or updating skills, diagnosing unexpected skill behavior, or running HyperFrames setup in CI.
3+
Read this reference when the person asks about installing or updating skills, when diagnosing unexpected skill behavior, or when setting up HyperFrames in CI (see `HYPERFRAMES_SKIP_SKILLS` below). Skills are versioned with the CLI. Installing, updating and removing them is the person's step: tell them what is out of date and which command fits, and do not run it yourself.
44

55
For a plugin installation, follow [plugin execution rules](plugin-installation.md); the plugin manager owns updates and every skill is bundled. The commands below apply only to standalone skills.
66

7-
- **Core set, installed eagerly:** `/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry` and `/media-use`.
8-
- **On demand:** `/figma`, `/slideshow`, `/remotion-to-hyperframes` and `/reverse-any-video`, installed with `npx hyperframes skills update <name>`.
7+
- **Core set:** `/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry` and `/media-use`.
8+
- **On demand:** `/figma`, `/slideshow`, `/remotion-to-hyperframes`, `/reverse-any-video` and `/style-sampling`, which the person installs with `npx hyperframes skills update <name>`.
99

1010
## What `init` does
1111

12-
`npx hyperframes init` installs the core set when it is missing and leaves every skill that is already installed as it is: it never refreshes, replaces or removes one. Updating is `npx hyperframes skills update`, run by you. Offline or rate-limited checks degrade gracefully and do not fail project scaffolding.
12+
Without `--skip-skills`, `npx hyperframes init` installs the core set when it is missing and leaves every skill that is already installed as it is: it never refreshes, replaces or removes one. Installing the core set is the person's step, so pass `--skip-skills` whenever you run `init`. When a core skill is missing, tell the person to run `npx hyperframes skills update`, which also updates the skills already installed. Offline or rate-limited checks degrade gracefully and do not fail project scaffolding.
1313

1414
`--skip-skills` makes `init` leave skills alone. `HYPERFRAMES_SKIP_SKILLS=1` does the same for CI and tests.
1515

@@ -19,24 +19,29 @@ For a plugin installation, follow [plugin execution rules](plugin-installation.m
1919

2020
After `render`, `lint` and `validate`, the CLI prints `N HyperFrames skills out of date or missing` to stderr when the cached check finds stale skills, so an agent run without a terminal sees it too. It is off in CI, in dev, with `HYPERFRAMES_NO_UPDATE_CHECK=1` and with `HYPERFRAMES_SKIP_SKILLS=1`, and runs with `--json` too, since it only writes stderr and leaves `--json` stdout untouched.
2121

22-
## Diagnose and update
22+
## Diagnose, and what the person can run
2323

2424
```bash
2525
npx hyperframes skills check
2626
npx hyperframes skills check --json
27-
npx hyperframes skills update
28-
npx hyperframes skills update <name>
29-
npx hyperframes skills
27+
```
28+
29+
The person's install and update commands, to name when you relay a stale result:
30+
31+
```bash
32+
npx hyperframes skills update # the person runs this
33+
npx hyperframes skills update <name> # the person runs this
34+
npx hyperframes skills # the person runs this
3035
```
3136

3237
- `skills check` exits non-zero when an installed skill is stale or the core set is incomplete. Skills available on demand but not installed are not failures.
3338
- Bare `skills update` refreshes the core set and the HyperFrames skills already installed. It never removes a skill, and it leaves a skill the install record attributes to another publisher alone, even when the name matches one of ours.
3439
- Named `skills update <name...>` also installs those named skills.
3540
- Bare `skills` installs the full published set explicitly.
3641

37-
If the HyperFrames CLI is unavailable, use `npx skills add heygen-com/hyperframes --skill <name>` for one skill or `npx skills add heygen-com/hyperframes --all` for the full published set.
42+
If the HyperFrames CLI is unavailable, the person can install with `npx skills add heygen-com/hyperframes --skill <name>` for one skill or `npx skills add heygen-com/hyperframes --all` for the full published set.
3843

39-
The CLI may print a one-line stale-skill reminder during `render`, `lint`, or `check`. Treat a failed update as a visible tool failure; do not continue from a remembered skill.
44+
The CLI may print a one-line stale-skill reminder during `render`, `lint`, or `check`. Relay it to the person and keep working from the installed skills; do not continue from a remembered skill.
4045

4146
## Keep the project's CLI current
4247

‎skills/hyperframes/scripts/plugin-cli.mjs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export function pluginVersion(pluginRoot = root) {
2929
return manifest.version;
3030
}
3131
throw new Error(
32-
"No HyperFrames plugin manifest found. Use the standalone skills installation instructions.",
32+
"No HyperFrames plugin manifest found. This is a standalone skill install; run `npx hyperframes` directly.",
3333
);
3434
}
3535

@@ -45,7 +45,7 @@ export function invocation(
4545
) {
4646
if (args[0] === "skills")
4747
throw new Error(
48-
"Update HyperFrames through your agent's plugin manager; bundled skills are release-managed.",
48+
"Bundled skills are release-managed; the person updates HyperFrames through their agent's plugin manager.",
4949
);
5050
const childEnv = {
5151
...env,

0 commit comments

Comments
 (0)