/post-publisher

name: post-publisher
description: "Publish assets to Instagram, Threads, TikTok, X, YouTube, Telegram or LinkedIn, and syndicate articles to dev.to, Telegraph or Hashnode with a canonical URL. Dry-run by default. Use when: 'опубликуй это', 'выложи карусель в треды', 'post this to Instagram', 'кросс-постинг статьи', 'syndicate this article'."

license: MIT
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob

<objective> The last mile. Every other skill in this collection stops at `./generated/...`; this one sends what is there to the platform and records that it did.

Input: an output directory from `carousel-builder` / `reel-builder` (or a single file, or just text). Output: a live post or a platform-side draft, plus a `posted.json` receipt.

This skill does NOT:

• Write the content — that is `viral-text` / `essay-write` / `carousel-builder` / `reel-builder`.
• Schedule anything. There is no queue and no cron. It publishes now, or it stages a draft you finish by hand.
• Post to a platform you have not connected. Credentials are yours; nothing is bundled.
• Guarantee reach, or touch analytics.

</objective>

ROLE

Resolve a source directory → build one platform-neutral `Post` → preflight it against each target platform's real limits → show the user exactly what would go where → ask → publish → write a receipt.

**Publication is irreversible. Dry-run is the default and `--yes` is what leaves it.** Even with `--yes`, each platform is confirmed separately: approving an Instagram post is not approval to also post to X.

PIPELINE

1. **Resolve the source.** A directory is inspected in this order: `final.mp4` → video; several images → carousel (sorted numerically, so `slide-2` precedes `slide-10`); one image → image; nothing → text post. Override with `--kind`.

2. **Resolve the caption.** From `--text`, else `--text-file`, else `captions.md` in the source directory. The parser looks for a `## Main post` / `## Основной пост` heading and takes everything up to the next heading; with no such heading it takes the whole file minus headings. **Always check the extracted text in the dry-run preview** — `captions.md` is written by an agent, so its shape is a convention, not a contract.

3. **Preflight, per platform.** Character limits including hashtags, media count, file size, extension, missing alt text, and each platform's own rules (Telegram's 1024-char caption ceiling that does not apply to text posts; Instagram's 24h posting cap; TikTok's audit caveat). A `block` finding means nothing is sent; a `warn` means it goes but you should know.

4. **Preview + confirm.** Full text, character count, every file with its size and alt text, and whether it is going out live or as a draft.

5. **Publish, then record.** The receipt (`posted.json`) is written immediately after each platform succeeds — a crash mid-fan-out cannot cause a re-post of the platforms already done. A later run with identical content is refused unless `--force`.

PLATFORMS

| Platform | Post kinds | Draft | The thing that will bite you | |---|---|---|---| | `telegram` | text, image, carousel, video | — | Caption on media caps at 1024 chars (text-only gets 4096). Video ≤50 MB. **The only one testable end-to-end without OAuth — start here.** | | `threads` | text, image, carousel, video | container | 500 chars. Text-only posts need no S3 — the easiest real connection. | | `instagram` | image, carousel, video | container | Business/Creator account required. Media is fetched by URL, so **S3 is mandatory**. Video publishes as a Reel (≤300 MB, ≤15 min). 100 posts/24h. | | `tiktok` | video, image, carousel | **inbox** | Direct publishing needs an audited app; without one, posts are silently forced to SELF_ONLY. **Use `--draft`.** | | `x` | text, image, carousel, video | — | 280 chars. 10,000/24h per app, 100/15min per user; what you may spend depends on the plan. Threads publish incrementally — a failure mid-chain leaves earlier posts live. | | `youtube` | video | `private` | 100 uploads/day on their own allocation, drafts included. Cleanest draft of the seven. | | `linkedin` | text, image, carousel, video | — | 3000 chars. Member posts work with `w_member_social`; company pages need the partner-gated Community Management API. |

MODES

Source

• `post-publisher <dir>` — a `carousel-builder` / `reel-builder` output directory
• `post-publisher <file>` — a single image or video
• `post-publisher --kind text --text "..."` — no source at all

Targeting

• `--platform a,b,c` — comma-separated; each is confirmed separately
• `--draft` — stage instead of publish. A platform without drafts is **skipped**, not published live
• `--kind text|image|carousel|video|article` — override auto-detection

Content

• `--text` / `--text-file` — caption (overrides `captions.md`)
• `--title` — YouTube title / LinkedIn article title
• `--hashtags "a,b,c"` — kept separate from the body so preflight can count them
• `--alt "..."` — repeat once per media file, in order
• `--link` — attached where the platform supports it

Article syndication (`--kind article`)

• `--canonical <url>` — **the important one.** The URL of the original on your own domain
• `--description` — SEO excerpt / subtitle
• `--series` — dev.to series name, Hashnode series id
• `--cover-url` — cover image, already hosted
• `--packets <dir>` — write submission packets for the platforms with no API

Execution

• *(nothing)* — dry-run. Prints what would happen and stops
• `--yes` — leave dry-run. Still asks before each platform
• `--force` — publish despite a matching receipt in `posted.json`
• `--publish-container <id>` — publish a Meta container left by an earlier `--draft`
• `--check --platform X` — readiness: credentials present, token usable
• `--list-platforms` — everything, with what each is missing

Exit codes

| Code | Meaning | |---|---| | `0` | Everything asked for happened, or was already done | | `1` | At least one platform failed — blo