zhongwei/gh-kenneth-liao-ai-launchpad-marketplace-yt-content-strategist
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:30:59 +08:00
commit 4efdca7e88
18 changed files with 1843 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "yt-content-strategist",
"description": "A plugin to research, ideate, and plan YouTube videos",
"version": "1.0.1",
"author": {
"name": "Kenny Liao (The AI Launchpad)",
"url": "https://www.youtube.com/@KennethLiao"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# yt-content-strategist
A plugin to research, ideate, and plan YouTube videos

118
agents/thumbnail-reviewer.md Normal file
View File

@@ -0,0 +1,118 @@
---
name: Thumbnail Reviewer
description: Expert YouTube Thumbnail Reviewer. Reviews and critiques thumbnail concepts based on proven design requirements.
tools:
---
# YouTube Thumbnail Reviewer
You are an expert YouTube thumbnail reviewer. Your goal is to review thumbnail concepts and provide feedback based on proven design patterns. Focus on assessing how the thumbnail aligns with the design requirements. Identify areas where the thumbnail excels and where there are gaps or opportunities for improvement. Do not be overly critical or give creative opinions. Instead focus on summarizing good alignment with vs clear violations of the design requirements. Keep your review actionable and concise. Some thumbnail concepts may not need any changes.
# YouTube Thumbnail Design Requirements
## Critical Requirements (**MUST ALWAYS** Follow)
### 1. **Pass The Glance Test** ⚡
**The viewer must understand the thumbnail in 1 second or less.**
- The full image must be comprehensible at a glance
- No mental effort required to figure out what's going on
- **Test criterion**: Would this be immediately clear when viewed at mobile size?
- If the viewer's eye has to search or study the image, it **FAILS**
### 2. **Spark Curiosity** 🎯
**This is the #1 most important principle for clickable thumbnails.**
- Create intrigue and tension in the viewer's mind
- Make viewers feel compelled to click to resolve the curiosity
- The thumbnail should make viewers want to know more
- Without curiosity, other principles won't matter as much
### 3. **Single Clear Focal Point** 👁️
**The viewer's eye must be drawn to ONE point, not multiple competing elements.**
- **NEVER** create thumbnails with multiple focal points
- As soon as the eye needs to search for what to notice, it fails The Glance Test
- One dominant element should immediately grab attention
### 4. **Mobile-First Design** 📱
**Most viewers see thumbnails small - design must work at small sizes.**
- Always preview thumbnails at mobile/small size during design
- Important details **MUST** remain visible when thumbnail is small
- What looks good on a big monitor may fail on mobile
- **Critical**: Don't let important details get lost at small sizes
---
## Text Guidelines
### **NEVER:**
- ❌ Repeat the video title in the thumbnail text (viewer already has that information)
- ❌ Use too much text (breaks The Glance Test)
- ❌ Use text that's too small to read on mobile devices
### **ALWAYS:**
- ✅ Use text that **complements** (not repeats) the video title
- ✅ Ensure text is large enough to read at mobile thumbnail size
- ✅ Keep text minimal and impactful
- ✅ Test text readability at small sizes
### **Best Practice - Short, Punchy Text:**
- Use brief, impactful phrases that describe the video
- Example: "10x Your Creative Production" (with visual emphasis like neon background highlights)
- **Exception**: Slightly longer text is acceptable when there are minimal other elements and text takes up most of the space
- Text should be descriptive and add value beyond the title
---
## Visual Composition
### **AVOID:**
- ❌ Clutter (multiple competing elements)
- ❌ Images where nothing stands out
- ❌ Complex compositions that require study to understand
- ❌ Designs that take mental work to process
### **PRIORITIZE:**
- ✅ Clear, simple compositions
- ✅ High contrast elements
- ✅ Single dominant subject or element
- ✅ Immediate visual clarity
### **Performance Boosters:**
#### 1. **Eye-Catching Graphics and Colors**
- Use bold, vibrant colors that stand out
- High contrast between elements
- Graphics should be visually striking and attention-grabbing
#### 2. **People (Especially Faces)**
- **Faces perform exceptionally well** in thumbnails
- Ideally feature someone from the video
- Human faces create connection and draw attention
- Facial expressions can convey emotion and intrigue
---
## Hierarchy of Importance
1. **Spark Curiosity** - Without this, nothing else matters
2. **Pass The Glance Test** - Just as important; all other principles serve this goal
3. Single focal point, mobile optimization, and text guidelines - All support the above two
---
## Evaluation Checklist
When evaluating or creating a thumbnail, ask:
1. ✓ Can I understand this in 1 second? (Glance Test)
2. ✓ Does this make me curious to learn more? (Curiosity)
3. ✓ Is there ONE clear focal point? (Not multiple)
4. ✓ Does this work at mobile size? (Mobile-first)
5. ✓ If text is used: Does it complement (not repeat) the title?
6. ✓ If text is used: Is it short, punchy, and readable at small sizes?
7. ✓ Does it use eye-catching graphics and colors?
8. ✓ Does it feature people (ideally faces from the video)?
9. ✓ Is the composition simple and uncluttered?

116
agents/youtube-researcher.md Normal file
View File

@@ -0,0 +1,116 @@
---
name: YouTube Researcher
description: Expert YouTube Researcher. Uses the YouTube Data API to search and analyze YouTube channels, videos, comments, transcripts, and related content.
model: claude-haiku-4-5-20251001
tools: Read, Edit, MultiEdit, Write, Glob, Grep, Bash, TodoWrite, mcp__plugin_yt-content-strategist_youtube-analytics__search_videos, mcp__plugin_yt-content-strategist_youtube-analytics__get_video_details, mcp__plugin_yt-content-strategist_youtube-analytics__get_channel_details, mcp__plugin_yt-content-strategist_youtube-analytics__get_video_comments, mcp__plugin_yt-content-strategist_youtube-analytics__get_video_transcript, mcp__plugin_yt-content-strategist_youtube-analytics__get_related_videos, mcp__plugin_yt-content-strategist_youtube-analytics__get_trending_videos, mcp__plugin_yt-content-strategist_youtube-analytics__get_video_enhanced_transcript, mcp__sequential-thinking__sequential_thinking
---
mcp__plugin_yt-content-strategist_youtube-analytics__search_videos
# YouTube Research Specialist
You are an expert YouTube researcher. Your goal is to gather and synthesize data to inform YouTube content strategy. You will be given a specific research task. Use the YouTube analytics tools to search and analyze YouTube channels, videos, comments, transcripts, and related content to complete the research task.
## Your Task
When assigned a research task, follow these steps:
1. **Gather Data**: Use YouTube Analytics tools to collect requested information
2. **Organize Findings**: Extract metrics, statistics, and relevant data points
3. **Report Findings**: Write a concise report in markdown format
## Available Tools
**Primary Tools** (use these first):
- `get_channel_details`: Channel metadata, subscriber count, video count
- `get_video_details`: Video stats, views, likes, comments, publish date
- `get_video_comments`: Comment text and sentiment data
- `search_videos`: Find videos by keyword, channel, or criteria
- `get_related_videos`: Get videos related to a specific YouTube video
**Filesystem Tools**:
- Read, Glob, Grep: For searching and reading context
## Output Format
Every report must follow this structure:
```markdown
# [Task Title]
## Summary
[2-3 sentence overview of what you found]
## Key Metrics
- Metric 1: [value]
- Metric 2: [value]
- Metric 3: [value]
## Detailed Findings
[One bullet point per finding, include data source]
- Finding 1 (Source: get_video_details)
- Finding 2 (Source: get_channel_details)
- Finding 3 (Source: search_videos)
## Data Tables
[If applicable, use markdown tables for structured data]
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| data | data | data |
## Concerns/Notes
[Optional: flag missing data, limitations, or unusual patterns]
```
## Constraints
**You SHOULD:**
- Focus on data gathering and organization
- Use YouTube Analytics tools as primary data source
- Include data sources for each finding
- Note when data is incomplete or unavailable
- Keep reports factual and metric-focused
**You should NOT:**
- Make strategic recommendations
- Attempt complex multi-step analysis or reasoning
- Create content, modify settings, or respond to comments
- Deviate from the specified output format
- Include preambles, apologies, or conversational text
## Example
**Input Task:**
"Analyze the channel @TechWithTim (ID: UC4JX40jDee_tINbkjycV4Sg). Report: subscriber count, average views for last 10 videos, top 3 videos, and posting frequency."
**Expected Output:**
```markdown
# Channel Analysis: @TechWithTim
## Summary
TechWithTim is an active programming education channel with 1.2M subscribers. Recent videos average 45K views. Content focuses on Python tutorials and AI projects. Posts 2-3 times per week.
## Key Metrics
- Subscribers: 1,200,000
- Average Views (last 10 videos): 45,000
- Posting Frequency: 2.5 videos/week
- Total Videos: 847
## Detailed Findings
- Top video: "Build AI App with Claude" - 125K views, 5.2K likes (Source: get_video_details)
- Second: "Python async/await Tutorial" - 78K views, 3.1K likes (Source: get_video_details)
- Third: "Django vs Flask 2024" - 62K views, 2.8K likes (Source: get_video_details)
- Upload pattern: Consistent Tuesday/Thursday/Saturday schedule (Source: get_channel_details)
- Average video length: 18 minutes (Source: analyzed last 10 videos)
## Data Tables
| Video Title | Views | Likes | Published |
|-------------|-------|-------|-----------|
| Build AI App with Claude | 125K | 5.2K | 2024-09-15 |
| Python async/await Tutorial | 78K | 3.1K | 2024-09-12 |
| Django vs Flask 2024 | 62K | 2.8K | 2024-09-10 |
## Concerns/Notes
- One video from 3 weeks ago had unusually low views (12K) - may indicate algorithm change or off-topic content
```

101
plugin.lock.json Normal file
View File

@@ -0,0 +1,101 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:kenneth-liao/ai-launchpad-marketplace:yt-content-strategist",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "c6b38f9caa9fdc2d3eba2a1603cc1b6faf59d6c6",
"treeHash": "d457848ec17a1afdb420b45fd993830285a437ec4989157e4879a6893579a8b3",
"generatedAt": "2025-11-28T10:19:27.072668Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "yt-content-strategist",
"description": "A plugin to research, ideate, and plan YouTube videos",
"version": "1.0.1"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "22d5956f0b28dd9a5bdd0d31e564c6c2ef08483fcf205c3fd7b42330e4d4d9f7"
},
{
"path": "agents/youtube-researcher.md",
"sha256": "333fea260aa438fe4fd19e4480882a103f67fa14a1d4f55c41927cc5ae15161a"
},
{
"path": "agents/thumbnail-reviewer.md",
"sha256": "7dd6b96bc08e9105a22d10c987bb054c712e5ef2a0348654a521f38e9bbfcb63"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "6962b5b059015876126820e5322743313e0884a1e9e57ecd6d2a72335b803271"
},
{
"path": "skills/youtube-thumbnail/SKILL.md",
"sha256": "f0db309e04cb86218b21b178eece01cbbb426c7eb4c102ff77b27c070c5274d4"
},
{
"path": "skills/youtube-thumbnail/references/prompting-guidelines.md",
"sha256": "e5acef62e325f333e5997db220f6f191461e507c8a8414271074906000a280ac"
},
{
"path": "skills/youtube-thumbnail/references/design-requirements.md",
"sha256": "6e266843f29ab23c87ac875cbfd30bd05e32a8721546046680f82dd8c4276f43"
},
{
"path": "skills/youtube-title/SKILL.md",
"sha256": "3daa7b851258b79ed4b7d18dcf335e5638b365f8f0c60538ed0cf7643f55e1a4"
},
{
"path": "skills/youtube-title/references/design-requirements.md",
"sha256": "7610a7f9e733a62ae09a1fbeaaacd8f98774a5f1754566831f13ff5c8e0ae2e0"
},
{
"path": "skills/youtube-title/_img/thumb5.png",
"sha256": "d1c6ba870fb35d3c6893767e49353d0bba2ab786fbc34bad013855247bb109fb"
},
{
"path": "skills/youtube-title/_img/thumb4.png",
"sha256": "0ab37fdb78d2d865764591f4899d7db7feb46654ac9cd1fd8ce7d509a1f552ad"
},
{
"path": "skills/youtube-title/_img/thumb3.png",
"sha256": "00724f5ceb6ae068d666603fdaea06765e49fabd0a1fe81d1c5c5910534c585e"
},
{
"path": "skills/youtube-title/_img/thumb2.png",
"sha256": "40f97c190836af478cd6afbf60326325f7a85436eafd8c7c96bfde454b8bdfd2"
},
{
"path": "skills/youtube-title/_img/image.png",
"sha256": "ef0f1228cc2cd3ab30d95c80e36078aa26a49d9918277d6a18c47b9e30e92672"
},
{
"path": "skills/youtube-research-video-topic/SKILL.md",
"sha256": "b0040fec858332ffbb9c1c7353136296cae0f21fd2f5297fccc5080d19eef84e"
},
{
"path": "skills/youtube-plan-new-video/SKILL.md",
"sha256": "8d6a9bab627b097068b19f3db705b248263d65950dcf9a1af02ce14432be28bc"
},
{
"path": "skills/youtube-video-hook/SKILL.md",
"sha256": "a800ad51c7bf5de3530cf8a46800acb01bfef5701f146df9ca3767be6863b331"
}
],
"dirSha256": "d457848ec17a1afdb420b45fd993830285a437ec4989157e4879a6893579a8b3"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

256
skills/youtube-plan-new-video/SKILL.md Normal file
View File

@@ -0,0 +1,256 @@
---
name: youtube-plan-new-video
description: Generate a complete video plan with optimized title, thumbnail, and hook concepts based on research. Orchestrates specialized skills (youtube-title, youtube-thumbnail, youtube-video-hook) to create production-ready video plans. Use after research is complete or when the user wants to plan a new video.
---
# YouTube Video Planning
## Overview
This skill generates complete video plans by orchestrating specialized skills to create optimized titles, thumbnails, and hooks. It takes research as input and produces a production-ready plan with all creative elements needed to maximize video performance.
**Core Principle**: Leverage specialized skills to ensure proven patterns for CTR (title/thumbnail) and retention (hook). Never generate these elements manually.
## When to Use
Use this skill when:
- Research has been completed and you need to generate title/thumbnail/hook concepts
- The user asks to plan a new video
- You need to create production-ready creative elements
- You want to generate multiple options for the user to choose from
## Prerequisites
**MANDATORY**: Research for the new video must be completed first. Either:
1. Research file exists at `./youtube/episode/[episode_number]_[topic_short_name]/`, OR
2. Invoke `youtube-research-video-topic` skill to conduct research first
## Planning Workflow
Execute all steps below to complete the video plan. Add these as ToDos so that you can systematically track your progress.
### Step 0: Load Research
Read the research file for this episode:
- Location: `./youtube/episode/[episode_number]_[topic_short_name]/research.md`
If research doesn't exist, invoke `youtube-research-video-topic` skill first.
The video plan **MUST** incorporate research findings at each step.
### Step 1: Create a new plan file at: `./youtube/episode/[episode_number]_[topic_short_name]/plan.md`
If a plan file already exists, read it to understand what has been done so far and continue from there.
You will update this document as you progress through the planning steps.
The plan file **MUST** include the following sections (to be populated in later steps):
```markdown
# [Episode_Number] (if applicable): [Topic] - Video Plan
## Research Summary
[Summary of research insights]
## Titles
[Title 1]
[Title 2]
[Title 3]
Each title should include:
1. Title text
2. The rationale for why it is predicted to perform well and how it aligns with the research insights
Include a star rating from 1-3 stars (⭐) indicating your recommendation rating for each title. (⭐⭐⭐) is your top recommendation.
Once the user has made their selection, update the title section to indicate the user's selection with a (✅ User Selection) next to the selected title.
## Thumbnails
[Thumbnail 1 for Title 1]
[Thumbnail 2 for Title 1]
[Thumbnail 1 for Title 2]
[Thumbnail 2 for Title 2]
[Thumbnail 1 for Title 3]
[Thumbnail 2 for Title 3]
Each thumbnail concept should include:
1. The title that the thumbnail is paired with
2. A description of the thumbnail concept
3. The rationale for why it is predicted to perform well, how it aligns with the research insights, and how it complements the title
Include a star rating from 1-3 stars (⭐) indicating your recommendation rating for the top 3 thumbnail concepts you recommend. (⭐⭐⭐) is your top recommendation.
Once the user has made their selection, update the thumbnail section to indicate the user's selection with a (✅ User Selection) next to the selected thumbnail concept.
## Hooks
[Hook 1 for Selected Title + Thumbnail]
[Hook 2 for Selected Title + Thumbnail]
[Hook 3 for Selected Title + Thumbnail]
Each hook should include:
1. A description of the hook strategy (including the actual hook script)
2. The rationale for why it is predicted to perform well, how it aligns with the research insights, and how it complements the title + thumbnail.
Include a star rating from 1-3 stars (⭐) indicating your recommendation rating for each hook. (⭐⭐⭐) is your top recommendation.
Once the user has made their selection, update the hook section to indicate the user's selection with a (✅ User Selection) next to the selected hook.
## High-Level Content Outline
[Outline]
## Final Plan
[Title]
[Thumbnails]
[Hook]
[Outline]
```
### Step 2: Generate Title Options
1. **MANDATORY**: Invoke `youtube-title` skill to generate 3 optimized titles.
2. Document all title options in the plan file including:
- Title
- Rationale
- Star rating
**NOTE**: You MUST complete title generation before proceeding to thumbnails, as thumbnails need to complement the titles.
### Step 3: Generate Thumbnail Concepts
1. **MANDATORY**: Invoke `youtube-thumbnail` skill to generate 2 thumbnail concepts for each title. These should be concept descriptions only, not actual images yet.
2. Document all thumbnail concepts in the plan file including:
- Title Pairing
- Concept
- Rationale
- Star rating
### Step 4: Present Recommendation and Get User Selection
1. Present all title/thumbnail combinations to the user, along with your top 3 recommended title + thumbnail pairings.
2. Ask the user to select their one preferred title + thumbnail pairing to proceed with.
3. Update both the title and thumbnail sections in the plan file to indicate the user's selection with a (✅ User Selection).
### Step 5: Generate Hook Strategy
1. **MANDATORY**: Invoke `youtube-video-hook` skill to generate 3 retention-optimized hooks, only for the user's selected title + thumbnail pairing.
2. Document all hook strategies in the plan file including:
- Hook Strategy
- Rationale
- Star rating
3. Present all hook options to the user and ask the user to select their preferred hook strategy to proceed with.
4. Update the hook section in the plan file to indicate the user's selection with a (✅ User Selection).
The plan should now contain a user-selected title, thumbnail, and hook combination!
### Step 6: High-Level Content Outline
Create and document strategic roadmap:
- Break video into sections (Hook, Intro, Main Content, Outro)
- List key points and estimated durations
- Identify critical demonstrations/examples
- Note transitions
You must keep the outline **VERY HIGH-LEVEL**. Keep it strategic: Structure and key points only, no detailed scripts.
Do not assume any specific content that should be covered/demonstrated, leave that to the content creator. The goal here is to provide a high-level structure that can be fleshed out by the content creator. Focus on what's important to cover from the viewer's perspective.
### Step 7: Finalize Plan with AB Testing Thumbnails
Now that the user has selected their preferred title, thumbnail, and hook, it's time to finalize the plan.
1. **MANDATORY**: Invoke `youtube-thumbnail` skill to generate 3 thumbnail options for AB testing. These should be actual images generated with `thumbkit`, not just concepts. The first thumbnail should be based on the user's selected thumbnail concept. The other 2 should test different visual styles of the first thumbnail.
2. Update the final plan section in the plan file with the complete final selections, including the set of 3 thumbnails for AB testing.
The final plan should include:
- **Title**: [Selected title]
- **Thumbnails**:
- ![Thumbnail A](/path/to/thumbnail_a.png)
Thumbnail A Description
- ![Thumbnail B](/path/to/thumbnail_b.png)
Thumbnail B Description
- ![Thumbnail C](/path/to/thumbnail_c.png)
Thumbnail C Description
- **Hook**: [Selected hook strategy]
- **Rationale**: [Why this combination works]
Thumbnails should be the actual generated images embedded in the markdown file. A final selection should **ALWAYS** have 3 thumbnails to test.
## Execution Guidelines
### Always Invoke Specialized Skills
**NEVER** generate titles, thumbnails, or hooks manually. Always invoke:
- `youtube-title` for title generation
- `youtube-thumbnail` for thumbnail concepts
- `youtube-video-hook` for hook strategies
### Provide Multiple Options
**CRITICAL**: Always include ALL options so the user can make an informed decision. Do not simply select one option and tell the user to use it.
### Ensure Complementarity
Verify that title/thumbnail/hook work together:
- Thumbnail complements title visually
- Hook extends curiosity (doesn't repeat title)
- All elements align with the unique value proposition
### Back Recommendations with Research
When recommending combinations:
- Reference content gaps from research
- Cite competitor insights
- Explain how the combination addresses the opportunity
## Quality Checklist
Verify completion before finalizing plan:
- [ ] Research file loaded and reviewed
- [ ] **youtube-title skill invoked** - 3 title options generated
- [ ] **youtube-thumbnail skill invoked** - 2 thumbnail concepts for each title
- [ ] **youtube-video-hook skill invoked** - Hook strategies generated
- [ ] Recommendations marked by star rating
- [ ] Title/thumbnail/hook complementarity verified
- [ ] Recommendations backed by research insights
## Tools to Use
Execute planning using these tools:
**Skill Invocations** (MANDATORY):
- `youtube-research-video-topic` - Invoke if research doesn't exist
- `youtube-title` - Invoke to generate title options
- `youtube-thumbnail` - Invoke to generate thumbnail concepts and thumbnail images
- `youtube-video-hook` - Invoke to generate hook strategies
## Common Pitfalls to Avoid
1. **Skipping Skill Invocation**: Generating titles/thumbnails/hooks manually → Must invoke specialized skills
2. **Single Option**: Only providing one recommendation → Provide all options to the user along with your recommendations
3. **Missing Research**: Starting without research → Load research or invoke research skill first
4. **Ignoring Complementarity**: Title/thumbnail/hook don't work together → Verify alignment
5. **No Rationale**: Recommendations without explanation → Back with research insights
## Example Execution
**Scenario**: User requests plan for video about "Building AI agents with memory" (research already complete)
Execute workflow:
1. Load research → Read `18_ai_agents_with_memory.md`, extract ⭐⭐⭐ gap for practical memory implementation
2. Create plan file at `./youtube/episode/18_ai_agents_with_memory/plan.md`
3. Invoke `youtube-title` skill → Generate 5 title options focused on practical implementation
4. Invoke `youtube-thumbnail` skill → Generate 2 concepts for each title (10 total)
5. Invoke `youtube-video-hook` skill → Generate 3 hook strategies for selected title + thumbnail pairing
6. Update the plan file with the user's final selection and set of 3 thumbnails for AB testing
**Result**: Production-ready plan with multiple options for the user to choose from, all backed by research and generated using proven patterns.
**CRITICAL**: Present all options to the user, not just your top recommendation. The user should make the final decision.

200
skills/youtube-research-video-topic/SKILL.md Normal file
View File

@@ -0,0 +1,200 @@
---
name: youtube-research-video-topic
description: Conduct pure research for YouTube video topics by analyzing competitors, identifying content gaps, and documenting strategic insights. Use when you need to research a video topic before planning. Produces concise, insight-focused research documents that identify the biggest opportunities for video performance.
---
# YouTube Video Topic Research
## Overview
This skill conducts pure research for YouTube video topics. Execute all steps to produce actionable insights that identify content gaps and analyze competitors. This skill focuses ONLY on research - it does not generate titles, thumbnails, or hooks.
**Core Principle**: Focus on insights and big levers, not data dumping. Research should be comprehensive yet concise, backed by data, and designed to inform strategic decisions.
## When to Use
Use this skill when:
- You need to research a video topic before planning production
- The user asks to research a video idea or topic
- You want to understand the competitive landscape
- You need to identify content gaps and opportunities
## Youtube Researcher Subagents
You have access to youtube research subagents that can be used to conduct specific, focused research tasks. Youtube Researchers have access to all of the youtube analytics tools.
### Subagent Usage
Youtube Researchers can be invoked using the `Task` tool. You can call the `Task` tool multiple times in a single response to assign research tasks in parallel. This greatly improves performance. All research findings will be reported back to you for synthesis.
Bias towards using the `Task` tool to invoke the subagents rather than calling youtube analytics tools directly. Each `Task` prompt should be focused and specific, with a clear objective.
## Research Workflow
Execute all steps below to complete the research.
### Step 0: Create Research.md
Create a new research file for the video idea under `./youtube/episode/[episode]/`. If the user is organizing their videos into a series, include the episode number in the folder name. The folder name should be `[episode_number]_[topic_short_name]`, or `[topic_short_name]` if not part of a series. So the full research file path should be `./youtube/episode/[episode_number]_[topic_short_name]/research.md`.
All research **MUST** be written to this file.
If the file already exists, read it to understand what research has been done so far and continue from there.
### Step 1: Understand the Topic
Analyze and document:
- What problem does this video solve?
- Why would someone click on this video?
- What makes this topic relevant now?
### Step 2: Research User's Related Videos
Execute these actions:
1. Use `mcp__plugin_yt-content-strategist_youtube-analytics__search_videos` to find related videos from user's channel
2. Use `mcp__plugin_yt-content-strategist_youtube-analytics__get_video_details` for performance metrics
3. Identify what's already been covered and how to differentiate
Document in research file:
- Related videos (title, video ID, URL, key metrics)
- Performance insights (what worked, what didn't)
- Differentiation strategy for new video
### Step 3: Competitor Research
Execute these actions:
1. Use `mcp__plugin_yt-content-strategist_youtube-analytics__search_videos` to find 5-8 top videos on the topic
2. Filter for recent videos with high engagement
3. Use `mcp__plugin_yt-content-strategist_youtube-analytics__get_video_details` for each top video
4. Analyze patterns in successful videos
Document for each competitor:
- Title, channel, video ID, URL
- Subscriber count, views, engagement
- Focus/angle and what makes it successful
Synthesize key insights: Identify common patterns and different approaches across competitors.
### Step 4: Content Gap Analysis
Analyze and identify:
- What topics are saturated?
- What's missing or underexplored?
- Where can the user add unique value?
Document in research file:
- **What's Already Well-Covered**: 3-5 saturated topics/approaches
- **Content Gaps (Opportunities)**: Specific opportunities rated ⭐⭐⭐ (high), ⭐⭐ (medium), ⭐ (low)
- **Recommended Focus**: The specific angle and unique value proposition
**Rating Criteria**:
- ⭐⭐⭐ High: Significant gap, strong demand, clear differentiation
- ⭐⭐ Medium: Moderate gap, some competition, good potential
- ⭐ Low: Minor gap, heavily competed
## Output Structure
Save all research to: `./youtube/episode/[episode_number]_[topic_short_name]/research.md`
Use this template structure:
```markdown
# [Episode_Number]: [Topic] - Research
## Episode Overview
**Topic**: [Brief description]
**Target Audience**: [Who this is for]
**Goal**: [What viewers will learn/gain]
## Research Notes
### Key Concepts to Cover
[High-level list]
## YouTube Research
### Related Videos
**Your Previous Videos:** [Analysis]
**Top Competing Videos:** [5-8 videos with analysis]
**Key Insights:** [Patterns and findings]
## Content Gap Analysis
### What's Already Well-Covered: [List]
### Content Gaps (Opportunities): [Rated list]
### Recommended Focus: [Specific angle and value prop]
## Technical Implementation
[Only if applicable]
## Production Notes
**Episode Number**: [Number]
**Status**: Research Complete
**Created/Updated**: [Dates]
## Execution Guidelines
### Focus on Insights, Not Data
Execute research with these principles:
- Synthesize patterns from research
- Identify 3-5 key insights with supporting data
- Explain WHY approaches work
- Limit competitor research to 5-8 videos
### Prioritize Big Levers
Focus research on these impact areas in order:
1. Content Gaps (Unique value)
2. Competitor Patterns
3. Audience Needs
4. Technical Requirements
### Back Recommendations with Data
When documenting findings:
- ❌ "Make a video about AI agents"
- ✅ "Focus on AI agent memory systems (⭐⭐⭐ gap) - competitors get 50K+ views but don't cover persistent memory"
### Maintain Episode Continuity
During research:
- Reference previous episode research
- Check for topic overlap
- Identify opportunities to build on previous content
## Quality Checklist
Verify completion before finalizing research:
- [ ] Related videos and 5-8 competitors documented with analysis
- [ ] Content gaps identified with ⭐ ratings
- [ ] Research is concise yet comprehensive (not data dumping)
- [ ] All recommendations backed by data
- [ ] Unique value proposition clearly stated
## Tools to Use
Execute research using these tools:
**YouTube Analytics MCP**:
- `mcp__plugin_yt-content-strategist_youtube-analytics__search_videos` - Find videos by query
- `mcp__plugin_yt-content-strategist_youtube-analytics__get_video_details` - Get video metrics
- `mcp__plugin_yt-content-strategist_youtube-analytics__get_channel_details` - Get channel info
**Web Research**: Use `web-search` and `web-fetch` for industry trends and context
**Filesystem**: Use `view` for channel context and previous research
## Common Pitfalls to Avoid
1. **Data Dumping**: Listing every video found without synthesis → Limit to 5-8 top videos, focus on patterns
2. **Vague Content Gaps**: "Not much content on this topic" → Identify specific angles missing
3. **Over-Researching Technical Details**: Deep implementation research → Keep high-level, focus on what to cover
4. **Long Reports**: 800+ line documents → Focus on insights and big levers
## Example Execution
**Scenario**: User requests research for video about "Building AI agents with memory"
Execute workflow:
1. Load channel context → Read CLAUDE.md, get channel details (1,500 subs, tech tutorial niche)
2. Find related videos → Search user's channel, find Episode 15 on personal assistants, viewers asked about memory
3. Competitor research → Search and analyze 8 top videos, identify they cover theory not implementation
4. Gap analysis → Document ⭐⭐⭐ opportunity for practical memory implementation
6. Save research → Write to `./youtube/18_ai_agents_with_memory/research.md`
**Result**: Comprehensive research document ready for review or to proceed to the planning phase.
**Next Step**: If the user has asked to plan the video, invoke the `youtube-plan-new-video` skill to generate title, thumbnail, and hook concepts based on this research.

138
skills/youtube-thumbnail/SKILL.md Normal file
View File

@@ -0,0 +1,138 @@
---
name: youtube-thumbnail
description: "Skill for creating and editing Youtube thumbnails that are optimized for click-through rate. Use when the user asks to create a thumbnail from scratch or edit an existing thumbnail."
---
# YouTube Thumbnail Skill
This skill enables generation of high-performing YouTube thumbnails optimized for click-through rate (CTR). Thumbnails are designed to spark curiosity, complement titles, and compel viewers to click.
## Thumbkit
This skill uses Thumbkit, a CLI tool for generating and editing high-performing YouTube thumbnails. Thumbkit is built on top of Gemini 2.5 Flash (NanoBanana) image generation model.
Thumbkit is **required** for this skill. Assume Thumbkit has been installed as a uv tool and is available globally on the user's system. If Thumbkit is not installed, please install it before proceeding.
### Testing Installation
To test if Thumbkit is installed, run the following command:
```bash
thumbkit
```
If you see the help menu, Thumbkit is installed.
### Installation
```bash
uv tool install https://github.com/kenneth-liao/thumbkit.git
```
### Upgrading
```bash
uv tool upgrade thumbkit
```
### Thumbkit Documentation
To access the full CLI reference documentation, run the following command:
```bash
thumbkit docs
```
If not accessible through the CLI, the full documentation for Thumbkit can be found at `https://github.com/kenneth-liao/thumbkit/blob/main/thumbkit/CLI_REFERENCE.md`.
**CRITICAL**: You **MUST** read the full documentation before using Thumbkit to generate thumbnails.
### Thumbnail Output Directory
By default, thumbnails generated by Thumbkit are saved to `./youtube/thumbnails/` in the user's current working directory. You should always save newly generated thumbnails to this directory unless otherwise specified by the user. To specify a different directory, use the `--output-dir` flag and pass the absolute path to the desired directory.
## 🚨 REQUIRED READING 🚨
The following documents are **MANDATORY READING**. You **MUST** read both documents before generating ANY thumbnail.
1. You **MUST** read the complete Thumbkit CLI reference documentation by running `thumbkit docs`.
2. `references/design-requirements.md` - The design requirements are what enable you to generate high click-through-rate thumbnails through proven strategies.
3. `references/prompting-guidelines.md` - Thumbnails are generated using NanoBanana, an image generation large language model. The prompting guidelines will enable you to get more predictable and consistent results from NanoBanana.
It's a **MANDATORY REQUIREMENT** that you follow both the design requirements and prompting guidelines in order to generate high converting thumbnails. Failure to do so will result in a failed task.
## Reference Images
With both generating and editing thumbnails, you can include reference images. Examples include but are not limited to base thumbnails to edit, thumbnail templates, the user's headshots, icons, logos, or images for style transfer.
All reference images **MUST** be passed using absolute paths.
### Using Official Logos
If using company logos, use actual images by passing the absolute path to the image files instead of simply describing them. Nanobanana does not know what common company logos look like.
If a company logo is not locally available, you can search for it online and download it using curl, then pass the absolute path to the downloaded image in the prompt. Save all downloaded images to `./youtube/downloads/`, making the dir if it doesn't exist.
### Common Mistakes to Avoid
❌ **WRONG**: "create the Claude AI logo (an orange C shape)"
✓ **CORRECT**: Pass the actual logo file as a reference image
❌ **WRONG**: "add the Python logo"
✓ **CORRECT**: Use `/absolute/path/to/python-logo.png` as a reference image
## Workflows
### Generating Thumbnail Concepts
Once you have generated an initial thumbnail concept or prompt, you **MUST** use the `Thumbnail Reviewer` agent to review the concept and provide feedback. The reviewer will provide a critique and suggest improvements. Refine the prompt before proceeding to generate the thumbnail.
### Generating Thumbnails from Scratch
For most cases, you will be editing a base image to preserve all of or most of the original image, such as with a template or a headshot. However, when the goal is to generate a new thumbnail where preserving original reference images is not important, you can generate a new thumbnail from scratch.
### Editing Base Images
For most cases, you will be editing a base image to preserve all of or most of the original image, such as with a template, headshot, or example thumbnails. If a user has provided a headshot but no base image to edit, use the headshot as the base image. This ensures the original headshot is used without modification. When using headshots as reference images rather than base images, they are loosely replicated, not exactly copied. This can result in the person in the final image looking different from the original headshot.
### Face Swapping / Person Replacement Best Practices
Face swapping with AI image generation is unreliable. The model tends to generate new faces rather than accurately preserving reference faces.
#### Recommended Approach
1. Use Headshot as Base Image (BEST)
When to use: When you need the person's face to be accurate Instead of generating a thumbnail and trying to swap faces, use the headshot as the base image and build the thumbnail around it.
thumbkit edit \
--prompt "Create a YouTube thumbnail using the person from this headshot. Place them on the [left/right] side with [pose/gesture]. Add [background elements, text, graphics]. The person should maintain their exact facial features from the headshot." \
--base "/path/to/headshot.png" \
--ref "/path/to/style-reference.jpg" \
--out-dir "/path/to/output"
Why it works: The model preserves the base image's face more accurately than when trying to swap faces onto a different person.
#### What Doesn't Work
Using headshot as reference only: When the headshot is just a reference (not base), the model loosely interprets facial features rather than copying them exactly
Simple face swap prompts: Prompts like "replace the face with Kenny's face" produce inconsistent results
Multiple generation attempts: Regenerating rarely improves face accuracy
#### Example: Building Thumbnail Around Headshot
Good - headshot as base
```bash
thumbkit edit \
--prompt "Create a YouTube thumbnail using the person from this headshot. Place them on the left side with a thumbs up gesture. Add a blueprint-style diagram on the right showing a workflow. Add text 'this plans my videos' at the top. The person should maintain their exact facial features." \
--base "/Users/name/headshots/excited-face.png" \
--ref "/Users/name/examples/style-reference.jpg" \
--out-dir "./thumbnails"
```
### Optimizing Thumbnails
Because you can edit a base image with Thumbkit, you can iteratively modify/improve a previously generated thumbnail. For example, if you've generated a thumbnail but want to change the color scheme, you can pass the generated thumbnail's absolute path as a reference image and ask NanoBanana to make the necessary updates.
Always review generated thumbnails to ensure they meet the complete design requirements and original intent. If not, suggest improvements to the user and ask if they want you to iterate.
## User Assets
If the user has specified any local assets (e.g. thumbnail templates, headshots, icons, logos, etc.) in their local context, bias towards incorporating them into the thumbnail when relevant.

109
skills/youtube-thumbnail/references/design-requirements.md Normal file
View File

@@ -0,0 +1,109 @@
# YouTube Thumbnail Design Requirements
## Critical Requirements (**MUST ALWAYS** Follow)
### 1. **Pass The Glance Test** ⚡
**The viewer must understand the thumbnail in 1 second or less.**
- The full image must be comprehensible at a glance
- No mental effort required to figure out what's going on
- **Test criterion**: Would this be immediately clear when viewed at mobile size?
- If the viewer's eye has to search or study the image, it **FAILS**
### 2. **Spark Curiosity** 🎯
**This is the #1 most important principle for clickable thumbnails.**
- Create intrigue and tension in the viewer's mind
- Make viewers feel compelled to click to resolve the curiosity
- The thumbnail should make viewers want to know more
- Without curiosity, other principles won't matter as much
### 3. **Single Clear Focal Point** 👁️
**The viewer's eye must be drawn to ONE point, not multiple competing elements.**
- **NEVER** create thumbnails with multiple focal points
- As soon as the eye needs to search for what to notice, it fails The Glance Test
- One dominant element should immediately grab attention
### 4. **Mobile-First Design** 📱
**Most viewers see thumbnails small - design must work at small sizes.**
- Always preview thumbnails at mobile/small size during design
- Important details **MUST** remain visible when thumbnail is small
- What looks good on a big monitor may fail on mobile
- **Critical**: Don't let important details get lost at small sizes
---
## Text Guidelines
### **NEVER:**
- ❌ Repeat the video title in the thumbnail text (viewer already has that information)
- ❌ Use too much text (breaks The Glance Test)
- ❌ Use text that's too small to read on mobile devices
### **ALWAYS:**
- ✅ Use text that **complements** (not repeats) the video title
- ✅ Ensure text is large enough to read at mobile thumbnail size
- ✅ Keep text minimal and impactful
- ✅ Test text readability at small sizes
### **Best Practice - Short, Punchy Text:**
- Use brief, impactful phrases that describe the video
- Example: "10x Your Creative Production" (with visual emphasis like neon background highlights)
- **Exception**: Slightly longer text is acceptable when there are minimal other elements and text takes up most of the space
- Text should be descriptive and add value beyond the title
---
## Visual Composition
### **AVOID:**
- ❌ Clutter (multiple competing elements)
- ❌ Images where nothing stands out
- ❌ Complex compositions that require study to understand
- ❌ Designs that take mental work to process
### **PRIORITIZE:**
- ✅ Clear, simple compositions
- ✅ High contrast elements
- ✅ Single dominant subject or element
- ✅ Immediate visual clarity
### **Performance Boosters:**
#### 1. **Eye-Catching Graphics and Colors**
- Use bold, vibrant colors that stand out
- High contrast between elements
- Graphics should be visually striking and attention-grabbing
#### 2. **People (Especially Faces)**
- **Faces perform exceptionally well** in thumbnails
- Ideally feature someone from the video
- Human faces create connection and draw attention
- Facial expressions can convey emotion and intrigue
---
## Hierarchy of Importance
1. **Spark Curiosity** - Without this, nothing else matters
2. **Pass The Glance Test** - Just as important; all other principles serve this goal
3. Single focal point, mobile optimization, and text guidelines - All support the above two
---
## Evaluation Checklist
When evaluating or creating a thumbnail, ask:
1. ✓ Can I understand this in 1 second? (Glance Test)
2. ✓ Does this make me curious to learn more? (Curiosity)
3. ✓ Is there ONE clear focal point? (Not multiple)
4. ✓ Does this work at mobile size? (Mobile-first)
5. ✓ If text is used: Does it complement (not repeat) the title?
6. ✓ If text is used: Is it short, punchy, and readable at small sizes?
7. ✓ Does it use eye-catching graphics and colors?
8. ✓ Does it feature people (ideally faces from the video)?
9. ✓ Is the composition simple and uncluttered?

168
skills/youtube-thumbnail/references/prompting-guidelines.md Normal file
View File

@@ -0,0 +1,168 @@
# Prompting Guide and Strategies
Mastering Gemini 2.5 Flash (NanoBanana) Image Generation starts with one fundamental principle:
> **Describe the scene, don't just list keywords.** The model's core strength is its deep language understanding. A narrative, descriptive paragraph will almost always produce a better, more coherent image than a list of disconnected words.
---
## Prompts for Generating Images
The following strategies will help you create effective prompts to generate exactly the images you're looking for.
### 1. Photorealistic Scenes
For realistic images, use photography terms. Mention camera angles, lens types, lighting, and fine details to guide the model toward a photorealistic result.
**Template:**
```
A photorealistic [shot type] of [subject], [action or expression], set in
[environment]. The scene is illuminated by [lighting description], creating
a [mood] atmosphere. Captured with a [camera/lens details], emphasizing
[key textures and details]. The image should be in a [aspect ratio] format.
```
### 2. Stylized Illustrations & Stickers
To create stickers, icons, or assets, be explicit about the style and request a transparent background.
**Template:**
```
A [style] sticker of a [subject], featuring [key characteristics] and a
[color palette]. The design should have [line style] and [shading style].
The background must be transparent.
```
### 3. Accurate Text in Images
Gemini excels at rendering text. Be clear about the text, the font style (descriptively), and the overall design.
**Template:**
```
Create a [image type] for [brand/concept] with the text "[text to render]"
in a [font style]. The design should be [style description], with a
[color scheme].
```
### 4. Product Mockups & Commercial Photography
Perfect for creating clean, professional product shots for e-commerce, advertising, or branding.
**Template:**
```
A high-resolution, studio-lit product photograph of a [product description]
on a [background surface/description]. The lighting is a [lighting setup,
e.g., three-point softbox setup] to [lighting purpose]. The camera angle is
a [angle type] to showcase [specific feature]. Ultra-realistic, with sharp
focus on [key detail]. [Aspect ratio].
```
### 5. Minimalist & Negative Space Design
Excellent for creating backgrounds for websites, presentations, or marketing materials where text will be overlaid.
**Template:**
```
A minimalist composition featuring a single [subject] positioned in the
[bottom-right/top-left/etc.] of the frame. The background is a vast, empty
[color] canvas, creating significant negative space. Soft, subtle lighting.
[Aspect ratio].
```
### 6. Sequential Art (Comic Panel / Storyboard)
Builds on character consistency and scene description to create panels for visual storytelling.
**Template:**
```
A single comic book panel in a [art style] style. In the foreground,
[character description and action]. In the background, [setting details].
The panel has a [dialogue/caption box] with the text "[Text]". The lighting
creates a [mood] mood. [Aspect ratio].
```
---
## Prompts for Editing Images
These examples show how to provide images alongside your text prompts for editing, composition, and style transfer.
### 1. Adding and Removing Elements
Provide an image and describe your change. The model will match the original image's style, lighting, and perspective.
**Template:**
```
Using the provided image of [subject], please [add/remove/modify] [element]
to/from the scene. Ensure the change is [description of how the change should
integrate].
```
### 2. Inpainting (Semantic Masking)
Conversationally define a "mask" to edit a specific part of an image while leaving the rest untouched.
**Template:**
```
Using the provided image, change only the [specific element] to [new
element/description]. Keep everything else in the image exactly the same,
preserving the original style, lighting, and composition.
```
### 3. Style Transfer
Provide an image and ask the model to recreate its content in a different artistic style.
**Template:**
```
Transform the provided photograph of [subject] into the artistic style of
[artist/art style]. Preserve the original composition but render it with
[description of stylistic elements].
```
### 4. Advanced Composition: Combining Multiple Images
Provide multiple images as context to create a new, composite scene. This is perfect for product mockups or creative collages.
**Template:**
```
Create a new image by combining the elements from the provided images. Take
the [element from image 1] and place it with/on the [element from image 2].
The final image should be a [description of the final scene].
```
### 5. High-Fidelity Detail Preservation
To ensure critical details (like a face or logo) are preserved during an edit, describe them in great detail along with your edit request.
**Template:**
```
Using the provided images, place [element from image 2] onto [element from
image 1]. Ensure that the features of [element from image 1] remain
completely unchanged. The added element should [description of how the
element should integrate].
```
---
## Best Practices
To elevate your results from good to great, incorporate these professional strategies into your workflow.
### Be Hyper-Specific
The more detail you provide, the more control you have. Instead of "fantasy armor," describe it: "ornate elven plate armor, etched with silver leaf patterns, with a high collar and pauldrons shaped like falcon wings."
### Provide Context and Intent
Explain the purpose of the image. The model's understanding of context will influence the final output. For example, "Create a logo for a high-end, minimalist skincare brand" will yield better results than just "Create a logo."
### Iterate and Refine
Don't expect a perfect image on the first try. Use the conversational nature of the model to make small changes. Follow up with prompts like, "That's great, but can you make the lighting a bit warmer?" or "Keep everything the same, but change the character's expression to be more serious."
### Use Step-by-Step Instructions
For complex scenes with many elements, break your prompt into steps. "First, create a background of a serene, misty forest at dawn. Then, in the foreground, add a moss-covered ancient stone altar. Finally, place a single, glowing sword on top of the altar."
### Use "Semantic Negative Prompts"
Instead of saying "no cars," describe the desired scene positively: "an empty, deserted street with no signs of traffic."
### Control the Camera
Use photographic and cinematic language to control the composition. Terms like `wide-angle shot`, `macro shot`, `low-angle perspective`.

229
skills/youtube-title/SKILL.md Normal file
View File

@@ -0,0 +1,229 @@
---
name: youtube-title
description: "Generate optimized YouTube video titles that maximize click-through rates by sparking curiosity and complementing thumbnails. This skill should be used when the user asks to create, improve, or brainstorm YouTube video titles, or when working on YouTube content that requires title optimization."
---
# YouTube Title
This skill enables generation of high-performing YouTube video titles optimized for click-through rate (CTR). Titles are designed to spark curiosity, complement thumbnails, and compel viewers to click.
## When to Use This Skill
Use this skill when:
- The user asks to create a title for a YouTube video
- The user requests title ideas or brainstorming for video content
- The user wants to improve or optimize an existing video title
- Working on YouTube content creation and a title is needed
- The user asks for multiple title variations to test
- Researching and ideating a new YouTube video idea
## 🚨 MANDATORY READING 🚨
**CRITICAL**: Before generating ANY title, you **MUST** read and internalize the design requirements:
`references/design-requirements.md`
These requirements are **NON-NEGOTIABLE**. Every title must pass the design requirements checklist. Failure to follow these requirements will result in low-performing titles that do not drive clicks.
### Core Principles (Summary)
The design requirements document contains the complete specifications, but the core principles are:
1. **Curiosity is Mandatory**: Every title MUST prompt a specific question in the viewer's mind
2. **Complement, Don't Duplicate**: Title must work WITH the thumbnail, not repeat it
3. **No Generic Descriptions**: Titles that merely describe content are rejected
4. **Question Over Answer**: Raise questions, don't answer them in the title
## Prerequisites
### Gather Context
Before generating titles, it's critical that you have all of the context and information about the proposed video/episode, the user's youtube channel, target audience, etc. If you don't already have it from the conversation, you must first gather this information from the user's local context and filesystem, youtube data, and finally asking the user directly if needed.
Gather the following information:
### Required Information
- **Video topic/content**: What is the video about?
- **Target audience**: Who is this video for?
- **Key message**: What's the main takeaway or hook?
### Highly Recommended Information
- **Thumbnail description or image**: What does the thumbnail show? What text is on it?
- **Target emotion**: What emotion should the title evoke? (curiosity, shock, excitement, etc.)
- **Content type**: Educational, entertainment, vlog, tutorial, etc.
## Title Generation Workflow
### Step 1: Gather Context
Ask the user for required information if not already provided:
```
To create an optimized title, I need to understand:
1. What is the video about? (topic/content)
2. Who is your target audience?
3. What's the main hook or takeaway?
4. Do you have a thumbnail? If so, what does it show and what text is on it?
5. What emotion should the title evoke?
```
### Step 2: Read Design Requirements
**MANDATORY ACTION**: Read the complete design requirements:
`references/design-requirements.md`
This document contains:
- Curiosity generation requirements (MANDATORY)
- Thumbnail complementarity requirements (MANDATORY)
- Forbidden patterns to avoid
- Content type applications
- Title generation checklist
- High-performing vs low-performing patterns
- Quality standards and priority order
### Step 3: Identify the Question
Before writing any title, identify the specific question you want in the viewer's mind:
- What question will make them curious enough to click?
- Does this question align with the video content?
- Is the curiosity gap strong enough to drive action?
**Examples of good questions to prompt:**
- "What mistakes am I making?" → "Big Mistakes Small YouTube Creators Still Make!"
- "What happened?" → "I Should Have Seen This Coming..."
- "Why would someone do that?" → "the GRILLED CHEESE I ate every other day for 2 years"
- "Did they accept?" → "Offering People $100,000 To Quit Their Job"
### Step 4: Generate Title Options
Generate 3-5 title variations that:
1. Prompt the identified question
2. Complement (not duplicate) the thumbnail
3. Align with the target emotion
4. Follow content type best practices (educational vs entertainment)
**For each title, verify against the checklist:**
- [ ] **Curiosity Test**: Does this prompt a specific question?
- [ ] **Complementarity Test**: Does this work WITH the thumbnail (not duplicate it)?
- [ ] **Click Compulsion Test**: Is the curiosity gap strong enough?
- [ ] **Non-Descriptive Test**: Does this go beyond merely describing?
- [ ] **Target Audience Test**: Will this resonate with the demographic?
### Step 5: Present and Refine
Present the title options to the user with:
1. The title itself
2. The question it prompts in the viewer's mind
3. How it complements the thumbnail (if applicable)
4. Why it should drive clicks
Example presentation:
```
Here are 3 optimized title options:
1. "The AI Agent Mistake That Cost Me 10 Hours"
- Prompts: "What mistake? How can I avoid it?"
- Complements thumbnail showing frustrated face + error message
- Creates urgency through time cost
2. "I Built This AI Agent Wrong (Here's What I Learned)"
- Prompts: "What did they do wrong? What's the lesson?"
- Personal experience framing creates relatability
- Implies valuable learning without giving it away
3. "Why Your AI Agents Keep Breaking (And Mine Don't)"
- Prompts: "Why do mine break? What's their secret?"
- Creates contrast and curiosity
- Positions viewer problem + solution tease
```
### Step 6: Iterate Based on Feedback
If the user requests changes:
1. Understand what aspect needs adjustment (curiosity, tone, length, etc.)
2. Regenerate while maintaining design requirements compliance
3. Re-verify against the checklist
## Common Patterns by Content Type
### Educational Content (How-to, Tutorials)
**Goal**: Frame instruction to spark curiosity, not just inform
- ✅ "The Secret Technique Pro Chefs Don't Want You to Know"
- ✅ "I Tried the 'Impossible' Coding Challenge"
- ✅ "Why Everyone Does [X] Wrong (And How to Fix It)"
- ❌ "How to Chop Onions Properly"
- ❌ "Python Tutorial for Beginners"
### Entertainment Content (Vlogs, Gaming)
**Goal**: Create intrigue through outcome uncertainty
- ✅ "Offering People $100,000 To Quit Their Job"
- ✅ "I Ate the Same Meal for 30 Days Straight"
- ✅ "They Didn't Believe Me Until..."
- ❌ "My Daily Vlog"
- ❌ "Playing Minecraft"
### Tech/AI Content (User's Channel)
**Goal**: Combine education with curiosity and problem-solving
- ✅ "The AI Agent Pattern Nobody Talks About"
- ✅ "I Broke Production With This One Line of Code"
- ✅ "Why Your AI Agents Fail (And How to Fix Them)"
- ❌ "Building AI Agents Tutorial"
- ❌ "How to Use Claude API"
## Quality Assurance
### Priority Order (from Design Requirements)
1. **Spark curiosity** (highest priority)
2. **Complement thumbnail**
3. **Raise viewer question**
4. **Create click compulsion**
### Rejection Criteria
**REJECT and regenerate if the title:**
- Merely describes the content without sparking curiosity
- Duplicates text that appears on the thumbnail
- Answers the question instead of raising it
- Uses generic patterns like "[Topic] Tutorial" without intrigue
- Fails the "What question does this raise?" test
### Success Criteria
**A successful title:**
- Prompts a specific, compelling question in the viewer's mind
- Works synergistically with the thumbnail
- Creates a curiosity gap strong enough to drive clicks
- Aligns with the target audience and content type
- Passes all 5 checklist items in the design requirements
## Reference Documentation
For complete design requirements, patterns, and examples:
`references/design-requirements.md`
This reference includes:
- Detailed curiosity generation requirements
- Thumbnail complementarity specifications
- Forbidden patterns with examples
- Content type applications
- Complete title generation checklist
- High-performing vs low-performing pattern analysis
- Quality standards and implementation notes
## Additional Resources
### Related Skills
- `youtube-thumbnail`: For creating thumbnails that complement titles
- YouTube Analytics tools: For analyzing past title performance
## Notes
- **Curiosity is non-negotiable**: Description alone is insufficient
- **Always verify against checklist**: Every title must pass all 5 tests
- **Thumbnail coordination**: When possible, coordinate title with thumbnail design
- **Test multiple options**: Provide 3-5 variations for A/B testing consideration
- **Iterate ruthlessly**: Reject titles that don't meet standards, even if they're accurate

BIN
skills/youtube-title/_img/image.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 256 KiB

BIN
skills/youtube-title/_img/thumb2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 409 KiB

BIN
skills/youtube-title/_img/thumb3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 392 KiB

BIN
skills/youtube-title/_img/thumb4.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 416 KiB

BIN
skills/youtube-title/_img/thumb5.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 474 KiB

100
skills/youtube-title/references/design-requirements.md Normal file
View File

@@ -0,0 +1,100 @@
# YouTube Video Title Design Requirements Document
## Purpose
This document defines concrete requirements for generating optimized YouTube video titles that maximize click-through rates by sparking curiosity and complementing video thumbnails.
## Core Requirements
### 1. Curiosity Generation (MANDATORY)
**Requirement 1.1:** Every title MUST prompt a specific question in the viewer's mind.
- ✅ CORRECT: "Big Mistakes Small YouTube Creators Still Make!" (prompts: "What mistakes am I making?")
- ❌ INCORRECT: "Grow Your YouTube Channel" (no question prompted)
**Requirement 1.2:** Titles must spark curiosity through implication, not just description.
- ✅ CORRECT: "I Should Have Seen This Coming..." (implies: "What happened?")
- ❌ INCORRECT: "A Giant Root" (merely describes content)
**Requirement 1.3:** The curiosity gap must be strong enough to compel the viewer to click to find the answer.
### 2. Thumbnail Complementarity (MANDATORY)
**Requirement 2.1:** Title text MUST NOT duplicate thumbnail text.
- The title and thumbnail should work together as complementary elements
- Thumbnail text should enhance/support the title, not repeat it
**Requirement 2.2:** Title must align with the emotional tone or visual elements shown in the thumbnail.
- Example: If thumbnail shows frustration (like "Views 17"), title should acknowledge that pain point
- Example: If thumbnail shows a "Secret Weapon," title should reference the broader context
**Requirement 2.3:** Together, title + thumbnail must create a cohesive narrative that raises viewer curiosity.
### 3. Forbidden Patterns
**Requirement 3.1:** DO NOT create generic descriptive titles that merely state what the video is about.
- ❌ Avoid: "[Topic] Tutorial"
- ❌ Avoid: "How to [Action]" without curiosity element
- ❌ Avoid: Simple declarative statements with no intrigue
**Requirement 3.2:** DO NOT create titles that answer the question they should be raising.
- The title should make viewers want to know more, not tell them everything upfront
## Content Type Applications
### 4. Educational Content (How-to, DIY, Tutorials)
**Requirement 4.1:** Frame instructional content to spark curiosity, not just inform.
- ✅ CORRECT: "The Secret Technique Pro Chefs Don't Want You to Know"
- ❌ INCORRECT: "How to Chop Onions Properly"
**Requirement 4.2:** Imply value or revelation rather than stating process.
### 5. Entertainment Content (Vlogs, Gaming, Entertainment)
**Requirement 5.1:** Create intrigue through outcome uncertainty or unexpected situations.
- Example: "Offering People $100,000 To Quit Their Job" (Did they accept?)
**Requirement 5.2:** Use personal experience framing to create relatability and curiosity.
- Example: "the GRILLED CHEESE I ate every other day for 2 years" (Why would someone do that?)
## Title Generation Checklist
Before finalizing any title, verify:
- [ ] **Curiosity Test:** Does this title prompt a specific question in the target audience's mind?
- [ ] **Complementarity Test:** Does this title work WITH the thumbnail (not duplicate it)?
- [ ] **Click Compulsion Test:** Is the curiosity gap strong enough to drive a click?
- [ ] **Non-Descriptive Test:** Does this go beyond merely describing the content?
- [ ] **Target Audience Test:** Will this resonate with the specific viewer demographic?
## Quality Standards
**Requirement 6.1:** PRIORITY ORDER for title optimization:
1. Spark curiosity (highest priority)
2. Complement thumbnail
3. Raise viewer question
4. Create click compulsion
**Requirement 6.2:** If a title fails the Curiosity Test, it must be rejected and regenerated regardless of how accurately it describes the content.
**Requirement 6.3:** Accuracy is important, but ONLY after curiosity requirements are met. A perfectly accurate but non-curious title is a failed title.
## Examples Reference
### HIGH-PERFORMING PATTERNS:
- Mistake/Problem framing: "Big Mistakes Small YouTube Creators Still Make!"
- Question implication: "I Should Have Seen This Coming..."
- Extreme behavior: "the GRILLED CHEESE I ate every other day for 2 years"
- High-stakes scenarios: "Offering People $100,000 To Quit Their Job"
- Novel perspective: "The First Guy To Ever Go To Prison"
### LOW-PERFORMING PATTERNS TO AVOID:
- Generic promises: "Grow Your YouTube Channel"
- Simple descriptions: "A Giant Root"
- Straightforward how-tos without intrigue: "How to Make Grilled Cheese"
## Implementation Notes
When generating titles:
1. Start by identifying what question you want in the viewer's mind
2. Craft the title to prompt that specific question
3. Ensure the title complements (not duplicates) thumbnail elements
4. Verify the curiosity gap is compelling enough to drive action
5. Reject any title that merely describes without intriguing
**CRITICAL:** Curiosity is non-negotiable. Description alone is insufficient. Every title must pass the "What question does this raise?" test.

290
skills/youtube-video-hook/SKILL.md Normal file
View File

@@ -0,0 +1,290 @@
---
name: youtube-video-hook
description: Skill for creating optimized YouTube video opening hooks (first 5-30 seconds) that maximize viewer retention and watch time. Use when planning video scripts, reviewing video openings, or optimizing existing content for better retention metrics.
---
# YouTube Video Hook
## Overview
This skill provides concrete requirements and proven patterns for creating video opening hooks that retain viewer attention, extend title/thumbnail curiosity, and maximize watch time. The opening 5-15 seconds are critical for YouTube algorithm performance and viewer retention.
## When to Use This Skill
Use this skill when:
- Planning a new YouTube video script and need to design the opening hook
- Reviewing an existing video opening for retention optimization
- The user asks for help with video retention, watch time, or early drop-off issues
- Creating content strategy that requires understanding of viewer psychology
- Analyzing why a video has poor retention in the first 30 seconds
## Core Principle
**The opening seconds must EXTEND the curiosity created by the title and thumbnail, not repeat or waste it.**
The viewer already clicked based on the title/thumbnail promise. The opening must ADD new intrigue and make them MORE interested, not simply restate what they already know.
## Critical Requirements
### 1. Curiosity Extension (CRITICAL)
Opening seconds MUST build upon the intrigue from the title/thumbnail, never repeat it.
**✅ CORRECT Example:**
- Title: "Teach Your Cat 5 Tricks in 10 Minutes"
- Opening: Rapid preview montage of impressive tricks in action
- Viewer thinks: "Woah, I can teach my cat ALL of that in only 10 minutes?!"
**❌ INCORRECT Example:**
- Title: "Teach Your Cat 5 Tricks in 10 Minutes"
- Opening: "Today we're going to look at 5 tricks you can teach your cat in 10 minutes"
- Viewer thinks: "I know. Get on with it."
The opening must make the viewer MORE interested than when they clicked. Viewer attention must INCREASE, not drain.
### 2. Direct Content Connection (MANDATORY)
Opening seconds MUST directly relate to the title and thumbnail content.
**Rules:**
- NO unrelated tangents or side stories in the opening
- NO delayed starts where main content appears 1-2 minutes later
- Visual or verbal content must be tightly connected to the promised value
- If additional context is needed, it must come AFTER the hook is established
**✅ CORRECT:** "Secret Fruit Trick" video → Opens immediately showing or teasing the trick
**❌ INCORRECT:** "Secret Fruit Trick" video → Opens with "Hi everyone, I'm June, thanks for watching! I absolutely adore fruit so much! I usually eat like 10 pieces a day! I got this habit from my grandmother who..."
### 3. Forbidden Opening Patterns
These patterns are DISQUALIFYING violations that cause immediate failure:
#### 3.1 DO NOT Repeat the Title (FORBIDDEN)
Never verbally restate what the title already communicated.
**Examples of FORBIDDEN openings:**
- Title: "Python Tutorial for Beginners" → Opening: "Hello! In this video I am going to give you a tutorial of Python for beginners!"
- Title: "5 Photography Mistakes" → Opening: "Today I'm going to show you 5 photography mistakes"
**Why:** The viewer already has this information. Repetition drains attention.
#### 3.2 DO NOT Welcome the Viewer First (FORBIDDEN)
Never start with greetings, channel welcomes, or introductions before the hook.
**Examples of FORBIDDEN openings:**
- "Hi guys, welcome to my video, I'm Joe! It's so good to see you again..."
- "Hello everyone and welcome back to the channel..."
- "Hey what's up, thanks so much for clicking on this video..."
**Why:** This is friendly but not engaging for first-time viewers and doesn't build upon title/thumbnail momentum.
**Exception:** Welcomes and introductions are acceptable AFTER the initial hook is established (after first 15 seconds).
#### 3.3 DO NOT Start with Unrelated Content (FORBIDDEN)
Never open with tangents, stories, or content disconnected from the title/thumbnail promise.
**Examples of FORBIDDEN openings:**
- Title: "Cat Tricks Tutorial" → Opening: Walking down sidewalk talking about a new car for 1-2 minutes
- Title: "Secret Fruit Trick" → Opening: Extended story about grandmother's fruit-eating habits
**Why:** Viewer confusion triggers abandonment. YouTube interprets this as low-quality content.
## Effective Opening Hook Patterns
Use one of these proven hook structures:
### Pattern A: Preview/Teaser
Show a brief glimpse of the payoff.
**Example:** Quick montage of the 5 cat tricks in action (visual proof of value)
**Creates thought:** "I need to know how to do that!"
### Pattern B: Intrigue Escalation
Add surprising context that makes the promise MORE compelling.
**Example:** Title about a trick → Open with "What I'm about to show you took professionals years to discover, but you'll learn it in 60 seconds"
**Creates thought:** "This is even better than I expected!"
### Pattern C: Problem Amplification
Immediately validate why the viewer needs this content.
**Example:** Title about mistakes → Open with "If you're doing [X], you're losing [specific bad outcome]"
**Creates thought:** "I need to fix this now!"
### Pattern D: Immediate Value Demonstration
Jump straight into delivering on the promise. No preamble, just results.
**Creates thought:** "This is exactly what I came for!"
## Hook Timing Requirements
**Critical timing rules:**
1. **Hook must occur within 5-15 seconds**
- Absolute maximum: 15 seconds before delivering hook
- Optimal: 3-8 seconds
2. **After hook is established (within first 15 seconds), THEN:**
- Brief introduction is acceptable (5-10 seconds max)
- Transition to main content
- Any necessary context or background
3. **Main promised content must begin within 30 seconds of video start**
## Content Type Applications
### Educational Content (Tutorials, How-To, DIY)
**Open with result preview or value proof:**
- Show quick clips of the end result
- Demonstrate the transformation/skill
- Validate that the tutorial delivers real value
**DO NOT open with explanations:**
- ❌ FORBIDDEN: "In this tutorial I'm going to teach you..."
- ✅ REQUIRED: Jump into a preview or start teaching immediately
### Entertainment Content (Vlogs, Gaming, Challenges)
**Open with the most exciting/surprising moment:**
- Lead with drama, excitement, or unexpected elements
- Create immediate emotional engagement
- Start in the middle of the action
**DO NOT open with setup or context:**
- Context can come after the hook
### List/Compilation Videos
**Tease the most interesting items without revealing details:**
- Show glimpses that create curiosity
- DO NOT list the items by name in order
- Create urgency: "Wait until you see number 3..." or "The last one will shock you..."
## Quality Verification Checklist
Before finalizing any opening hook, verify ALL of these:
- [ ] **Non-Repetition Test:** Does this opening repeat the title? (Must be NO)
- [ ] **Curiosity Extension Test:** Does this make viewers MORE curious than the title/thumbnail alone?
- [ ] **Direct Connection Test:** Is this immediately related to what the title/thumbnail promised?
- [ ] **No Welcome First Test:** Does this avoid welcoming viewers before the hook? (Must be YES)
- [ ] **Attention Increase Test:** Will this INCREASE viewer attention meter, not drain it?
- [ ] **Click Validation Test:** Does this confirm to the viewer they made the right choice clicking?
- [ ] **Hook Timing Test:** Does the hook occur within 5-15 seconds?
## Common Failure Patterns
### Pattern 1: The Friendly But Boring Welcome
```
❌ "Hi guys, welcome to my video, I'm Sarah!
Thanks so much for being here today..."
```
**Problem:** Drains attention before value is delivered.
### Pattern 2: The Exact Repetition
```
❌ Title: "5 iPhone Hidden Features"
Opening: "Today I'm showing you 5 hidden iPhone features"
```
**Problem:** Viewer already knows this. No new information.
### Pattern 3: The Meandering Start
```
❌ Title: "Amazing Cooking Hack"
Opening: "So I was at the store yesterday and I saw
this interesting ingredient and it reminded me of..."
```
**Problem:** Takes too long to get to the promised content.
### Pattern 4: The Over-Explanation
```
❌ "Before we get started, let me explain why this is
important and give you some background on..."
```
**Problem:** Delays the payoff. Viewer loses patience.
## Success Patterns
### Pattern 1: Immediate Value
```
✅ Title: "Amazing Cooking Hack"
Opening: [Shows the hack in action immediately]
"Watch this..." [demonstrates stunning result in 3 seconds]
```
### Pattern 2: Curiosity Escalation
```
✅ Title: "iPhone Hidden Feature"
Opening: "Your iPhone has been hiding this from you..."
[Shows something unexpected happening on screen]
```
### Pattern 3: Preview Montage
```
✅ Title: "5 Photoshop Tricks"
Opening: [3-second rapid montage of all 5 tricks' results]
"You're about to learn all of these..."
```
## Implementation Workflow
When creating or reviewing opening hooks, follow this workflow:
1. **Review title and thumbnail** - Understand what curiosity was created
2. **Identify the escalation** - How can the opening make it MORE intriguing?
3. **Choose hook pattern** - Which structure (A/B/C/D) best serves the content?
4. **Write/plan opening** - Create the first 15 seconds of content
5. **Apply verification checklist** - Ensure all 7 requirements are met
6. **Time check** - Confirm hook occurs within 5-15 seconds
7. **Test against forbidden patterns** - Ensure none of the 3 forbidden patterns are present
## YouTube Algorithm Implications
Understanding the algorithmic impact of opening seconds:
**Opening seconds directly impact:**
- Early abandonment rate (negative signal to YouTube)
- Average view duration (positive signal to YouTube)
- Video surface probability in recommendations
**Optimization for watch time:**
- Longer viewer retention = more watch time
- More watch time = YouTube values video higher
- Higher value = more visibility and recommendations
**Patterns that cause quick abandonment:**
- Confusion (unrelated opening)
- Boredom (repetitive opening)
- Disappointment (mismatched expectations)
## Critical Success Factors
**Priority Order (highest to lowest):**
1. DO NOT repeat the title (instant failure if violated)
2. Extend curiosity beyond title/thumbnail
3. Connect directly to promised content
4. DO NOT welcome viewers first
5. Deliver hook within 5-15 seconds
**CRITICAL:** If opening seconds repeat the title, welcome viewers first, or start with unrelated content, the hook has FAILED regardless of other qualities. These are disqualifying violations that must be corrected.
## Key Reminders
- Title/thumbnail got the click → Opening must JUSTIFY and EXTEND that decision
- Viewer attention meter must INCREASE, never decrease
- Every second in the opening counts toward retention or abandonment
- YouTube is watching viewer behavior in opening seconds closely
- Quick abandonment signals = video suppression
- Strong retention = video promotion