Skip to content

sergebulaev/youtube-skills / .codex-marketplace/youtube-skills

youtube-marketing

Verified

Plan, write, and publish for YouTube and YouTube Shorts. Use when the user wants high-CTR video titles, an SEO description with chapters and links, a first-30-seconds retention script (or a 3-second Shorts hook), a designer-ready thumbnail brief, a community-tab post or poll, or a weekly upload plan. The user supplies the video; the skills produce the title, description, hook, and thumbnail brief, then on approval upload and schedule via the Publora API.

<p align="center">
  <img src="assets/hero.png" alt="YouTube marketing skills for Claude Code and Codex, open source MIT licensed" width="900" />
</p>

# YouTube Marketing Skills for Claude Code and Codex

<p align="center">
  <img src="https://img.shields.io/github/v/release/sergebulaev/youtube-skills?color=111827&label=release" alt="Latest release">
  <img src="https://img.shields.io/badge/Claude_Code-Compatible-D97757?logo=anthropic&logoColor=white" alt="Claude Code Compatible">
  <img src="https://img.shields.io/badge/Codex-Compatible-111827" alt="Codex Compatible">
  <img src="https://img.shields.io/badge/Claude-Skills-8A63D2" alt="Claude Skills">
  <img src="https://img.shields.io/badge/License-MIT-22C55E.svg" alt="MIT License">
  <img src="https://img.shields.io/github/stars/sergebulaev/youtube-skills?style=social" alt="GitHub stars">
  <img src="https://img.shields.io/badge/PRs-welcome-F59E0B.svg" alt="PRs Welcome">
</p>

> **Part of the [linkedin-skills](https://github.com/sergebulaev/linkedin-skills) family (400+ stars).** Same voice engine and approve-before-publish flow, now for YouTube. Also available for [Instagram](https://github.com/sergebulaev/instagram-skills) · [X](https://github.com/sergebulaev/x-skills) · [TikTok](https://github.com/sergebulaev/tiktok-skills) · [Threads](https://github.com/sergebulaev/threads-skills) · [Facebook](https://github.com/sergebulaev/facebook-skills).

**9 skills that turn Claude Code and Codex into your YouTube packaging team.** They write high-CTR titles and SEO descriptions, script retention hooks for long-form and Shorts, brief thumbnails, draft community posts, and audit your channel page. You supply the video; the skills write the packaging, strip the AI tells, and wait for your approval.

Once installed, just ask Claude Code or Codex things like:

- "Write 5 high-CTR titles for a video about [topic]"
- "Script the first 30 seconds to keep viewers watching"
- "Answer this comment as a community post"
- "What's working in my niche on YouTube? (reads real data)"

The right skill activates automatically. Then you review and approve.

## Install

Pick whichever way you use Claude Code or Codex:

### Codex CLI

```bash
codex plugin marketplace add sergebulaev/youtube-skills
codex plugin add youtube-skills@youtube-skills
```

To test a local clone before publishing changes:

```bash
git clone https://github.com/sergebulaev/youtube-skills.git
cd youtube-skills
codex plugin marketplace add .
codex plugin add youtube-skills@youtube-skills
```

### claude.ai (web)

1. Open https://claude.ai/code
2. Go to **Skills** in the sidebar
3. Click **Add from GitHub**
4. Paste: `sergebulaev/youtube-skills`
5. Done. The skills activate automatically when you ask about YouTube or Shorts.

### Claude Desktop (Mac / Windows)

1. Open Claude Desktop
2. Open **Settings** (gear icon)
3. Go to **Skills**
4. Click **Add from GitHub**
5. Paste: `sergebulaev/youtube-skills`
6. Done. Start a new conversation and ask Claude to title your next video.

### Claude Code (CLI / VS Code / JetBrains)

```
/plugin marketplace add sergebulaev/youtube-skills
/plugin install youtube-skills@youtube-skills
```

Or clone the repo and open it as your working directory:

```bash
git clone https://github.com/sergebulaev/youtube-skills.git
cd youtube-skills
```

### OpenClaw

1. Open your OpenClaw working directory
2. Clone the skills into it:
   ```bash
   git clone https://github.com/sergebulaev/youtube-skills.git
   ```
3. In OpenClaw settings, add this to your system prompt:
   ```
   You have YouTube marketing skills in ./youtube-skills/.
   For any YouTube task, read the relevant skills/*/SKILL.md first.
   Use lib/url_parser.py for URL parsing and lib/publora_client.py for publishing.
   ```
4. Done. Ask OpenClaw to write a YouTube post.

### Hermes Agent

Hermes Agent (Nous Research) follows the agentskills.io open standard and loads `skills/*/SKILL.md` directly. Clone the bundle into your Hermes skills folder:

```bash
git clone https://github.com/sergebulaev/youtube-skills.git ~/.hermes/skills/youtube-skills
```

Coming from OpenClaw? `hermes claw migrate` imports these skills automatically. Then call `/<skill-name>` from any of your Hermes chat surfaces.

### Any agent (skills CLI)

One command that works across Claude Code, Codex, Cursor, and any other agent that reads SKILL.md files:

```bash
npx skills add sergebulaev/youtube-skills
```

> **Found this useful? [Star the repo](https://github.com/sergebulaev/youtube-skills).** Curated Claude Code and Codex directories rank and gate by star count, so a star is what makes these skills findable for the next person. It is the only thing we ask. No signup, no email.

## What you can do

Once installed, just ask Claude Code or Codex for help with YouTube. The right skill activates automatically.

**Title a video:**
> "Give me 5 high-CTR titles for a video on cutting my render time in half."

**Write the description:**
> "Write the description with chapters and keywords for this video: [paste the outline]"

**Script the opening:**
> "Script the first 30 seconds so people don't click away. The title is 'How I shipped in 5 days'."

**Hook a Short:**
> "Write the first 3 seconds for a Short about one editing setting that doubles views."

**Brief a thumbnail:**
> "Give me 3 thumbnail concepts a designer can build for this video."

**Plan your week:**
> "Plan a week of YouTube content. I'm building an AI app in public and can do 1 long-form plus 3 Shorts."

Every skill shows you a draft first and waits for your OK. Nothing gets published without your approval.

## The 9 skills

| Skill | What it does |
|---|---|
| **Title Optimizer** | Writes high-CTR titles under 100 chars using 2026 formulas (curiosity, number, how-I, mistake, transformation, versus, success-story). Front-loads the words that decide the click and returns 3 to 5 A/B variants tagged by goal |
| **Description Writer** | Writes the full description under 5,000 chars: a first-150-char hook (the only part visible before "Show more"), timestamped chapters, natural keywords, links, and a real CTA |
| **Hook Scripter** | Scripts the spoken opening that decides retention: the first 30 seconds of a long-form video, or the first 3 seconds of a Short, with no intro and a designed loop |
| **Thumbnail Brief** | Turns a video into a designer-ready brief (focal subject, face/emotion, 4-word text overlay, contrast, composition) plus 2 to 3 A/B concepts and the upload flow |
| **Community Post Writer** | Writes community-tab text posts, polls, and questions that keep the channel warm between uploads. Returns a copy-paste block (community posts have no API) |
| **Content Planner** | Builds a weekly plan: long-form vs Shorts mix, cadence, per-slot title and thumbnail pairing, hook angle, community posts, and a CTR / retention / subscribe goal balance |
| **Repurposer** | Adapts off-platform content (a blog post, X thread, LinkedIn post, or newsletter) into a native YouTube surface: a community-tab post or poll, or a video brief (title, spoken hook, description with chapters). Leads with the payoff and strips off-platform artifacts |
| **Channel Optimizer** | Audits and rewrites the channel page end-to-end: name and @handle, banner (2560x1440 with the 1235x338 safe area), profile picture, About with keywords, the trailer for non-subscribers vs the featured video for subscribers, playlist sections and section order, watermark, and links. Turns a viewer into a subscriber with a scorecard and before/after |
| **Audience Insights** | Reads your audience from the comments via the free YouTube Data API: commenters, top comments, recurring questions (content ideas), superfans, and what is trending in your niche. YouTube keeps likers private, so this reads commenters |

## How publishing works on YouTube

YouTube is a **video-only platform**: every published post needs a single video, which you supply. The skills write the title, description, hook script, and thumbnail brief; you bring the .mp4. Uploading to YouTube on the native Data API means a Google OAuth flow, the resumable-upload protocol, and quota tracking.

This bundle hands that chain to [Publora](https://publora.com/?utm_source=github&utm_medium=readme&utm_campaign=youtube-skills). On approval, it creates a draft, uploads your video to S3, sets the title and metadata, and schedules the post, all over a few REST calls. A custom thumbnail can be attached too, but the thumbnail image upload is out of band (Publora dashboard or a dedicated endpoint); the bundle automates the attach step, not the image upload. The writer skills use this on approval.

## Optional: auto-upload with Publora

By default, the skills draft everything for you to paste into YouTube Studio. If you want Claude Code or Codex to upload and schedule the video you supply, connect Publora. It takes about 2 minutes.

### What is Publora?

[Publora](https://publora.com/?utm_source=github&utm_medium=readme&utm_campaign=youtube-skills) is a publishing API that turns one flow (`create-post`, `get-upload-url`, `update-post`) into a scheduled YouTube upload, and can cross-post the same content to other platforms.

Publora also ships [official MCP skills](https://github.com/publora/skills) (`npx skills add publora/skills`): one skill per platform, covering the publish side only. This bundle is the layer above them, adding the reading, the writing craft and the approval flow.

### Setup (2 minutes)

**Step 1.** Sign up at https://app.publora.com/signup?utm_source=github&utm_medium=readme&utm_campaign=youtube-skills (free)

**Step 2.** Connect YouTube: click **Channels** in the left sidebar, then **Add Channel**, pick **YouTube**, authorize with Google.

**Step 3.** Find your Platform ID: go to **Channels**, click your YouTube channel. The ID looks like `youtube-UCxxxxxxxxxxxxxxxxxxxxxx`. Copy the whole thing including `youtube-`.

**Step 4.** Get your API key: click **Settings** (gear icon, bottom-left), then **API**, then **Create Key**. Copy the `sk_...` string.

**Step 5.** Create a file called `.env` in the youtube-skills folder:

```
PUBLORA_API_KEY=sk_paste_your_key_here
YOUTUBE_PLATFORM_ID=youtube-paste_your_channel_id_here
```

If you cloned the repo, copy the template instead:

```bash
cp .env.example .env
```

Then open `.env` and replace the placeholders with your real values.

**Step 6.** Install two small Python packages:

```bash
pip install requests python-dotenv
```

**Step 7.** Test it. Ask Claude Code or Codex:

> "Schedule a test video as unlisted via Publora 24 hours from now using [path to a short .mp4], title 'API connection test'."

If Publora returns a `postGroupId`, you're set. Cancel the post in the Publora dashboard before the scheduled time. If you get HTTP 401, your API key is wrong. If you get `Invalid platform ID format`, your `YOUTUBE_PLATFORM_ID` is wrong. See [Troubleshooting](#troubleshooting).

> **Note on community posts:** YouTube community-tab posts and polls have no publishing API, so the Community Post Writer always returns its draft as a copy-paste block for you to post yourself. Videos and Shorts auto-upload.

## Optional: generate illustrations with Pixfaro

The thumbnail drives click-through more than anything else. The Community Post Writer can generate a 16:9 image with bold overlay text, but the community tab has no media API, so you upload the approved image yourself with the post. Without a key it drafts the image prompt and asks you to generate it yourself, so nothing breaks.

[Pixfaro](https://pixfaro.com) is a single image API over multiple models (from `flux-schnell` at $0.004 to `gpt-5-image`). It composites your handle, brand color, or logo onto the image as a **pixel-exact overlay**, so a cheap base model still renders crisp text on a thumbnail. Pull those brand fields from your [Voice & Brand Profile](references/voice-profile.md) (section 6) and every asset stays on-brand.

Setup: drop `PIXFARO_TOKEN=pf_live_...` into your `.env`. The thin client at `lib/pixfaro_client.py` and the wrappers `lib.illustrate(prompt, kind="thumbnail")` / `lib.refine(image_id, instruction)` return a hosted URL that flows straight into `lib.publish(..., media_urls=[url])`. `refine` edits a prior image by its id (cheaper than regenerating); results carry `cost`, `balance_after`, and a `premium` flag so the skills never quietly spend on a pricey model.

## Optional: read real YouTube data

`yt-audience-insights` reads comments, video and channel stats and the trending list through the **YouTube Data API v3**, Google's own, not Apify. Without a key it asks you to paste the numbers, so nothing breaks.

Setup, with a shell:

```
YOUTUBE_API_KEY=AIza_your_key_here
```

The key is free and needs no billing: create a project, enable "YouTube Data API v3", create an API key. [Console](https://console.cloud.google.com/apis/library/youtube.googleapis.com) · [Credentials](https://console.cloud.google.com/apis/credentials).

**On claude.ai there is no read path for this bundle**, and that is worth saying plainly rather than leaving you to discover it. The sibling bundles read through Apify, which now publishes an MCP server you can add as a connector; this one reads through Google, which publishes no such thing. A skill on claude.ai has no environment to hold `YOUTUBE_API_KEY` and no process to call the API with, so the reading skills there ask you to paste titles, stats or comments. The draft quality is the same; it costs you a copy-paste.

If that matters to you, the honest options are to run this bundle in Claude Code with a `.env`, or to open an issue asking for an Apify YouTube actor to be wired in as a second read path.
## Voice rules

Every skill follows these rules automatically:

1. Em dashes capped at about one per 100 words (at most one in a title). The character stopped being a tell in 2026; the density is.
2. Capitalize names. Always. Lowercase a brand reads as careless.
3. No AI vocabulary clusters. One 2026 marker ("leverage", "significant", "streamline", "foster") in a paragraph is English; three in one paragraph reads as AI and gets the paragraph rewritten. In a one-line title any marker goes.
4. Specific numbers beat adjectives. "in 28 days" beats "fast".
5. The title is a promise, not a summary. Curiosity plus a concrete payoff.
6. Title and thumbnail are a pair. They never repeat the same words.
7. The first 30 seconds (or 3 on a Short) is the real algorithm. No intro.
8. Title caps at 100 chars (sweet spot 40 to 60). Description caps at 5,000, first 150 visible.

## Troubleshooting

| Problem | Fix |
|---|---|
| Skills don't activate when I ask about YouTube | Make sure you installed via the Skills panel, `/plugin install`, or `codex plugin add`. Try a new conversation. |
| "PUBLORA_API_KEY not set" | Your `.env` file is missing or in the wrong folder. It should be in the `youtube-skills/` root. |
| "401 Invalid API key" from Publora | Your API key is wrong or revoked. Go to Publora Settings > API > Create a new key. |
| "Invalid platform ID format" | Your `YOUTUBE_PLATFORM_ID` is wrong. Go to Publora Channels and copy the full `youtube-...` string. |
| My video failed with VIDEO_REQUIRED | YouTube needs a video on every post. Point the skill at your local .mp4; a text-only YouTube post cannot publish. |
| My custom thumbnail didn't apply | The channel must be verified, and the image must be JPEG/PNG under 2 MB. Applying is best-effort: the video still publishes without it. |
| My upload is over 512 MB | Publora caps uploads at 512 MB. Compress the video, or upload the large file via YouTube Studio. |
| `pip install` fails | Use a virtual environment: `python -m venv venv && source venv/bin/activate && pip install requests python-dotenv` |

## Cross-cutting references

- [`references/hook-formulas.md`](references/hook-formulas.md) - the 11 YouTube title and hook formulas with skeletons and goal tags
- [`references/algorithm-heuristics.md`](references/algorithm-heuristics.md) - 2026 YouTube ranking (CTR x retention), timing, and limits
- [`references/thumbnail-principles.md`](references/thumbnail-principles.md) - the thumbnail design language and the upload flow
- [`references/voice-rules.md`](references/voice-rules.md) - the canonical voice rules every skill inherits

---

<details>
<summary><b>For developers: runtime compatibility, URL parsing, and internals</b></summary>

## Runtime compatibility

```
youtube-skills/
  skills/             SKILL.md frontmatter; native to Claude Code and Codex, others read as markdown
  .codex-marketplace/ generated nested Codex package (run scripts/sync_codex_marketplace.py)
  lib/                pure Python, works in any agent runtime
  references/         pure markdown, works anywhere
  scripts/            pure Python CLI, works anywhere
```

| Runtime | Auto-discovers skills? | Setup |
|---|---|---|
| **Claude Code** (CLI, Desktop, Web, IDE) | Yes | Install via plugin or clone. Skills activate on matching prompts. |
| **Codex CLI** | Yes | `codex plugin marketplace add sergebulaev/youtube-skills` and `codex plugin add youtube-skills@youtube-skills`. |
| **Anthropic Managed Agents** (`/v1/agents`) | Yes | Pass skill files in the agent context. |
| **Cursor / Cline / Aider** | Manual | Read `SKILL.md` files as prompt context; import `lib/` as Python. |
| **LangChain / AutoGen** | No | Use `lib/` as a package; feed `references/` as prompt context. |

## Generic Python agent quickstart

```python
import sys; sys.path.insert(0, "path/to/youtube-skills")
from lib import parse_youtube_url, PubloraClient, publish

parsed = parse_youtube_url("https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=10s")
print(parsed["video_id"], parsed["url_type"])  # dQw4w9WgXcQ video

# Write side (Publora) - the full media-required YouTube flow in one call
client = PubloraClient()  # reads PUBLORA_API_KEY from env
client.publish_video(
    content="Full description here.. first 150 chars are the hook.",
    platforms=["youtube-UCxxxxxxxxxxxxxxxxxxxxxx"],
    video_path="./episode-12.mp4",
    title="How I shipped in 5 days",
    privacy="public",
    scheduled_time="2026-07-01T16:00:00.000Z",
)

# Or the high-level wrapper that handles manual / Publora / diy routing
publish("video", draft_text="<description>", target_url="https://studio.youtube.com",
        video_path="./episode-12.mp4", title="How I shipped in 5 days",
        platforms=["youtube-UCxxxxxxxxxxxxxxxxxxxxxx"])
```

## URL handling

`lib/url_parser.py` parses YouTube video, Short, and channel URLs:

| URL fragment | Parsed |
|---|---|
| `youtube.com/watch?v=ID` | `{video_id, url_type: "video"}` |
| `youtu.be/ID` | `{video_id, url_type: "video"}` |
| `youtube.com/shorts/ID` | `{video_id, is_short: true, url_type: "short"}` |
| `youtube.com/@handle` | `{handle, url_type: "channel"}` |
| `youtube.com/channel/UC...` | `{channel_id, url_type: "channel"}` |

```bash
python lib/url_parser.py "https://www.youtube.com/shorts/abc123XYZ_-"
```

## The media-required upload flow

YouTube requires a video on every post, so a text-only post fails at publish with `VIDEO_REQUIRED`. The client runs the documented order:

1. `create-post` with no `scheduledTime` -> a draft, returns `postGroupId`
2. `get-upload-url` -> a pre-signed S3 URL
3. PUT the video to S3
4. `update-post/:postGroupId` -> set `scheduledTime` and any youtube settings

A custom thumbnail is *attached* in step 4 (it needs the `postGroupId`), never on `create-post`. `PubloraClient.publish_video()` runs all four steps; `set_thumbnail()` wraps the update-post attach call. Note the thumbnail *image upload* is out of band: Publora requires a tracked media asset from its dedicated YouTube thumbnail endpoint, which is not wired into this bundle. Upload the image in the Publora dashboard (or the dedicated endpoint once available) to get the `{mediaId, url}`, then attach. Without it, ship the video and set the thumbnail in YouTube Studio.

## Why community posts are copy-paste

YouTube community-tab posts and polls have no Publora endpoint and no public publishing API. `yt-community-post-writer` therefore drafts the post and returns it as a copy-paste block via `lib/backend_selector.py`. Videos and Shorts auto-upload normally.

</details>

## References

- [Publora API docs](https://docs.publora.com/?utm_source=github&utm_medium=readme&utm_campaign=youtube-skills) - endpoint reference for the publishing layer
- [YouTube Creator Insider](https://www.youtube.com/@CreatorInsider) - YouTube's own signals on ranking and packaging

## Who builds this

These skills come out of [Creative Content Crafts](https://cccrafts.ai), an engineering company. We build the machinery underneath a company's public voice: ICP parsing, engagement systems, content guardrails, and posting infrastructure. We do not sell the words themselves.

We call that layer **content engineering**. Writing collapsed to the price of a chat subscription. What stayed valuable is everything below it: pulling every post your market wrote this week, keeping a live list of the people who matter, engaging on it daily with judgment in the loop, and catching the risky drafts before the platform does.

This repo is the thin top layer of that stack, open-sourced. The engine underneath is what we build for clients.

## License

MIT. Powered by [Publora](https://publora.com/?utm_source=github&utm_medium=readme&utm_campaign=youtube-skills).

## Related open-source skill bundles

Part of a family of AI social-media marketing skill bundles for Claude Code and Codex:

- [linkedin-skills](https://github.com/sergebulaev/linkedin-skills) - LinkedIn
- [x-skills](https://github.com/sergebulaev/x-skills) - X (Twitter)
- [instagram-skills](https://github.com/sergebulaev/instagram-skills) - Instagram
- **youtube-skills - YouTube (this repo)**
- [threads-skills](https://github.com/sergebulaev/threads-skills) - Threads
- [tiktok-skills](https://github.com/sergebulaev/tiktok-skills) - TikTok
- [facebook-skills](https://github.com/sergebulaev/facebook-skills) - Facebook Pages

Also: [Anthropic Skills repo](https://github.com/anthropics/skills), the `awesome-claude-skills` directory.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall