From 1d92aafad50aae46eac02679c589ca26f8498760 Mon Sep 17 00:00:00 2001 From: Meng To <1065452+MengTo@users.noreply.github.com> Date: Fri, 14 Aug 2026 14:13:01 +0800 Subject: [PATCH 01/10] Add YouTube companion runbook skill --- README.md | 11 +- .../build-youtube-companion-runbooks/SKILL.md | 128 +++++++++++++ .../agents/openai.yaml | 4 + .../assets/youtube-companion-template.md | 142 +++++++++++++++ .../scripts/validate_youtube_companion.py | 169 ++++++++++++++++++ 5 files changed, 450 insertions(+), 4 deletions(-) create mode 100644 agent-skills/media/build-youtube-companion-runbooks/SKILL.md create mode 100644 agent-skills/media/build-youtube-companion-runbooks/agents/openai.yaml create mode 100644 agent-skills/media/build-youtube-companion-runbooks/assets/youtube-companion-template.md create mode 100644 agent-skills/media/build-youtube-companion-runbooks/scripts/validate_youtube_companion.py diff --git a/README.md b/README.md index 5be5973..6e3870f 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,8 @@ agent-skills/ media/ aura-asset-images/ SKILL.md + build-youtube-companion-runbooks/ + SKILL.md unsplash-asset-images/ SKILL.md ui/ @@ -177,7 +179,7 @@ Conventions: ## Current library -This snapshot contains **123 skills** across five categories. +This snapshot contains **128 skills** across five categories. Use `find agent-skills -name SKILL.md | sort` for the source of truth. @@ -201,9 +203,10 @@ Operational skills for repeatable Codex work: - `write-like-meng-on-x` - calibrate concise X drafts against an authored voice corpus. - `x-bookmark-quote-posts` - turn recent X bookmarks into source-backed quote-post drafts. -### Media (2) +### Media (3) -Image sourcing skills: +Media production and image sourcing skills: +- `build-youtube-companion-runbooks` - package verified videos into titles, thumbnails, chapters, descriptions, social copy, publication gates, and upload checks. - `aura-asset-images` - use Aura Assets for stock-style design and marketing imagery. - `unsplash-asset-images` - pick high-quality Unsplash assets by use case, crop, and ratio. @@ -236,7 +239,7 @@ Player systems and feedback: Assets, performance, QA, and release: - `build-hybrid-game-assets`, `build-vesperfall-review-assets`, `optimize-threejs-games`, `test-playable-web-games`, `ship-web-games` -### Web design (81) +### Web design (85) Conversion and implementation: - `build-awwwards-quality-sites`, `landing-page`, `pricing-page`, `tailwindcss`, `animation-systems`, `webgl-landing-steering` diff --git a/agent-skills/media/build-youtube-companion-runbooks/SKILL.md b/agent-skills/media/build-youtube-companion-runbooks/SKILL.md new file mode 100644 index 0000000..231c238 --- /dev/null +++ b/agent-skills/media/build-youtube-companion-runbooks/SKILL.md @@ -0,0 +1,128 @@ +--- +name: build-youtube-companion-runbooks +description: Create or update source-faithful YouTube companion runbooks from a finished video, local master, transcript, captions, and related article. Use when Codex needs to produce `youtube.md` packaging with accurate titles, hooks, thumbnail directions, chapter timestamps, a YouTube description, social and LinkedIn copy, a pinned comment, public-link gates, resource packaging, and a final upload checklist. +--- + +# Build YouTube companion runbooks + +Turn verified video evidence into a practical `youtube.md` package. Keep internal production notes separate from copy that will be pasted into YouTube or social platforms. + +## Gather the evidence + +1. Locate the final video or local master, transcript or captions, related article, and owned thumbnail assets. +2. Probe the video when its duration or dimensions are unknown. +3. Read the complete article and transcript before writing titles or chapters. +4. Verify any existing public video, article, repository, product, or resource URL from its first-party page. +5. Record missing public URLs as explicit gates. Never substitute a similar video or invent a link. + +Prefer the final uploaded video for timestamps. When only a local master exists, derive chapters from the transcript and require a post-upload recheck. + +## Start from the template + +Copy [assets/youtube-companion-template.md](assets/youtube-companion-template.md) into the target article folder as `youtube.md`. Replace every bracketed instruction with source-backed content or a standardized publication gate. + +Keep these internal source links near the top when available: + +- related article +- source video or local master +- transcript or captions +- optimized upload file + +Use neutral placeholders in reusable skills and public repositories. Do not hard-code a creator's home directory, email, credentials, private project names, or unpublished account details. + +## Choose one honest package + +Lead with the strongest visible result, conflict, or useful surprise from the recording. + +Create: + +- one recommended title with a short reason +- five or six alternate titles +- five opening hooks +- two thumbnail directions +- one short thumbnail phrase, usually two to four words + +Name the product, model, or medium when it improves clarity. Keep the promise inside the evidence. Do not claim “one prompt,” “zero edits,” a cost, a speed, or a result unless the recording proves it. + +Build the primary thumbnail from an owned frame or article visual. Make the finished result larger than the tool interface. Remove tiny UI text that will disappear on a phone. Avoid generic logos, fake code, long prompt text, or imagery unrelated to the video. + +## Build chapters from the transcript + +Create 8 to 20 chapters for a normal long-form video. Use fewer for short videos and more only when the recording has real topic changes. + +Follow these rules: + +- Start with `00:00`. +- Keep timestamps strictly increasing. +- Place a chapter where the subject changes, not at every sentence. +- Use concrete labels that describe what the viewer learns or sees. +- Keep most labels under 65 characters. +- Avoid duplicate or nearly duplicate chapter names. +- Recheck every timestamp after the final upload, intro replacement, or edit. + +Copy the same verified chapter list into the YouTube description. + +## Write the YouTube description + +Use the first two lines for the result and workflow. Explain what the viewer will learn in plain language, then add: + +1. a short list of covered steps +2. an exact prompt only when it appears in the source +3. the verified chapter list +4. a `Resources:` block with first-party URLs + +Use `[ADD YOUTUBE URL BEFORE GOING LIVE]`, `[ADD ARTICLE URL BEFORE GOING LIVE]`, or `[ADD RESOURCE ZIP URL BEFORE GOING LIVE]` when a public destination does not exist yet. + +Keep local filesystem paths out of public copy blocks. Link the first mention of each product, site, repository, model, or download. Do not claim a download exists until the file and public link are verified. + +## Package downloads as one resource + +When the video offers several files, package the article PDF, templates, prompt files, README, and related assets into one ZIP. Upload and share that ZIP through the approved provider, then use one link throughout `youtube.md`. + +Do not scatter several file links across the description, pinned comment, and social posts. If no download bundle exists, omit the claim and leave the upload checklist explicit. + +## Adapt the idea for each channel + +Create these copy blocks from the same source evidence: + +- `Social Share`: concise, first-person, and suitable for X or Threads +- `LinkedIn Post`: explain the workflow and practical lesson with more context +- `Pinned Comment`: repeat the strongest action, link the article or source, and ask one useful question +- `Short Description`: one or two sentences for metadata or previews + +Preserve the creator's spoken vocabulary and opinion. Cut generic setup, fake revelations, repeated conclusions, decorative dashes, and unsupported superlatives. + +## Add publication gates + +End with an upload checklist that covers: + +- public video, article, sponsor, and download URLs +- chapter verification against the uploaded file +- thumbnail export at 1280 by 720 and a phone-size check +- consistent product and model spelling +- first-party resource-link checks +- sponsorship disclosure when applicable +- a reminder to add the final YouTube URL back to the article + +Uploading, publishing, sending sponsor review, and activating social automation are separate external actions. Perform only the actions the user authorized. + +## Validate the runbook + +Run: + +```bash +python3 scripts/validate_youtube_companion.py /absolute/path/to/youtube.md +``` + +Resolve the script relative to this skill folder when invoked outside the skill directory. + +Then check: + +```bash +git diff --check -- /absolute/path/to/youtube.md +git status --short -- /absolute/path/to/article-folder +``` + +Review every reported publication gate. A runbook can be complete with explicit gates, but it is not ready to publish until those gates are replaced with verified public values. + +When working in a mixed worktree, stage and commit only the new skill or companion files. diff --git a/agent-skills/media/build-youtube-companion-runbooks/agents/openai.yaml b/agent-skills/media/build-youtube-companion-runbooks/agents/openai.yaml new file mode 100644 index 0000000..20732db --- /dev/null +++ b/agent-skills/media/build-youtube-companion-runbooks/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Build YouTube Companion Runbooks" + short_description: "Package videos for YouTube and social launch" + default_prompt: "Use $build-youtube-companion-runbooks to create a source-faithful YouTube companion from this video, transcript, and article." diff --git a/agent-skills/media/build-youtube-companion-runbooks/assets/youtube-companion-template.md b/agent-skills/media/build-youtube-companion-runbooks/assets/youtube-companion-template.md new file mode 100644 index 0000000..b00ae13 --- /dev/null +++ b/agent-skills/media/build-youtube-companion-runbooks/assets/youtube-companion-template.md @@ -0,0 +1,142 @@ +# YouTube Companion + +This runbook packages `[VIDEO OR ARTICLE TITLE]` for YouTube and social distribution. + +Article: `[LINK TO CONTENT.MD OR PUBLIC ARTICLE]` + +Source video: `[LOCAL MASTER OR VERIFIED PUBLIC VIDEO]` + +Source captions: `[LINK TO TRANSCRIPT OR CAPTIONS]` + +Public video URL: `[ADD YOUTUBE URL BEFORE GOING LIVE]` + +Public article URL: `[ADD ARTICLE URL BEFORE GOING LIVE]` + +## Recommended Package + +**Title:** `[RECOMMENDED TITLE]` + +**Thumbnail text:** `[TWO TO FOUR WORDS]` + +**Opening promise:** `[ONE SOURCE-BACKED SENTENCE]` + +`[EXPLAIN WHY THIS PACKAGE FITS THE RECORDING AND NAME ANY MISLEADING CLAIM TO AVOID.]` + +## Hook Options + +- `[HOOK 1]` +- `[HOOK 2]` +- `[HOOK 3]` +- `[HOOK 4]` +- `[HOOK 5]` + +## Title Ideas + +1. `[TITLE 1]` +2. `[TITLE 2]` +3. `[TITLE 3]` +4. `[TITLE 4]` +5. `[TITLE 5]` + +## YouTube Title A/B Hooks + +- `[A/B TITLE 1]` +- `[A/B TITLE 2]` +- `[A/B TITLE 3]` +- `[A/B TITLE 4]` +- `[A/B TITLE 5]` + +## Thumbnail Direction + +### Primary + +- `[OWNED BASE FRAME OR ARTICLE VISUAL]` +- Main text: `[SHORT PHRASE]` +- `[SUBJECT, CROP, HIERARCHY, AND COLOR NOTES]` + +### Alternate + +- `[SECOND OWNED FRAME OR COMPOSITION]` +- Main text: `[SHORT PHRASE]` +- `[SUBJECT, CROP, HIERARCHY, AND COLOR NOTES]` + +Avoid `[SPECIFIC MISLEADING OR GENERIC THUMBNAIL CHOICES]`. + +## Chapter Timestamps + +```text +00:00 [OPENING RESULT OR TENSION] +00:30 [FIRST REAL TOPIC CHANGE] +01:20 [NEXT REAL TOPIC CHANGE] +``` + +Recheck these timestamps against the final uploaded file. + +## YouTube Description + +```text +[TWO-LINE RESULT AND WORKFLOW HOOK] + +In this video, I show: + +- [STEP OR LESSON] +- [STEP OR LESSON] +- [STEP OR LESSON] + +Chapters: +00:00 [OPENING RESULT OR TENSION] +00:30 [FIRST REAL TOPIC CHANGE] +01:20 [NEXT REAL TOPIC CHANGE] + +Resources: +Full article: [ADD ARTICLE URL BEFORE GOING LIVE] +[FIRST-PARTY RESOURCE NAME]: [VERIFIED URL] +``` + +## Social Share + +```text +[SHORT FIRST-PERSON HOOK] + +[CONCRETE WORKFLOW OR RESULT] + +Watch: [ADD YOUTUBE URL BEFORE GOING LIVE] +Article: [ADD ARTICLE URL BEFORE GOING LIVE] +``` + +## LinkedIn Post + +```text +[CONCRETE PROBLEM OR RESULT] + +[WORKFLOW WITH SPECIFIC STEPS, DECISIONS, OR EVIDENCE] + +Full video: [ADD YOUTUBE URL BEFORE GOING LIVE] +Article: [ADD ARTICLE URL BEFORE GOING LIVE] +``` + +## Pinned Comment + +```text +[BEST PRACTICAL TAKEAWAY] + +Article: [ADD ARTICLE URL BEFORE GOING LIVE] + +[ONE USEFUL QUESTION FOR VIEWERS] +``` + +## Short Description + +```text +[ONE OR TWO SENTENCES FOR METADATA OR PREVIEWS] +``` + +## Upload Checklist + +- Replace every `[ADD ... BEFORE GOING LIVE]` gate with a verified public URL. +- Recheck chapters against the final upload. +- Export the thumbnail at 1280 by 720 and inspect it at phone size. +- Confirm product, model, creator, and repository spelling. +- Confirm all public resource links open without authentication. +- Add no download claim unless the real bundle and public link exist. +- Add the final YouTube URL back to the related article after upload. diff --git a/agent-skills/media/build-youtube-companion-runbooks/scripts/validate_youtube_companion.py b/agent-skills/media/build-youtube-companion-runbooks/scripts/validate_youtube_companion.py new file mode 100644 index 0000000..d554a1b --- /dev/null +++ b/agent-skills/media/build-youtube-companion-runbooks/scripts/validate_youtube_companion.py @@ -0,0 +1,169 @@ +#!/usr/bin/env python3 +"""Validate the structure and chapter timing of a YouTube companion runbook.""" + +from __future__ import annotations + +import argparse +import re +import sys +from pathlib import Path + + +REQUIRED_HEADINGS = ( + "# YouTube Companion", + "## Recommended Package", + "## Hook Options", + "## Title Ideas", + "## Thumbnail Direction", + "## Chapter Timestamps", + "## YouTube Description", + "## Social Share", + "## LinkedIn Post", + "## Pinned Comment", + "## Short Description", + "## Upload Checklist", +) + +PUBLICATION_GATES = ( + "[ADD YOUTUBE URL BEFORE GOING LIVE]", + "[ADD ARTICLE URL BEFORE GOING LIVE]", + "[ADD RESOURCE ZIP URL BEFORE GOING LIVE]", +) + +CHAPTER_PATTERN = re.compile( + r"^(?P(?:\d+:)?[0-5]?\d:[0-5]\d)\s+(?P