From 9631e077a24b18d3638703714ef0e7e46a0788b1 Mon Sep 17 00:00:00 2001 From: 0xDevNinja Date: Fri, 26 Jun 2026 13:18:35 +0530 Subject: [PATCH 1/2] docs: scope orphaned skill-level AGENTS.md as supplementary references Three skill directories ship a long-form upstream AGENTS.md alongside their loadable SKILL.md: .agents/skills/flux-best-practices/AGENTS.md .agents/skills/vercel-composition-patterns/AGENTS.md .agents/skills/vercel-react-best-practices/AGENTS.md None were referenced by their parent SKILL.md, skills/INDEX.md, AGENT_GUIDE.md, or any pipeline manifest, leaving their authority scope undefined relative to the repository-root AGENTS.md (override / extend / ignore?). Reference each from its SKILL.md with explicit scope: the AGENTS.md is supplementary upstream reference material for that skill only, SKILL.md is the loadable entry point and the authority, and it does not override or extend the root AGENTS.md / AGENT_GUIDE.md. Preserves the vendored content while removing the ambiguity. Refs #61 --- .agents/skills/flux-best-practices/SKILL.md | 2 ++ .agents/skills/vercel-composition-patterns/SKILL.md | 2 ++ .agents/skills/vercel-react-best-practices/SKILL.md | 2 ++ 3 files changed, 6 insertions(+) diff --git a/.agents/skills/flux-best-practices/SKILL.md b/.agents/skills/flux-best-practices/SKILL.md index 414e8cf..7d725f1 100644 --- a/.agents/skills/flux-best-practices/SKILL.md +++ b/.agents/skills/flux-best-practices/SKILL.md @@ -11,6 +11,8 @@ metadata: Use this skill when generating prompts for any BFL FLUX model to ensure optimal image quality and accurate prompt interpretation. +> **Extended reference:** [`AGENTS.md`](AGENTS.md) in this directory is the long-form upstream FLUX guide (vendored from Black Forest Labs). It is supplementary reference material scoped to this skill only — `SKILL.md` is the loadable entry point and the authority. It does not override or extend the repository-root `AGENTS.md` / `AGENT_GUIDE.md`. + ## When to Use - Creating prompts for FLUX.2 or FLUX.1 models diff --git a/.agents/skills/vercel-composition-patterns/SKILL.md b/.agents/skills/vercel-composition-patterns/SKILL.md index d07025b..a460ad7 100644 --- a/.agents/skills/vercel-composition-patterns/SKILL.md +++ b/.agents/skills/vercel-composition-patterns/SKILL.md @@ -19,6 +19,8 @@ boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale. +> **Extended reference:** [`AGENTS.md`](AGENTS.md) in this directory is the long-form upstream guide (vendored from Vercel). It is supplementary reference material scoped to this skill only — `SKILL.md` is the loadable entry point and the authority. It does not override or extend the repository-root `AGENTS.md` / `AGENT_GUIDE.md`. + ## When to Apply Reference these guidelines when: diff --git a/.agents/skills/vercel-react-best-practices/SKILL.md b/.agents/skills/vercel-react-best-practices/SKILL.md index df17a29..c836c90 100644 --- a/.agents/skills/vercel-react-best-practices/SKILL.md +++ b/.agents/skills/vercel-react-best-practices/SKILL.md @@ -11,6 +11,8 @@ metadata: Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 65 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation. +> **Extended reference:** [`AGENTS.md`](AGENTS.md) in this directory is the long-form upstream guide (vendored from Vercel). It is supplementary reference material scoped to this skill only — `SKILL.md` is the loadable entry point and the authority. It does not override or extend the repository-root `AGENTS.md` / `AGENT_GUIDE.md`. + ## When to Apply Reference these guidelines when: From 8cb971b2339555f5740a098fa4690f33e8bc6d9e Mon Sep 17 00:00:00 2001 From: 0xDevNinja Date: Fri, 26 Jun 2026 13:18:35 +0530 Subject: [PATCH 2/2] docs: de-stale gsap/README.md and mark it a non-loadable nav map MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The GSAP family README described HyperFrames as a 'future' engine ('if the parallel HyperFrames engine gets wired in', 'becomes a day-1 skill', 'Future hyperframes_compose tool — if added'). Every other artifact (AGENT_GUIDE.md, skills/core/hyperframes.md, skills/INDEX.md) treats HyperFrames as a fully production composition runtime, and hyperframes_compose is a registered tool. Update the HyperFrames references to present-tense production reality. Also add a scope note: this directory has no SKILL.md and is not a loadable skill — it is a navigation map for the sibling gsap-* skills, which removes the ambiguity about why it is not loadable via agent_skills[]. Closes #61 --- .agents/skills/gsap/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.agents/skills/gsap/README.md b/.agents/skills/gsap/README.md index 6a745ab..c66eac0 100644 --- a/.agents/skills/gsap/README.md +++ b/.agents/skills/gsap/README.md @@ -1,5 +1,7 @@ # GSAP Skills in OpenMontage +> **Scope:** This directory has no `SKILL.md` — it is **not** a loadable skill. This file is a navigation map for the eight loadable `gsap-*` skills that live in sibling directories (`gsap-core`, `gsap-timeline`, …). Read it to find the right `gsap-*` skill; the agent loads those, not this README. + Eight Layer 3 skills teaching the agent correct GSAP (GreenSock Animation Platform) usage. Sourced from [greensock/gsap-skills](https://github.com/greensock/gsap-skills), MIT licensed. ## Why GSAP is in this repo @@ -7,7 +9,7 @@ Eight Layer 3 skills teaching the agent correct GSAP (GreenSock Animation Platfo OpenMontage doesn't use GSAP directly today — Remotion compositions are driven by `useCurrentFrame()` + `interpolate()` + `spring()`. GSAP becomes relevant in two concrete scenarios: 1. **Advanced text / SVG / motion-path animation inside a Remotion component.** GSAP's plugin family (SplitText, MorphSVG, DrawSVG, MotionPath, CustomEase) solves problems that are painful to hand-roll with primitive `interpolate()` calls. When you need per-character reveals, curved camera paths over SVG, or morphing between two arbitrary shapes — reach for GSAP. -2. **HyperFrames composition (future)**. If the parallel HyperFrames engine gets wired in (see `DESIGN.md` / earlier discussion), GSAP is its native animation runtime via the Frame Adapter pattern — timelines are paused and registered on `window.__timelines`, and the engine seeks them frame-by-frame. GSAP timeline authoring becomes a day-1 skill. +2. **HyperFrames composition.** HyperFrames is a production composition runtime in OpenMontage (rendered via `hyperframes_compose`; see `skills/core/hyperframes.md` and `AGENT_GUIDE.md`). GSAP is its native animation runtime via the Frame Adapter pattern — timelines are paused and registered on `window.__timelines`, and the engine seeks them frame-by-frame. GSAP timeline authoring is a day-1 skill for HyperFrames scenes. ## When to read which @@ -31,7 +33,7 @@ These skills don't fire automatically. Trigger points: - **`skills/meta/animation-runtime-selector.md`** — the dispatcher meta skill. When authoring any animated scene, read this first; it routes you to the right Layer 3 skill based on what kind of motion you need. - **Pipeline asset-director skills** — `animated-explainer`, `animation`, and `cinematic` pipelines reference these skills where applicable (SplitText for text, MorphSVG for logos, MotionPath for camera moves). -- **Future `hyperframes_compose` tool** — if added, will declare `agent_skills: ["gsap-timeline", "gsap-core"]` so the agent auto-reads them before authoring a HyperFrames composition. +- **`hyperframes_compose` tool** — declares `agent_skills: ["gsap-timeline", "gsap-core"]` so the agent auto-reads them before authoring a HyperFrames composition. ## Running GSAP deterministically inside Remotion