---
name: tt-caption-writer
description: "Write a TikTok caption under 2,200 chars (hashtags included), pick a tasteful 3 to 5 hashtag set with mixed reach, and set the platformSettings.tiktok flags (viewer setting, comments, duet, stitch, commercial and branded content). Front-loads a reason to comment, runs the humanizer pass, and publishes the rendered video via Publora on approval. Use to caption a finished video. Not for the in-video hook (use tt-hook-scripter) or scrubbing a script (use tt-humanizer)."
title: tt-caption-writer
canonical_url: https://skilld.dev/gh/sergebulaev/tiktok-skills/tt-caption-writer
last_updated: 2026-10-29T11:31:28.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/settings-matrix.md](https://skilld.dev/api/skills-raw/sergebulaev/tiktok-skills/tt-caption-writer/references/settings-matrix.md).
>
> If the user asked to install this Skill, run `npx skilld install sergebulaev/tiktok-skills/tt-caption-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/tt-caption-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/tiktok-skills/tt-caption-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/tt-caption-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/tt-caption-writer --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/tt-caption-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.

# TikTok Caption Writer

Write the caption that sits under the video: a tight caption inside the 2,200
char API limit, a mixed-reach hashtag set, and the `platformSettings.tiktok`
flags that control reach and interaction. On TikTok the caption supports the
video, it does not carry it. The hook is in the first 1-3 seconds of the clip
(see `tt-hook-scripter`); the caption's job is to add context and earn a comment.

## When to use

- User has a video (or a script) and needs the caption, hashtags, and settings
- User is about to upload and wants the posting flags right
- User wants Claude Code or Codex to schedule a rendered .mp4 via Publora

## What this skill produces

- **Caption** (<= 2,200 chars on the API; aim much shorter), first line front-
  loaded with a reason to read or comment
- **Hashtag set** (3 to 5, mixed reach), placed at the end
- **platformSettings.tiktok** flags with a plain-English summary
- On approval, the publish call (draft -> upload -> schedule) when a video file
  is supplied

## The TikTok settings (platformSettings.tiktok)

Build these with `lib.tiktok_settings(...)`. Defaults match Publora's.

| Setting | Values / default | What it does |
|---|---|---|
| `viewerSetting` | PUBLIC_TO_EVERYONE (default), MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY | who can view. Effectively required; an empty value is rejected |
| `allowComments` | true (default) | viewers can comment |
| `allowDuet` | false (default) | viewers can Duet |
| `allowStitch` | false (default) | viewers can Stitch |
| `commercialContent` | false (default) | the video is commercial |
| `brandOrganic` | false (default) | promoting your own brand |
| `brandedContent` | false (default) | paid partnership / sponsored |

### Two gotchas you must surface to the user

1. **Boolean inversion bug.** Publora currently maps `allowComments`,
   `allowDuet`, `allowStitch` to TikTok's `disable_*` flags, so the booleans can
   land inverted (sending `allowDuet: true` may disable duets). The status cannot
   be confirmed from the API alone. **Test with a `SELF_ONLY` draft before
   trusting these values.** Tell the user this whenever they change a flag.
2. **Commercial disclosure.** If `commercialContent` is true, at least one of
   `brandOrganic` (your own brand) or `brandedContent` (paid partnership) must
   also be true, or Publora rejects it. `lib.tiktok_settings` enforces this.

### Posting reality

- **Unaudited apps post PRIVATE only.** Until the publishing app passes TikTok's
  review, posts are forced to `SELF_ONLY` regardless of `viewerSetting`. Warn the
  user if a "public" post lands private.
- For reach, use `PUBLIC_TO_EVERYONE`. For an end-to-end test, use `SELF_ONLY`.

## 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 `tt-humanizer --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, goal first.** Ask (or infer) what the caption should earn,
   then shape for it: comments -> end on one specific question tied to the video;
   saves -> promise reference value ("the 3 settings are in the caption");
   shares -> a claim people will want to show someone; profile taps -> an open
   loop the pinned video pays off. Then gather the video topic/script, the
   niche, whether it is commercial, and whether a rendered
   .mp4 path exists.
2. **Draft the caption.** Front-load the first visible line with a reason to read
   or a specific question to comment on. Keep it tight. Em dashes under the cap
   (about one per 100 words; a short caption rarely needs one), no AI vocab
   cluster. Optionally restate the hook's open loop as a comment prompt.
3. **Pick hashtags.** 3 to 5, mixed reach: one broad, one to two niche-defining,
   one to two specific to the video. Put them at the end. Never stuff.
4. **Set the flags.** Default to `PUBLIC_TO_EVERYONE`, comments on, duet/stitch
   off, no commercial flags. Adjust per the user, and surface the two gotchas.
   Build with `lib.tiktok_settings(...)`.
5. **Char check.** Confirm caption + hashtags <= 2,200. If over, tighten.
6. **Humanizer pass.** Scrub 2026 AI vocab by density, cap em dashes (about
   one per 100 words, never swap one for a period), break stacked triads,
   generic openers, reveal bridges and sincerity openers ("not gonna lie").
   Leave the rhythm alone; never chop a line for punch. Canonical rules:
   `tt-humanizer` V3.
7. **Approval card.** Show: caption, char count, hashtag set, settings summary,
   and the resolved `viewerSetting` (flag if it may post private).
8. **On approval.** Call `lib.publish("video", caption, target_url=<upload or
   profile URL>, video_path=<path or None>, platform_settings=<settings>,
   scheduled_time=<iso or None>, platforms=[<TIKTOK_PLATFORM_ID>])`. With a video
   path and Publora configured, it runs draft -> upload -> schedule. Without one,
   it returns the caption and settings to upload in-app.

## Hard rules

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

- Caption + hashtags must fit 2,200 chars (API), hashtags included. Aim far under.
- 3 to 5 hashtags, mixed reach, at the end. Never 10+, never mid-sentence.
- The caption never does the hook's job. The hook is in the video.
- Always set `viewerSetting`. Never ship an empty value.
- Surface the boolean inversion warning whenever an interaction flag changes.

## Anti-patterns (skill will refuse)

- Hashtag walls (10+), or hashtags jammed into the sentence.
- Em dashes above the cap (more than about one per 100 words), or an em dash swapped for a period.
- "The result?" reveals and "No X. No Y. Just Z." staccato stacks added for punch.
- "Follow for part 2 / like and subscribe / don't forget to share" stacks.
- A caption that repeats the spoken hook word for word.
- `commercialContent: true` with neither brand flag set.
- Claiming a post will be public when the app is unaudited (it will be private).

## Resources

- `../../references/voice-rules.md` - caption and hashtag rules
- `../../references/algorithm-heuristics.md` - caption, hashtag, and settings heuristics
- `references/settings-matrix.md` - every platformSettings.tiktok value, defaults, and the known bugs
- `lib/publora_client.py` - `tiktok_settings(...)`, `publish_video(...)`, `create_draft(...)`

## Optional illustration

Offer a generated image when a visual would lift reach. Draft a prompt and call
`lib.illustrate(prompt, kind="story")`, pulling brand handle/color from Voice &
Brand Profile section 6 for a pixel-exact overlay. Show the returned `url` + `cost`,
for a TikTok photo post, attach the image via `media_urls=[url]` (TikTok photo carousel); for a video, TikTok's API has no cover-image field, so set the cover in the TikTok app. Full workflow (incl. quote-cards):
`../tt-humanizer/sub-skills/illustration.md`. No Pixfaro key -> it drafts the prompt for you to generate manually.
## Related skills

- `tt-hook-scripter` - the in-video hook (the caption does not replace it)
- `tt-humanizer` - scrub the caption before publishing
- `tt-content-planner` - schedule captions across a posting week
