From 4933d4366195af8e45ac13d622239f94ab1863cd Mon Sep 17 00:00:00 2001
From: kiritowoo <295860553+kiritowoo@users.noreply.github.com>
Date: Tue, 14 Jul 2026 09:04:07 +0000
Subject: [PATCH] feat(skills): instrument general-video renders with --skill
 attribution

general-video was the only major workflow skill without render attribution
(the Jun 24 instrumentation pass missed it) -- its usage was visible only
through agents spontaneously adding the flag, undercounting a skill that
is now among the top two by volume.

Adds a dedicated 'Render (only on explicit request)' section with the
exact command, matching the pattern of the other workflow skills, and
steers away from the scaffold's npm run render (which carries no
attribution).

Live-tested with headless agent runs on an observed machine (transcript
ground truth): a checklist-only placement was NOT sufficient (agents
reproduce the command shape but drop non-functional flags); the dedicated
section with 'use exactly this command' wording carries the flag at the
same rate as the other instrumented skills. Note for future skill testing:
the self-update preamble pulls main and overwrites locally modified
copies -- strip it in test deployments.
---
 skills/general-video/SKILL.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/skills/general-video/SKILL.md b/skills/general-video/SKILL.md
index 75cf8260e2..b73bdf94c7 100644
--- a/skills/general-video/SKILL.md
+++ b/skills/general-video/SKILL.md
@@ -134,11 +134,22 @@ node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes
 
 Then read `audio_meta.json`: mount each `voices[].path` + (`bgm.path`, `sfx[]`) as `<audio>` tracks and use `voices[].words` for captions, all per `hyperframes-core` (audio tracks + caption authoring). If BGM took the generate path (`bgm_pending: true`), run `media-use/audio/scripts/wait-bgm.mjs` before final render.
 
+## Render (only on explicit request)
+
+When the user asks for an MP4, use exactly this command — including the `--skill` flag, which
+attributes the render to this workflow in anonymous usage telemetry:
+
+```bash
+npx hyperframes render --skill=general-video --quality high --output renders/video.mp4
+```
+
+Prefer this over `npm run render` (the scaffold script carries no attribution).
+
 ## Output checklist → `hyperframes-cli`
 
 - [ ] `npx hyperframes check` pass (block on results)
 - [ ] design adherence verified if a spec (`frame.md` / `design.md`) exists — checklist in `hyperframes-creative/references/design-adherence.md`
 - [ ] `npx hyperframes check` passes, or every overflow is intentionally marked
 - [ ] contrast warnings addressed; for multi-scene work, review the animation map (`hyperframes-animation/scripts/animation-map.mjs`)
-- [ ] deliver the preview; render to MP4 only on explicit request
+- [ ] deliver the preview; render to MP4 only on explicit request (command in «Render» above)
 - [ ] surface the preview **only at handoff** (it is the stable, final preview); don't pop one mid-build — build-phase snapshots are headless