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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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(...).
- Char check. Confirm caption + hashtags <= 2,200. If over, tighten.
- 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.
- Approval card. Show: caption, char count, hashtag set, settings summary,
and the resolved
viewerSetting (flag if it may post private).
- 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
1---2name: tt-caption-writer3description: "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)."4metadata:5 source: https://skillmd.com/skills/sergebulaev/tt-caption-writer6---78# TikTok Caption Writer910Write the caption that sits under the video: a tight caption inside the 2,20011char API limit, a mixed-reach hashtag set, and the `platformSettings.tiktok`12flags that control reach and interaction. On TikTok the caption supports the13video, it does not carry it. The hook is in the first 1-3 seconds of the clip14(see `tt-hook-scripter`); the caption's job is to add context and earn a comment.1516## When to use1718- User has a video (or a script) and needs the caption, hashtags, and settings19- User is about to upload and wants the posting flags right20- User wants Claude Code or Codex to schedule a rendered .mp4 via Publora2122## What this skill produces2324- **Caption** (<= 2,200 chars on the API; aim much shorter), first line front-25 loaded with a reason to read or comment26- **Hashtag set** (3 to 5, mixed reach), placed at the end27- **platformSettings.tiktok** flags with a plain-English summary28- On approval, the publish call (draft -> upload -> schedule) when a video file29 is supplied3031## The TikTok settings (platformSettings.tiktok)3233Build these with `lib.tiktok_settings(...)`. Defaults match Publora's.3435| Setting | Values / default | What it does |36|---|---|---|37| `viewerSetting` | PUBLIC_TO_EVERYONE (default), MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY | who can view. Effectively required; an empty value is rejected |38| `allowComments` | true (default) | viewers can comment |39| `allowDuet` | false (default) | viewers can Duet |40| `allowStitch` | false (default) | viewers can Stitch |41| `commercialContent` | false (default) | the video is commercial |42| `brandOrganic` | false (default) | promoting your own brand |43| `brandedContent` | false (default) | paid partnership / sponsored |4445### Two gotchas you must surface to the user46471. **Boolean inversion bug.** Publora currently maps `allowComments`,48 `allowDuet`, `allowStitch` to TikTok's `disable_*` flags, so the booleans can49 land inverted (sending `allowDuet: true` may disable duets). The status cannot50 be confirmed from the API alone. **Test with a `SELF_ONLY` draft before51 trusting these values.** Tell the user this whenever they change a flag.522. **Commercial disclosure.** If `commercialContent` is true, at least one of53 `brandOrganic` (your own brand) or `brandedContent` (paid partnership) must54 also be true, or Publora rejects it. `lib.tiktok_settings` enforces this.5556### Posting reality5758- **Unaudited apps post PRIVATE only.** Until the publishing app passes TikTok's59 review, posts are forced to `SELF_ONLY` regardless of `viewerSetting`. Warn the60 user if a "public" post lands private.61- For reach, use `PUBLIC_TO_EVERYONE`. For an end-to-end test, use `SELF_ONLY`.6263## Steps6465**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.66671. **Gather inputs, goal first.** Ask (or infer) what the caption should earn,68 then shape for it: comments -> end on one specific question tied to the video;69 saves -> promise reference value ("the 3 settings are in the caption");70 shares -> a claim people will want to show someone; profile taps -> an open71 loop the pinned video pays off. Then gather the video topic/script, the72 niche, whether it is commercial, and whether a rendered73 .mp4 path exists.742. **Draft the caption.** Front-load the first visible line with a reason to read75 or a specific question to comment on. Keep it tight. Em dashes under the cap76 (about one per 100 words; a short caption rarely needs one), no AI vocab77 cluster. Optionally restate the hook's open loop as a comment prompt.783. **Pick hashtags.** 3 to 5, mixed reach: one broad, one to two niche-defining,79 one to two specific to the video. Put them at the end. Never stuff.804. **Set the flags.** Default to `PUBLIC_TO_EVERYONE`, comments on, duet/stitch81 off, no commercial flags. Adjust per the user, and surface the two gotchas.82 Build with `lib.tiktok_settings(...)`.835. **Char check.** Confirm caption + hashtags <= 2,200. If over, tighten.846. **Humanizer pass.** Scrub 2026 AI vocab by density, cap em dashes (about85 one per 100 words, never swap one for a period), break stacked triads,86 generic openers, reveal bridges and sincerity openers ("not gonna lie").87 Leave the rhythm alone; never chop a line for punch. Canonical rules:88 `tt-humanizer` V3.897. **Approval card.** Show: caption, char count, hashtag set, settings summary,90 and the resolved `viewerSetting` (flag if it may post private).918. **On approval.** Call `lib.publish("video", caption, target_url=<upload or92 profile URL>, video_path=<path or None>, platform_settings=<settings>,93 scheduled_time=<iso or None>, platforms=[<TIKTOK_PLATFORM_ID>])`. With a video94 path and Publora configured, it runs draft -> upload -> schedule. Without one,95 it returns the caption and settings to upload in-app.9697## Hard rules9899Global voice rules: see root `SKILL.md` Voice rules. Additional skill-specific100rules:101102- Caption + hashtags must fit 2,200 chars (API), hashtags included. Aim far under.103- 3 to 5 hashtags, mixed reach, at the end. Never 10+, never mid-sentence.104- The caption never does the hook's job. The hook is in the video.105- Always set `viewerSetting`. Never ship an empty value.106- Surface the boolean inversion warning whenever an interaction flag changes.107108## Anti-patterns (skill will refuse)109110- Hashtag walls (10+), or hashtags jammed into the sentence.111- Em dashes above the cap (more than about one per 100 words), or an em dash swapped for a period.112- "The result?" reveals and "No X. No Y. Just Z." staccato stacks added for punch.113- "Follow for part 2 / like and subscribe / don't forget to share" stacks.114- A caption that repeats the spoken hook word for word.115- `commercialContent: true` with neither brand flag set.116- Claiming a post will be public when the app is unaudited (it will be private).117118## Resources119120- `../../references/voice-rules.md` - caption and hashtag rules121- `../../references/algorithm-heuristics.md` - caption, hashtag, and settings heuristics122- `references/settings-matrix.md` - every platformSettings.tiktok value, defaults, and the known bugs123- `lib/publora_client.py` - `tiktok_settings(...)`, `publish_video(...)`, `create_draft(...)`124125## Optional illustration126127Offer a generated image when a visual would lift reach. Draft a prompt and call128`lib.illustrate(prompt, kind="story")`, pulling brand handle/color from Voice &129Brand Profile section 6 for a pixel-exact overlay. Show the returned `url` + `cost`,130for 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):131`../tt-humanizer/sub-skills/illustration.md`. No Pixfaro key -> it drafts the prompt for you to generate manually.132## Related skills133134- `tt-hook-scripter` - the in-video hook (the caption does not replace it)135- `tt-humanizer` - scrub the caption before publishing136- `tt-content-planner` - schedule captions across a posting week