How to Generate a SKILL.md From a YouTube Channel

Paste a channel handle into the Prepublish channel skill generator. It analyses the 12 most recent long-form uploads, requires at least four usable original-language transcripts, and writes a four-file Agent Skill bundle in about six minutes. Measured runs on 18 and 19 September 2026 took 6 minutes 30 seconds, 5 minutes 35 seconds, and 6 minutes 5 seconds.

The generator accepts a bare @handle, a channel URL, or a link to any video on the channel. It resolves the channel with yt-dlp and reads public data only: the 60 newest entries in the videos tab, then titles, descriptions, tags, chapters, view counts, and durations for the long-form videos among them. There is no YouTube Data API call anywhere in the tool and no Google account is involved (ops/specs/channel-skill-generator.md, 18 September 2026).

Three numbers bound the read. Uploads under 180 seconds are discarded before the list is used, at most 12 videos are analysed, and the transcript stage stops once it has accumulated 60,000 characters (channel_skill_service.go, channelSkillLongformSeconds, channelSkillMaxVideos, channelSkillTranscriptsTotal). Each transcript is capped at 8,000 characters, of which the first 1,200 characters are kept as an opening and the next 6,000 as a body.

One Gemini Flash call writes the brief. A pure renderer then produces the files, with no model call and no wall clock, so the same stored result always renders the same bytes (channel_skill_render.go, RenderChannelSkillFiles).

Source: marketing/content-drafts/EVIDENCE.md, section 6.

Metadata dominates that time rather than writing. Twelve detail pulls at roughly 13 seconds each account for about 2 minutes 36 seconds of the first run, and every transcript then costs a metadata probe plus a caption download (ops/specs/channel-skill-generator.md, 18 September 2026). A channel with fewer eligible uploads finishes sooner.

The renderer emits one brief file and up to three evidence files. SKILL.md is always present; a reference file appears only when it has evidence to carry:

// RenderChannelSkillFiles renders the downloadable bundle from the stored
// model output and the input snapshot. It is pure and deterministic: no model
// call, no wall clock, no map iteration, so the same entity always renders the
// same bytes. SKILL.md is always present; a reference file is emitted only when
// it has evidence to carry.
files := []ChannelSkillFile{{Path: "SKILL.md", Content: renderSkillMD(s)}}
// three conditional appends follow, in this order (conditions elided):
"references/hooks.md"
"references/titles.md"
"references/transcript-excerpts.md"

The SKILL.md body is fixed in order. These are the heading lines as renderSkillBody writes them, with each section's own render call elided:

func renderSkillBody(s *ChannelSkill, limits skillRenderLimits) []string {
	var lines []string

	if section := renderIdentity(s, limits); len(section) > 0 {
		lines = append(lines, "## Identity and niche", "")
		// ...section... elided
	}
	if section := renderAudience(s, limits); len(section) > 0 {
		lines = append(lines, "## Audience", "")
	}
	if section := renderVoice(s, limits); len(section) > 0 {
		lines = append(lines, "## Voice and diction rules", "")
	}
	if section := renderHooks(s, limits); len(section) > 0 {
		lines = append(lines, "## Hook patterns", "")
	}
	if section := renderStructure(s, limits); len(section) > 0 {
		lines = append(lines, "## Structure and pacing template", "")
	}
	if section := renderTitleConventions(s, limits); len(section) > 0 {
		lines = append(lines, "## Title conventions", "")
	}
	if section := renderThumbnails(s, limits); len(section) > 0 {
		lines = append(lines, "## Thumbnail conventions", "")
	}
	if section := renderRecurring(s, limits); len(section) > 0 {
		lines = append(lines, "## Recurring segments and catchphrases", "")
	}
	if section := renderTopics(s, limits); len(section) > 0 {
		lines = append(lines, "## Topics covered and gaps", "")
	}
	if section := renderCTAs(s, limits); len(section) > 0 {
		lines = append(lines, "## CTA patterns", "")
	}
	if section := renderBannedMoves(s, limits); len(section) > 0 {
		lines = append(lines, "## Banned moves", "")
	}
	if section := renderChecklist(s, limits); len(section) > 0 {
		lines = append(lines, "## Draft checklist", "")
		// (each section's content appends elided for length)
	}

	for len(lines) > 0 && lines[len(lines)-1] == "" {
		lines = lines[:len(lines)-1]
	}
	return lines
}

renderProvenance then appends a closing ## Provenance block that is always present and never empty.

The three reference files carry the depth that does not fit in the brief:

Two ceilings shape all of this. SKILL.md is capped at 480 lines (maxSkillMDLines), and the renderer walks a budget ladder of 8 items, 6 quotes, 240 characters per quote, and 900 characters per paragraph, then 5, 4, 180, and 600, then 3, 3, 140, and 400. The first set that fits wins, and the overflow evidence stays in the reference files. The skill name is capped at 48 characters, matches ^[a-z0-9-]{1,48}$, takes a -voice suffix, and falls back to youtube-channel-voice.

The bundle below is real output stored from a run against @Maxinomics on 18 September 2026: prompt version 1, model gemini-3.5-flash, 11 videos analysed, 11 transcripts used, all of them auto-generated captions. Nothing below is reconstructed.

---
name: "maxinomics-voice"
description: "A writing brief for Maxinomics, to be loaded when drafting scripts that analyze global business, economics, and industrial supply chains through real-world data."
metadata:
  channel_url: "https://www.youtube.com/channel/UCUEmaeh13ai1ivT5wzz5Lhg"
  videos_analyzed: 11
  generated_at: "2026-09-18T17:07:05Z"
  generator: prepublish
---

The economic, industrial, and geopolitical forces driving global systems, business models, and supply chains.

Where it sits. An analytical, data-driven explainer channel that bypasses political rhetoric and corporate spin to focus on physical constraints, unit economics, and historical parallels.

What a viewer gets. A deep, logical understanding of how complex global systems actually work by tracing the money and physical resources underneath them.

Credibility markers

• Uses real-time industry data platforms, such as FreightWaves for freight intelligence.
• Cites academic research papers from institutions like MIT and Boston University.
• Breaks down complex corporate operations into precise unit economics, such as return per ton of payload.
• Draws direct historical parallels, comparing modern tech companies to 19th-century railroads or the 1920s rubber monopoly.

Pacing notes

• Videos range from 13 to 25 minutes, allowing for deep, multi-chapter historical and economic investigations.
• Chapters are clearly defined, often transitioning from a modern corporate dilemma to a historical case study before returning to the present.
• The script maintains a steady, deliberate pace, using pauses and musical shifts to let complex mathematical or economic points sink in.

The closing provenance block of the same file reports `Videos analysed: 11 (2025-12-23 to 2026-08-07)` and `Transcripts used: 11 (0 manual, 11 auto-generated)`. It also records what the model could not establish. For this run the hooks carry no timings, and the note gives the reason:

> the exact seconds to payoff for the hooks could not be determined from the provided metadata as the transcripts do not contain explicit timestamps for the resolution of the opening promises.

Those values are zero in the file.

One detail about the evidence lines in the bundle: they reproduce the creator's own words, which means they carry the punctuation, filler, and mishearings of the caption track. Those passages sit in blockquotes and are quoted as they are.

Unzip the download. The archive already contains a top-level folder named after the skill, and every client below expects exactly that shape.

Cursor also loads .claude/skills/ and .codex/skills/ for compatibility, so one Claude Code install serves both. Copilot takes /skills reload to pick up a new folder without restarting, then /skills info <name> to confirm. Codex CLI needs a restart if a new skill does not appear.

Three constraints from the Agent Skills specification apply to any hand-editing afterwards. The name field must match the parent directory name, the description field is capped at 1024 characters, and the body is meant to stay under 500 lines with longer material in references/ (specification, retrieved 19 September 2026). The generator already works inside those limits, because it caps SKILL.md at 480 lines and puts the deep evidence in three reference files.

The 12-video budget cuts both ways. It is enough to describe a settled format and too little to describe a channel in transition.

Two practical rules follow. Pick a channel whose last dozen long-form uploads resemble each other, and check the provenance block before trusting the voice section, because the upload date range printed there is the window the model actually read.

A captions failure caused by YouTube blocking our own network is reported separately as captions_blocked and does not charge the daily run, because that failure is ours rather than the channel's (ops/specs/channel-skill-generator.md, 18 September 2026).

Read the provenance block first, including the "What the data could not show" list. It is the model telling you where it guessed or gave up, and the fastest route to the parts that need a human.

The evidence sections are worth trusting without re-reading the channel, because a machine check backs them. Every *_quote field the model returns is compared against the supplied transcripts, and a quote longer than 8 words that cannot be found is removed, with the removal recorded in the provenance block (ai.ValidateChannelSkillQuotes, ai.StripChannelSkillUnverifiedQuotes). The writer gets up to three attempts, each retry naming the exact failures. Quotes of 8 words or fewer are not checked, so treat a short quotation as a paraphrase and a long one as grounded.

These sections deserve an edit:

• Identity, audience, and the draft checklist. These are interpretation rather than measurement. The model read metadata and transcript excerpts, and it did not meet the audience.
• Thumbnail conventions. They are inferred from titles, descriptions, tags, and chapters. The writer never sees the thumbnail image.
• Payoff timings. seconds_to_payoff depends on captions or chapters carrying timing. When it cannot be established, the value is zero and the reason appears in the provenance notes, as in the Maxinomics bundle above.
• Title formulas. A formula carries an example only when that exact title appears in the analysed snapshot, so a missing example signals a pattern the model generalised.

Everything else can be saved and used. There is no build step and no schema to validate.

It reads public captions and metadata, and nothing else. It does not watch the video. Delivery, editing rhythm, music, on-screen text, and the thumbnail image are invisible to it, which is why thumbnail guidance is inferred rather than observed.

It describes patterns rather than predicting results. The bundle carries no claim about retention, watch time, or platform treatment, and the model is instructed to report a gap rather than fill one. The provenance block says so directly: for the Maxinomics run it lists as absent "audience retention, click-through rates, and private analytics."

The transcripts are frequently auto-generated, so a verbatim quote can contain a caption track's error. The generator copies that text as it stands, which keeps the quote traceable and keeps a misheard word attributable to the source.

Finally, the analysis window is recent by design. Twelve uploads is a snapshot of how a channel publishes now, not a history of how it got there. If the channel has a second format that matters, the honest move is a second run once that format fills the window.

The channel scanner reads the same public surface if you want the raw numbers before committing to a skill run, and how to write a YouTube script covers the drafting side that the brief feeds.