From 7d312bd170baa6fb1d2c247e14fef7c4d1022279 Mon Sep 17 00:00:00 2001 From: jrusso1020 Date: Tue, 21 Jul 2026 01:05:53 +0000 Subject: [PATCH] docs(skills): add pre-build gate to changelog-video SKILL.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds an explicit Step 0 above the pipeline that spells out the concrete file copies (fonts, bgm, ffmpeg-encoded bg-pattern, master-skeleton.html) before any composition HTML is written. Extends the anti-patterns table with the three failure modes James caught on the Jul 13-20 weekly run: starting from a prior video's index.html, hand-crafting @font-face / WebGL shader / custom BGM, and shipping without a CloudFront invalidation after the S3 replace. Why: the previous SKILL.md said "follow references/build-spec.md exactly" in step 5, but that lets an agent read the build-spec after already writing composition HTML on the wrong scaffold. Ships of the Jul 13-20 video went through three off-brand iterations before I finally started from master-skeleton.html (Jake called v3 "trash" — the skill's assets, fonts, and scaffold ARE the brand, not the SKILL.md prompt on its own). The three added anti-patterns are the concrete traps: agents will keep starting from prior-project templates unless the skill explicitly bans it. Mirrors to .agents/skills/ (Codex CLI) and .claude/skills/ (Claude Code) byte-identical, per the skill-mirror gate. --- .agents/skills/changelog-video/SKILL.md | 41 +++++++++++++++++++------ .claude/skills/changelog-video/SKILL.md | 41 +++++++++++++++++++------ 2 files changed, 64 insertions(+), 18 deletions(-) diff --git a/.agents/skills/changelog-video/SKILL.md b/.agents/skills/changelog-video/SKILL.md index c53b96c66..46e6ff2e0 100644 --- a/.agents/skills/changelog-video/SKILL.md +++ b/.agents/skills/changelog-video/SKILL.md @@ -25,6 +25,26 @@ non-visual items (reliability fix lists). ## Pipeline +### 0 · Bootstrap the project from THIS skill's assets — non-negotiable + +**Do this before writing any composition HTML. Skipping it always produces a video that looks like a similar project you built before, NOT this skill's brand — that's the single most common way this skill goes off-brand.** The skill's assets, fonts, and scaffold are the skill; the SKILL.md prompt is a router. + +```bash +mkdir -p project/assets/fonts +cp /assets/fonts/*.woff2 project/assets/fonts/ +cp /assets/bgm.mp3 project/bgm.mp3 +ffmpeg -y -stream_loop 15 -i /assets/bg-pattern.mp4 -t \ + -vf "scale=1080:1080,fps=30,eq=saturation=0.72,drawbox=c=black@0.5:t=fill" \ + -an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-s.mp4 +cp /examples/master-skeleton.html project/index.html +``` + +Then **read `references/build-spec.md` end-to-end** (not skimmed) — it defines the brand tokens (TT Norms Pro + ABC Solar Display + TT Norms Mono, cream `#f5f6f4`, rationed green `#5ef17c`, glass cards with green-tinted borders, kicker/sec-chip pill shape, caption rail at `top: 1002`) that every scene inherits from the scaffold. + +Only THEN begin steps 1-6 below. Steps 1-4 (parse, route, script, VO) plan what goes into the scaffold; step 5 fills placeholders (``, ``, ``, ``, scene bodies) inside the already-copied `project/index.html` — you do NOT rewrite the scaffold's chrome, fonts, palette, or layout shell. + +If you catch yourself reaching for `cp` on a prior video's `index.html`, or writing your own `@font-face` declarations, or designing a WebGL shader background instead of using the encoded bg-pattern MP4 above: STOP. Delete the current `index.html` and restart at the `cp` of the master-skeleton scaffold. Rebuilding scene content on the right scaffold is cheaper than retrofitting brand into the wrong scaffold. + ### 1 · Parse + editorial cut - Extract: week range, headline stats (releases, commits), themes, items. @@ -116,12 +136,15 @@ projects/active/weekly-changelog-/ ## Anti-patterns -| Don't | Instead | -| ---------------------------------------- | ---------------------------------------------- | -| Bullet-point slides for UI changes | Mock the surface acting out the change | -| Fake UI for un-representable items | Honest checklist scene | -| Plain "JSON"/"CLI" in the TTS text | Lexicon spoken forms; display stays standard | -| Phonetic spellings in captions | Captions always render the display layer | -| Guessing an unknown term's pronunciation | Ask, then grow the lexicon | -| Speaking every changelog item | ≤3 per theme; the digest link carries the rest | -| Green accents everywhere | One green moment per scene (#5ef17c) | +| Don't | Instead | +| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bullet-point slides for UI changes | Mock the surface acting out the change | +| Fake UI for un-representable items | Honest checklist scene | +| Plain "JSON"/"CLI" in the TTS text | Lexicon spoken forms; display stays standard | +| Phonetic spellings in captions | Captions always render the display layer | +| Guessing an unknown term's pronunciation | Ask, then grow the lexicon | +| Speaking every changelog item | ≤3 per theme; the digest link carries the rest | +| Green accents everywhere | One green moment per scene (#5ef17c) | +| Starting from a prior video's index.html | Step 0 — copy `examples/master-skeleton.html` from this skill into `project/index.html`, always | +| Hand-crafted `@font-face` / WebGL shader / custom BGM | Step 0 — copy this skill's `assets/` verbatim; the skill's assets ARE the brand | +| Delivered without CloudFront invalidation | Run `aws cloudfront create-invalidation` on distribution `E2BSLVSZ7FG3U0` for the exact path after any S3 replace — CDN caches the old file otherwise | diff --git a/.claude/skills/changelog-video/SKILL.md b/.claude/skills/changelog-video/SKILL.md index c53b96c66..46e6ff2e0 100644 --- a/.claude/skills/changelog-video/SKILL.md +++ b/.claude/skills/changelog-video/SKILL.md @@ -25,6 +25,26 @@ non-visual items (reliability fix lists). ## Pipeline +### 0 · Bootstrap the project from THIS skill's assets — non-negotiable + +**Do this before writing any composition HTML. Skipping it always produces a video that looks like a similar project you built before, NOT this skill's brand — that's the single most common way this skill goes off-brand.** The skill's assets, fonts, and scaffold are the skill; the SKILL.md prompt is a router. + +```bash +mkdir -p project/assets/fonts +cp /assets/fonts/*.woff2 project/assets/fonts/ +cp /assets/bgm.mp3 project/bgm.mp3 +ffmpeg -y -stream_loop 15 -i /assets/bg-pattern.mp4 -t \ + -vf "scale=1080:1080,fps=30,eq=saturation=0.72,drawbox=c=black@0.5:t=fill" \ + -an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-s.mp4 +cp /examples/master-skeleton.html project/index.html +``` + +Then **read `references/build-spec.md` end-to-end** (not skimmed) — it defines the brand tokens (TT Norms Pro + ABC Solar Display + TT Norms Mono, cream `#f5f6f4`, rationed green `#5ef17c`, glass cards with green-tinted borders, kicker/sec-chip pill shape, caption rail at `top: 1002`) that every scene inherits from the scaffold. + +Only THEN begin steps 1-6 below. Steps 1-4 (parse, route, script, VO) plan what goes into the scaffold; step 5 fills placeholders (``, ``, ``, ``, scene bodies) inside the already-copied `project/index.html` — you do NOT rewrite the scaffold's chrome, fonts, palette, or layout shell. + +If you catch yourself reaching for `cp` on a prior video's `index.html`, or writing your own `@font-face` declarations, or designing a WebGL shader background instead of using the encoded bg-pattern MP4 above: STOP. Delete the current `index.html` and restart at the `cp` of the master-skeleton scaffold. Rebuilding scene content on the right scaffold is cheaper than retrofitting brand into the wrong scaffold. + ### 1 · Parse + editorial cut - Extract: week range, headline stats (releases, commits), themes, items. @@ -116,12 +136,15 @@ projects/active/weekly-changelog-/ ## Anti-patterns -| Don't | Instead | -| ---------------------------------------- | ---------------------------------------------- | -| Bullet-point slides for UI changes | Mock the surface acting out the change | -| Fake UI for un-representable items | Honest checklist scene | -| Plain "JSON"/"CLI" in the TTS text | Lexicon spoken forms; display stays standard | -| Phonetic spellings in captions | Captions always render the display layer | -| Guessing an unknown term's pronunciation | Ask, then grow the lexicon | -| Speaking every changelog item | ≤3 per theme; the digest link carries the rest | -| Green accents everywhere | One green moment per scene (#5ef17c) | +| Don't | Instead | +| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bullet-point slides for UI changes | Mock the surface acting out the change | +| Fake UI for un-representable items | Honest checklist scene | +| Plain "JSON"/"CLI" in the TTS text | Lexicon spoken forms; display stays standard | +| Phonetic spellings in captions | Captions always render the display layer | +| Guessing an unknown term's pronunciation | Ask, then grow the lexicon | +| Speaking every changelog item | ≤3 per theme; the digest link carries the rest | +| Green accents everywhere | One green moment per scene (#5ef17c) | +| Starting from a prior video's index.html | Step 0 — copy `examples/master-skeleton.html` from this skill into `project/index.html`, always | +| Hand-crafted `@font-face` / WebGL shader / custom BGM | Step 0 — copy this skill's `assets/` verbatim; the skill's assets ARE the brand | +| Delivered without CloudFront invalidation | Run `aws cloudfront create-invalidation` on distribution `E2BSLVSZ7FG3U0` for the exact path after any S3 replace — CDN caches the old file otherwise |