Skip to content

docs(skills): say a variable must be declared before data-var-* binds it - #7693

Open
wonjangcloud9 wants to merge 1 commit into
heygen-com:mainfrom
wonjangcloud9:docs/skill-variables-declare
Open

wonjangcloud9 wants to merge 1 commit into
heygen-com:mainfrom
wonjangcloud9:docs/skill-variables-declare

Conversation

@wonjangcloud9

Copy link
Copy Markdown
Contributor

Context: I've been using HyperFrames every day for the past two weeks to make Korean Shorts and long-form videos, and it's been great to work with. This PR is one of a batch of fixes for things I ran into along the way, so you'll see several PRs from me at once — sorry for the pile-up, and thanks for your patience. Each one is reproduced on current main, independent of the others, and can be reviewed, merged or closed on its own.

What

  • skills/hyperframes/SKILL.md ("Keep it editable"): "Copy, brand colours and swappable media are variables (data-var-text, data-var-src, var(--id))." → "…are variables: declare each in data-composition-variables, then bind it (data-var-text, data-var-src, var(--id))."
  • skills/hyperframes/references/format.md (Variables): the declare bullet names the attribute (data-composition-variables), the type list adds font and image (both in CompositionVariableType, missing here) and says a video or audio link is a string, and a new bullet says an undeclared bound id silently keeps its fallback (unknown_variable_binding) with a one-line declare-then-bind example.
  • scripts/check-core-skills.mjs: hyperframes entry budget 7488 → 7552 B (+64 B, with the usual one-line reason). The entry was at 7481 B, so the new words did not fit otherwise.
  • Regenerated skills-manifest.json; one test in coreSkillContent.test.ts.

Why

An agent following the SKILL.md line literally writes <h1 data-var-text="headline">Title</h1> and stops there. On main:

$ hyperframes check --no-cache --json
warning unknown_variable_binding  <h1> binds data-var-text="headline" but no variable "headline" is declared in data-composition-variables, so the binding will silently keep the authored fallback.

The lint catches it and its fix hint is right, but the skill sent the agent there: neither SKILL.md nor format.md's Variables section named the attribute (only the skeleton at the top of format.md shows it). With the declaration added, the same project checks clean (no unknown_variable_binding) and the snapshot shows the variable's default Hello instead of the authored Title.

Related work

No existing issue or PR. Lint rule from #2054 (declarative bindings).

How

Docs only, plus the budget bump. The example lives in format.md rather than SKILL.md to keep the entry within budget.

Test plan

  • Reproduced on main (above); verified the documented declare-then-bind form on a real project: check has no unknown_variable_binding, snapshot at 1 s shows Hello.
  • coreSkillContent.test.ts: new case asserts SKILL.md names `data-composition-variables` and format.md names `unknown_variable_binding`; fails on main's docs, passes here (15/15 in the file).
  • node scripts/check-core-skills.mjs ✓ (7541 / 7552 B), node --test scripts/check-core-skills.test.mjs 12/12, bun scripts/lint-skills.ts no issues, check-skill-mirror OK, oxfmt/oxlint clean, manifest regenerated.
  • Documentation updated (this is the documentation)
  • Comments follow CONTRIBUTING.md "Comments"

Note for merging: this and the immediateRender: false skill PR both change the hyperframes hash in the generated skills-manifest.json; whichever lands second needs bun packages/cli/scripts/gen-skills-manifest.ts after rebasing. Nothing else overlaps.

🤖 Generated with Claude Code

SKILL.md said copy, brand colours and swappable media are variables
(`data-var-text`, `data-var-src`, `var(--id)`) without the step that makes
them variables: declaring each in data-composition-variables. Following it
gives unknown_variable_binding and the binding silently keeps its authored
fallback. The SKILL.md line now names the declaration, and format.md's
Variables section names the attribute, adds the font and image types, and
shows a one-line declare-then-bind example. The hyperframes entry budget
grows 64 B for the line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant