Skip to content

Commit 7d312bd

Browse files
committed
docs(skills): add pre-build gate to changelog-video SKILL.md
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.
1 parent 911b332 commit 7d312bd

2 files changed

Lines changed: 64 additions & 18 deletions

File tree

‎.agents/skills/changelog-video/SKILL.md‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,26 @@ non-visual items (reliability fix lists).
2525

2626
## Pipeline
2727

28+
### 0 · Bootstrap the project from THIS skill's assets — non-negotiable
29+
30+
**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.
31+
32+
```bash
33+
mkdir -p project/assets/fonts
34+
cp <SKILL_DIR>/assets/fonts/*.woff2 project/assets/fonts/
35+
cp <SKILL_DIR>/assets/bgm.mp3 project/bgm.mp3
36+
ffmpeg -y -stream_loop 15 -i <SKILL_DIR>/assets/bg-pattern.mp4 -t <TOTAL> \
37+
-vf "scale=1080:1080,fps=30,eq=saturation=0.72,[email protected]:t=fill" \
38+
-an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-<TOTAL>s.mp4
39+
cp <SKILL_DIR>/examples/master-skeleton.html project/index.html
40+
```
41+
42+
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.
43+
44+
Only THEN begin steps 1-6 below. Steps 1-4 (parse, route, script, VO) plan what goes into the scaffold; step 5 fills placeholders (`<RANGE>`, `<TOTAL>`, `<CUT_N>`, `<DUR_N>`, scene bodies) inside the already-copied `project/index.html` — you do NOT rewrite the scaffold's chrome, fonts, palette, or layout shell.
45+
46+
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.
47+
2848
### 1 · Parse + editorial cut
2949

3050
- Extract: week range, headline stats (releases, commits), themes, items.
@@ -116,12 +136,15 @@ projects/active/weekly-changelog-<range>/
116136

117137
## Anti-patterns
118138

119-
| Don't | Instead |
120-
| ---------------------------------------- | ---------------------------------------------- |
121-
| Bullet-point slides for UI changes | Mock the surface acting out the change |
122-
| Fake UI for un-representable items | Honest checklist scene |
123-
| Plain "JSON"/"CLI" in the TTS text | Lexicon spoken forms; display stays standard |
124-
| Phonetic spellings in captions | Captions always render the display layer |
125-
| Guessing an unknown term's pronunciation | Ask, then grow the lexicon |
126-
| Speaking every changelog item | ≤3 per theme; the digest link carries the rest |
127-
| Green accents everywhere | One green moment per scene (#5ef17c) |
139+
| Don't | Instead |
140+
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
141+
| Bullet-point slides for UI changes | Mock the surface acting out the change |
142+
| Fake UI for un-representable items | Honest checklist scene |
143+
| Plain "JSON"/"CLI" in the TTS text | Lexicon spoken forms; display stays standard |
144+
| Phonetic spellings in captions | Captions always render the display layer |
145+
| Guessing an unknown term's pronunciation | Ask, then grow the lexicon |
146+
| Speaking every changelog item | ≤3 per theme; the digest link carries the rest |
147+
| Green accents everywhere | One green moment per scene (#5ef17c) |
148+
| Starting from a prior video's index.html | Step 0 — copy `examples/master-skeleton.html` from this skill into `project/index.html`, always |
149+
| Hand-crafted `@font-face` / WebGL shader / custom BGM | Step 0 — copy this skill's `assets/` verbatim; the skill's assets ARE the brand |
150+
| 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 |

‎.claude/skills/changelog-video/SKILL.md‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,26 @@ non-visual items (reliability fix lists).
2525

2626
## Pipeline
2727

28+
### 0 · Bootstrap the project from THIS skill's assets — non-negotiable
29+
30+
**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.
31+
32+
```bash
33+
mkdir -p project/assets/fonts
34+
cp <SKILL_DIR>/assets/fonts/*.woff2 project/assets/fonts/
35+
cp <SKILL_DIR>/assets/bgm.mp3 project/bgm.mp3
36+
ffmpeg -y -stream_loop 15 -i <SKILL_DIR>/assets/bg-pattern.mp4 -t <TOTAL> \
37+
-vf "scale=1080:1080,fps=30,eq=saturation=0.72,[email protected]:t=fill" \
38+
-an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-<TOTAL>s.mp4
39+
cp <SKILL_DIR>/examples/master-skeleton.html project/index.html
40+
```
41+
42+
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.
43+
44+
Only THEN begin steps 1-6 below. Steps 1-4 (parse, route, script, VO) plan what goes into the scaffold; step 5 fills placeholders (`<RANGE>`, `<TOTAL>`, `<CUT_N>`, `<DUR_N>`, scene bodies) inside the already-copied `project/index.html` — you do NOT rewrite the scaffold's chrome, fonts, palette, or layout shell.
45+
46+
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.
47+
2848
### 1 · Parse + editorial cut
2949

3050
- Extract: week range, headline stats (releases, commits), themes, items.
@@ -116,12 +136,15 @@ projects/active/weekly-changelog-<range>/
116136

117137
## Anti-patterns
118138

119-
| Don't | Instead |
120-
| ---------------------------------------- | ---------------------------------------------- |
121-
| Bullet-point slides for UI changes | Mock the surface acting out the change |
122-
| Fake UI for un-representable items | Honest checklist scene |
123-
| Plain "JSON"/"CLI" in the TTS text | Lexicon spoken forms; display stays standard |
124-
| Phonetic spellings in captions | Captions always render the display layer |
125-
| Guessing an unknown term's pronunciation | Ask, then grow the lexicon |
126-
| Speaking every changelog item | ≤3 per theme; the digest link carries the rest |
127-
| Green accents everywhere | One green moment per scene (#5ef17c) |
139+
| Don't | Instead |
140+
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
141+
| Bullet-point slides for UI changes | Mock the surface acting out the change |
142+
| Fake UI for un-representable items | Honest checklist scene |
143+
| Plain "JSON"/"CLI" in the TTS text | Lexicon spoken forms; display stays standard |
144+
| Phonetic spellings in captions | Captions always render the display layer |
145+
| Guessing an unknown term's pronunciation | Ask, then grow the lexicon |
146+
| Speaking every changelog item | ≤3 per theme; the digest link carries the rest |
147+
| Green accents everywhere | One green moment per scene (#5ef17c) |
148+
| Starting from a prior video's index.html | Step 0 — copy `examples/master-skeleton.html` from this skill into `project/index.html`, always |
149+
| Hand-crafted `@font-face` / WebGL shader / custom BGM | Step 0 — copy this skill's `assets/` verbatim; the skill's assets ARE the brand |
150+
| 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 |

0 commit comments

Comments
 (0)