From 6cab53a681bf159ffe34f66506a8004e38213fae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Wed, 29 Jul 2026 17:27:07 +0200 Subject: [PATCH] docs(skills): name the media-treatment policy targets instead of alluding to them (#2879) Two routing surfaces pointed agents at media "policies" and "contracts" without naming a file. An agent that goes looking and finds nothing fills the gap with an invented rule. - skills/hyperframes/SKILL.md: "Load its media-treatment policy" now names references/media-treatments.md and states the policy governs how footage is treated, never whether media may be used. - skills/general-video/SKILL.md: "adoption, resolution, provider, provenance, and reuse contracts" now names references/resolve.md and references/setup-providers.md. Drops "provenance", which is ledger bookkeeping in operations.md, not a contract to follow. - The scaffolded project templates carried the same unnamed pointer and ship to every hyperframes init; both updated and kept byte-identical. --- packages/cli/src/templates/_shared/AGENTS.md | 2 +- packages/cli/src/templates/_shared/CLAUDE.md | 2 +- skills-manifest.json | 4 ++-- skills/general-video/SKILL.md | 2 +- skills/hyperframes/SKILL.md | 8 +++++--- 5 files changed, 10 insertions(+), 8 deletions(-) diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md index c4ff0aefd..6b1052174 100644 --- a/packages/cli/src/templates/_shared/AGENTS.md +++ b/packages/cli/src/templates/_shared/AGENTS.md @@ -20,7 +20,7 @@ The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes-keyframes`, `/hyperframes-creative`, `/hyperframes-cli`, `/media-use`, `/hyperframes-registry`, `/figma`) and the full capability map live inside `/hyperframes` — it is the single source of truth for which skill handles which intent. -**Changing how real footage or images look or reveal?** Load `/media-use` and its media-treatment policy before editing, even when the request only says dark, flat, boring, retro, private, or “make the reveal cooler.” Use canonical media treatments and seek-safe motion; do not improvise equivalent CSS/SVG filters or overlays. +**Changing how real footage or images look or reveal?** Load `/media-use` and read its `references/media-treatments.md` before editing, even when the request only says dark, flat, boring, retro, private, or “make the reveal cooler.” It governs how footage is treated, never whether media may be used. Use canonical media treatments and seek-safe motion; do not improvise equivalent CSS/SVG filters or overlays. > **Tailwind v4 projects** (`hyperframes init --tailwind`): see `/hyperframes-core` → `references/tailwind.md`. diff --git a/packages/cli/src/templates/_shared/CLAUDE.md b/packages/cli/src/templates/_shared/CLAUDE.md index c4ff0aefd..6b1052174 100644 --- a/packages/cli/src/templates/_shared/CLAUDE.md +++ b/packages/cli/src/templates/_shared/CLAUDE.md @@ -20,7 +20,7 @@ The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes-keyframes`, `/hyperframes-creative`, `/hyperframes-cli`, `/media-use`, `/hyperframes-registry`, `/figma`) and the full capability map live inside `/hyperframes` — it is the single source of truth for which skill handles which intent. -**Changing how real footage or images look or reveal?** Load `/media-use` and its media-treatment policy before editing, even when the request only says dark, flat, boring, retro, private, or “make the reveal cooler.” Use canonical media treatments and seek-safe motion; do not improvise equivalent CSS/SVG filters or overlays. +**Changing how real footage or images look or reveal?** Load `/media-use` and read its `references/media-treatments.md` before editing, even when the request only says dark, flat, boring, retro, private, or “make the reveal cooler.” It governs how footage is treated, never whether media may be used. Use canonical media treatments and seek-safe motion; do not improvise equivalent CSS/SVG filters or overlays. > **Tailwind v4 projects** (`hyperframes init --tailwind`): see `/hyperframes-core` → `references/tailwind.md`. diff --git a/skills-manifest.json b/skills-manifest.json index a7b36708e..27534f19e 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -14,11 +14,11 @@ "files": 2 }, "general-video": { - "hash": "87f292b572cad3f9", + "hash": "49f5216832cb8e91", "files": 4 }, "hyperframes": { - "hash": "02b48855a5321e48", + "hash": "db16e302ad866b42", "files": 17 }, "hyperframes-animation": { diff --git a/skills/general-video/SKILL.md b/skills/general-video/SKILL.md index 0480d2ccc..9a6da43ac 100644 --- a/skills/general-video/SKILL.md +++ b/skills/general-video/SKILL.md @@ -20,7 +20,7 @@ A successful no-op means the skill is current. Surface an update failure instead ## 1. Apply cross-cutting source adapters -- **Media:** For any audio, image, icon, logo, voice, grade, LUT, treatment/effect, caption, or media-operation need, load `/media-use` and follow its adoption, resolution, provider, provenance, and reuse contracts. Vague footage feedback and named styles use its `media-treatments.md` policy before editing; do not improvise supported media effects with CSS/SVG/opacity. Before the first authenticated provider action, run `npx hyperframes auth status` and relay its output verbatim. If signed out, apply the gate in `../hyperframes-core/references/brief-contract.md`: collaborative waits for sign-in or an explicit offline choice; autonomous states the status and continues through an available offline provider. Surface a blocker when no offline provider can satisfy a required capability. Local adoption alone does not require an auth gate. +- **Media:** For any audio, image, icon, logo, voice, grade, LUT, treatment/effect, caption, or media-operation need, load `/media-use` and follow `../media-use/references/resolve.md` (resolve, adopt, reuse) and `../media-use/references/setup-providers.md` (providers, auth). Vague footage feedback and named styles use `../media-use/references/media-treatments.md` before editing; do not improvise supported media effects with CSS/SVG/opacity. Before the first authenticated provider action, run `npx hyperframes auth status` and relay its output verbatim. If signed out, apply the gate in `../hyperframes-core/references/brief-contract.md`: collaborative waits for sign-in or an explicit offline choice; autonomous states the status and continues through an available offline provider. Surface a blocker when no offline provider can satisfy a required capability. Local adoption alone does not require an auth gate. - **Figma:** If any input is a `figma.com` URL, run `/figma` first. Build from its exported assets, tokens, components, or storyboard frames. Do not use raw Figma connector calls because they skip SVG sanitization, media provenance, and brand-token binding. These adapters do not change the workflow selected by `/hyperframes`. diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index e31530d34..e447e58d4 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -99,9 +99,11 @@ Use the bare name without `/`. If the command fails, surface the error; do not r Broad feedback about how photographic media looks or behaves also routes to `/media-use`, even when the user never says “color grading” or “effect”: fix dark/flat/boring footage, stylize a clip, hide a face, or improve a media -reveal. Load its media-treatment policy before editing; do not substitute a -generic LUT, CSS filter/overlay, or opacity tween for an existing canonical -treatment primitive. Keep text/layout/motion-only edits in their owning domain. +reveal. Read `../media-use/references/media-treatments.md` before editing a +treatment; it governs how footage is treated, never whether media may be used. +Do not substitute a generic LUT, CSS filter/overlay, or opacity tween for an +existing canonical treatment primitive. Keep text/layout/motion-only edits in +their owning domain. During a build with important photographic media, include one grounded media-polish scan in the final quality pass; leaving suitable media unchanged is a valid result.