Repository navigation
Skills: 10 cross-skill contradictions and 11 wrong facts or broken paths #5025
Description
Verified against main at 2b82e39 (2026-10-04); line numbers refer to that commit. Short names drop the hyperframes- prefix (core = skills/hyperframes-core/SKILL.md, cli = skills/hyperframes-cli/SKILL.md, …). Unless a path is given, the line is in the skill's SKILL.md.
Why it matters. When two loaded skills give opposite rules, the agent picks one arbitrarily or stops to ask. When a path doesn't resolve, the agent gets a read error and stops, or improvises the missing doctrine. Users can't patch this locally: npx hyperframes skills update and hyperframes init (step 0 of every workflow) overwrite local edits.
Section 1 needs a maintainer decision. In section 2, each fix is one edit.
1. Contradictions between skills (needs a maintainer decision)
| # | Where | Conflict | Likely fix |
|---|---|---|---|
| 1 | core:56 vs animation:66, keyframes:56,77,112,259 |
core: "Building it inside an async callback (document.fonts.ready) is supported". animation and keyframes forbid building the timeline inside async / setTimeout / Promise. animation:66 also credits that ban to core's Non-Negotiable Rules, which don't contain it. |
Decide, then align the other two. |
| 2 | registry:72 vs studio:90-92, core:88 |
registry: "data-track-index — layer ordering (higher = in front)". studio and core: display only, it never changes what renders on top. |
registry:72 → "Studio timeline row; display only — use CSS z-index for layering". |
| 3 | figma:91 vs cli:176-180 |
figma tells the agent to run npx hyperframes events --skill=figma-motion … by hand. cli lists events under "Commands you should not run": "an agent has no reason to call it by hand". |
Move the beacon into a bundled script, or drop it from figma. |
| 4 | cli:24, general-video:120 vs keyframes:57,214,264, studio:139, motion-graphics:131-132, slideshow:511-521 |
cli: run check, "do not run a redundant standalone lint". The others run lint then check, and studio uses lint alone as its final gate. |
Align everything on check. |
| 5 | talking-head-recut:8, slideshow:14, embedded-captions:14, motion-graphics:16, faceless-explainer:8, music-to-video:8, pr-to-video:8, product-launch-video:8 vs general-video:17-23,150 and the step-0 init |
"Confirm with the user before running skills update" vs general-video running it unprompted. init updates the skills anyway. |
One consent rule for every workflow. |
| 6 | music-to-video:14 vs :161 |
:14, Steps 3 and 6 in autonomous mode: "post the summary as a heads-up and proceed instead of waiting". :161: render "only on approval (autonomous mode: the same, as the one kept question)". | The sibling workflows keep the question: rewrite :14. |
| 7 | pr-to-video:178 vs faceless-explainer:128, product-launch-video:151 |
Pre-install registry blocks before dispatching workers (to avoid collisions) vs letting the parallel workers install them. | Align on pre-install. |
| 8 | talking-head-recut:423-425 vs :1109-1110 |
The layout files cover 2 formats vs 3. | Check the layout files and fix the wrong passage. |
| 9 | embedded-captions:51,95,134,177,226 vs :150-151,198 |
Cinematic-mode source file: plan.json, or cinematic.json → make-cinematic.cjs. |
Pick one. |
| 10 | audio:378-379 vs :138,386,391,476 |
"There is no static mode", while the same file describes one several times. | Read carve.mjs, then align. |
2. Wrong facts and broken paths (fix proposed)
| # | Where | Now | Proposed |
|---|---|---|---|
| 11 | studio:62-63 |
references/sub-compositions.md (not in studio) |
/hyperframes-core → references/sub-compositions.md |
| 12 | music-to-video:33 |
/media-use (references/bgm.md) |
/media-use (audio/references/bgm.md) |
| 13 | remotion-to-hyperframes:42 |
"When in doubt, default to … /general-video" (contradicts :12, its own description, and general-video's description) |
"When in doubt, return to /hyperframes; its intent layer picks the route." |
| 14 | registry:122 |
--tier on-device hard-coded (contradicts :127 and cli:92) |
--tier <the tier that answered> |
| 15 | talking-head-recut:541-543 vs :572-574 |
"copy-paste JSON snippet for … per-card layout field", while :572-574 says there is no card.layout field |
"… exact videoBounds + cardBounds; the storyboard records only card.zone". Drop "earlier versions … invented one" at :573. |
| 16 | talking-head-recut:251 |
"content can be a plain string…": the field is contentHints (:178) |
"contentHints can take any shape…" |
| 17 | talking-head-recut:547-550 |
"A common rhythm: … editorial … audit … whiteboard × pip × polaroid" (contradicts :433-434 and :455) | Remove it, and say "Within the user's chosen style group you may vary the style per card…" |
| 18 | embedded-captions:277 |
"falls back per SKILL §transcription" (no such section) | "falls back to an existing word-level transcript.json" |
| 19 | motion-graphics:111-114 |
node <SKILL_DIR>/phases/source/resolve.mjs … (the file doesn't exist; only guide.md does) |
Remove the block and keep "See phases/source/guide.md". |
| 20 | motion-graphics:101 |
The list of forms omits maps (listed at :54) |
Add / maps. |
| 21 | animation:76, creative:60-63, figma:97, slideshow:434,475 |
skills/<name>/scripts/… and skills/slideshow/references/… only resolve from the repo root, not from an installed skill |
<SKILL_DIR>/scripts/… and references/standalone-harness.md |
Activity
docs(skills): resolve cross-skill contradictions from the doctrine au…
docs(skills): fix wrong facts and broken paths from the doctrine audit
docs(skills): fix wrong facts and broken paths from the doctrine audit (
belentani7 commentedon Oct 5, 2026
This is a significant quality issue. Having 10 cross-skill contradictions and 11 wrong facts or broken paths means the skill system is unreliable and could cause agents to fail or behave unexpectedly.
You need a validation pass that checks all skills for consistency. Create a test suite that loads each skill, verifies all referenced paths exist, and checks for contradictions between skills.
Also consider adding a schema validator for skill definitions to catch these issues automatically.
ci(skills): lint skill-root paths and skill names in skill docs
ci(skills): lint skill-root paths and skill names in skill docs
ci(skills): lint skill-root paths and skill names in skill docs
jabaitedd commentedon Oct 20, 2026
Re row 5 (consent for
skills update): here's a concrete proposal for the single rule: confirm first, everywhere.Write it once, in
hyperframes/references/skill-lifecycle.md. The router, the step-0initand every workflow then link to it rather than restating it:Why:
hyperframes/SKILL.md, step 4) and the step-0init. In one session the agent can update silently through the router, then ask permission for the same command in the workflow.pr-to-videoskill. A prompt only protects the user if no path skips it.The edits:
initneeds a supported way to honour a "no". Right now there isn't one:--skip-skillsis ignored on purpose (init.ts:790-800) while skills.sh lags GitHub, andHYPERFRAMES_SKIP_SKILLS=1is documented for CI and tests only. I understand why the freshness check can't be dodged during the lag. But a user who has declined the update should still be able to scaffold a project. CouldHYPERFRAMES_SKIP_SKILLS=1be documented as the agent's path when the user declines (until--skip-skillsis restored), or could init ask before refreshing in interactive runs?jrusso1020 commentedon Oct 24, 2026
Status update: most of this audit landed. #5026 fixed the wrong facts and broken paths, and #5028 resolved the contradictions in rows 1, 2, 4 and 6 to 10. Two rows are still open. Row 3: the figma skill still asks agents to run
npx hyperframes eventsby hand. Row 5: there is still no single consent rule forskills update. #5874 adds a CI check so broken skill paths can't come back. Keeping this open for rows 3 and 5.— Rames
miguel-heygen commentedon Oct 24, 2026
A status update against current main. Since the last update, the workflow skills were retired (#5651), and
initno longer refreshes skills that are already installed; it only installs missing core skills (#6168). Update guidance now lives in one place,skills/hyperframes/references/skill-lifecycle.md, so the inconsistent consent wording in row 5 is gone with the skills that carried it. Whether that reference should also say to ask the user before runningskills updateis still a call for us to make.On the related question in the comments:
init --skip-skillsworks again on current releases, but its--helptext still calls it "temporarily ignored". That text is out of date.Row 3 is still open:
skills/figma/SKILL.mdsays to runnpx hyperframes eventsby hand, whilehyperframes-clisays not to. Keeping this open for that row and the consent wording.