---
name: yt-description-writer
description: "Write a full YouTube video description under 5,000 characters with a first-150-character hook (the only part visible before Show more, and what shows in search and suggested), timestamped chapters, naturally placed keywords, links, and a clear call to action. Covers long-form and YouTube Shorts. Becomes the create-post content that publishes with the video. Use to write or rework a description. Not for the title (use yt-title-optimizer) or the spoken opening (use yt-hook-scripter)."
title: yt-description-writer
canonical_url: https://skilld.dev/gh/sergebulaev/youtube-skills/yt-description-writer
last_updated: 2026-10-29T10:46:08.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/description-template.md](https://skilld.dev/api/skills-raw/sergebulaev/youtube-skills/yt-description-writer/references/description-template.md).
>
> If the user asked to install this Skill, run `npx skilld install sergebulaev/youtube-skills/yt-description-writer`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/yt-description-writer`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/sergebulaev/youtube-skills/yt-description-writer) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/yt-description-writer`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/yt-description-writer --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/yt-description-writer --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# YouTube Description Writer

The description does three jobs: it hooks the reader in its first 150 characters,
it feeds YouTube and Google search, and it organizes the video with chapters and
links. This skill writes all three layers.

## When to use

- User says "write the description for this video"
- User has a video and wants chapters, keywords, and links structured
- User wants the first 150 chars optimized for the search/suggested snippet
- User is about to upload and needs the `content` that ships with the video

## The three layers of a description

| Layer | Chars | Job |
|---|---|---|
| **Hook** | first ~150 | the only text visible before "Show more"; also the search/suggested snippet. Lead with the payoff or the question and the search phrase. |
| **Body** | ~150 to 1,000 | expand the value, restate the promise, place the main keywords naturally, link the key resource. |
| **Furniture** | rest, up to 5,000 | chapters, links, social, credits, hashtags. Skimmable, labeled. |

## Steps

**Voice profile first (all drafts).** If `../../references/voice-profile.md` has `filled: yes`, load it and match the user's voice fingerprint, hard rules, and CTA/link style throughout. If it is not filled, mention once that `yt-community-post-writer --mode profile` can learn their voice from a few posts, then proceed with the generic voice rules.

**Never invent the specifics.** The rules below ask for a concrete number, a date and a named entity, because that is what separates a real post from a generated one. Take them from what the user actually said in this conversation. **Do not invent a figure, a date, a client name or a result, and do not soften a vague claim into a plausible-looking number.** If the user has nothing concrete for a beat, ask them once, and if they still have nothing, drop the claim rather than decorate it. A published invented number is a retraction; a missing one is only a weaker post.

1. **Gather inputs.** The title (so the description complements it), the video's
   payoff, the main search phrase plus 3 to 5 secondary keywords, the chapter
   beats with timestamps, any links (lead magnet, gear, socials), and whether it
   is long-form or a Short. If a URL is given, parse it with `lib/url_parser.py`.
2. **Write the first 150 chars as a second hook.** Lead with the payoff or the
   question, work the primary keyword in naturally, and make it read well as a
   standalone snippet. This is not "welcome back to the channel".
3. **Write the body.** 2 to 4 short paragraphs that restate the promise and place
   the keywords without stuffing. Put the single most important link here.
4. **Add chapters.** Timestamps starting at `0:00`, each label short and
   descriptive. YouTube needs at least 3 chapters and a `0:00` start to enable
   the chapter UI. For a Short, skip chapters.
5. **Add the furniture.** Links section, socials, a one-line CTA (subscribe for
   the specific reason, not "smash like"), and 3 to 5 relevant hashtags at the
   very end (the first 3 surface above the title).
6. **Humanizer pass and length check.** Scrub 2026 AI vocabulary by paragraph
   density (one marker is fine; three in one paragraph means rewrite it), cap
   em dashes at about one per 100 words (replace the excess with a comma,
   colon or line break, never a period), strip reveal bridges and sincerity
   openers ("let me be honest"); never add a hedge or confession the creator
   did not write. Keep the whole thing under 5,000 chars. Confirm the first
   150 read well truncated.
7. **Approval card.** Show the description with a marked 150-char cutoff and the
   total char count.
8. **On approval.** This description is the `content` passed to
   `lib.publish(kind="video"|"short", draft_text=<description>, title=<title>,
   ...)`. The title travels separately in `platformSettings.youtube.title`.

## Hard rules

Global voice rules: see root `SKILL.md` Voice rules. Additional skill-specific
rules:

- 5,000-char hard cap. The first 150 chars carry the hook and the search phrase.
- The first line is never boilerplate ("Hi everyone, welcome back").
- Chapters: at least 3, first one at `0:00`, short labels. Long-form only.
- Keywords appear in natural sentences, never as a comma-separated dump.
- Hashtags: 3 to 5 max, at the end. More than 15 makes YouTube ignore all of them.
- Every link is labeled so the reader knows what it is before clicking.

## Anti-patterns (skill will refuse)

- A boilerplate greeting in the first 150 chars.
- A keyword dump or a tag wall pretending to be a description.
- 15+ hashtags (YouTube strips them all).
- Em dashes above the cap (more than about one per 100 words), or an em dash swapped for a period.
- "Smash that like button and subscribe" dead phrasing.
- Chapters that do not start at `0:00` (the UI will not render them).
- Raw unlabeled links.

## Resources

- `../../references/algorithm-heuristics.md` - the 150-char snippet, chapters, search signals
- `../../references/voice-rules.md` - the canonical voice rules
- `references/description-template.md` - the full skeleton with chapters, links, hashtags

## Related skills

- `yt-title-optimizer` - the title the description complements
- `yt-hook-scripter` - the spoken first 30 seconds (different from the written hook)
- `yt-content-planner` - keyword and link strategy across a series
