← All skills
  • Social
  • v1.0.0
  • instagram
  • captions
  • hashtags
  • carousel
  • audit

Instagram Marketing

Nine focused Instagram craft skills: write a caption with a first-125-char hook, plan a carousel slide by slide, reverse-engineer a hook that worked, size hashtags the 2026 way, strip AI tells, audit the profile, plan a week, repurpose cross-platform content, and read your account's real saves and shares.

SKILL.md

Instagram Marketing

A bundle of 9 focused Instagram skills. Each one is single-purpose, follows the draft → approval → publish pattern, and publishes through the myclawbots MCP tools — the same connected Instagram account the dashboard manages. No third-party posting service, no extra API key, no separate signup.

Routing — pick the sub-skill

Each sub-skill lives at scripts/sub-skills/<name>/SKILL.md. Read the one you need; do not load all nine.

The user wants Sub-skill
A caption (hook in the first 125 chars, body, one CTA) ig-caption-writer
A carousel planned slide by slide ig-carousel-planner
The hook reverse-engineered from a post they admire ig-hook-extractor
Hashtags sized the 2026 way (3-5, not 30) ig-hashtag-strategist
AI tells removed, or a draft audited before posting ig-humanizer (plus --mode audit)
A week of Reels, carousels and stories planned ig-content-planner
A LinkedIn post / blog / YouTube script / X thread made native here ig-repurposer
The profile audited and rewritten (photo, NAME, bio, link, highlights, grid, pins) ig-profile-optimizer
Their real account numbers and competitor research ig-audience-insights

Shared reference material sits in scripts/references/: hook-formulas.md, voice-rules.md, hashtag-strategy.md, algorithm-heuristics.md, media-workflow.md, and the user's voice-profile.md.

Publishing: the myclawbots MCP flow

The myclawbots MCP server is pre-configured on this machine. Do every publish and every read through its tools — never hand-build a Graph API call, and never send the user to a third-party scheduler.

1. list_social_accounts          -> the Instagram account_id (call this FIRST)
2. create_upload_url             -> one-time upload_url + final public_url
   curl -X PUT --data-binary @slide1.jpg -H "Content-Type: image/jpeg" <upload_url>
   (repeat per file, in slide order, for a 2-10 item carousel)
3. post_to_social                -> { platform: "instagram", account_id, content,
                                       media_url | media_urls }

Both halves of step 2 are required. The public_url is dead until the PUT succeeds; posting it early hands Instagram a 404, which Instagram then reports as its own download failure. That reads like a domain-verification problem and is not one. If the image exists only in the conversation and not on disk, use upload_media with base64 instead (small images, 1-2 files max).

Full detail, container rules and limits: scripts/references/media-workflow.md. The canonical tool contract and the per-platform rules live in the social-manager skill — read it when you need anything beyond the Instagram flow above.

Instagram facts that change how you draft

  • Media is mandatory. Instagram rejects text-only posts. The writer sub-skills produce the caption, hook, hashtags and slide plan; the user supplies the image or video, or carousel-generator renders the slides.
  • Instagram cannot be scheduled through our API. scheduled_time is Facebook-only. An Instagram post publishes when you call post_to_social. When a plan calls for a posting time, hand the user the time and post then — never tell them it is scheduled.
  • Video always publishes as a Reel (up to 15 min; 9:16 reads best).
  • Carousel is 2-10 items via the API — the native app allows 20.
  • Mixed carousels (photos + video) are supported on Instagram, unlike Facebook and LinkedIn.
  • Licensed library music cannot be attached via any API. The audio has to be in the file already. Say so rather than trying.
  • Business or Creator account required. Personal accounts cannot publish through the API at all.

Images

  • Images the user attached in chat are already on this machine under /tmp. Find the newest rather than asking for a path: ls -t /tmp/*.png /tmp/*.jpg /tmp/*.jpeg /tmp/*.webp 2>/dev/null | head -5
  • Need slides generated? Use the carousel-generator skill (5 themes, --platform instagram-portrait), then stage the PNGs with create_upload_url.
  • Need a single generated image? Use gemini-image (Gemini, through the vault) or DALL-E with vault-curl and $OPENAI_KEY (a stand-in for the user's OpenAI key). Agents not yet moved to the vault may instead have real keys in the GEMINI_API_KEY / OPENAI_API_KEY variables: use those with plain curl, in the same header. Never print a key. Ask the user which provider before spending their credits. Workflow: scripts/sub-skills/ig-humanizer/sub-skills/illustration.md.
  • Accepted types: jpeg, png, webp, gif, mp4, quicktime. Images ≤12MB, video ≤300MB. Staged URLs live ~2h — stage, then post promptly; an expired URL cannot be retried, it has to be re-staged.

Reading real numbers

ig-audience-insights covers this in full. The short version of what is and is not readable:

  • The user's own connected account — get_account_insights, get_recent_posts, get_post_insights, get_post_comments. Real reach, saves and shares, not estimates. This is better data than any scraper returns.
  • Competitors — search_public_pages and get_public_page_metrics are Facebook-only; lookup_threads_profile reads a public Threads profile. There is no Instagram competitor-stats tool and no hashtag scanner. When the user wants a niche scan, say that plainly and offer the paste path — never invent numbers, and never imply we can scrape Instagram.
  • Instagram may return comments with no author: Meta withholds the username on comments the account does not own. The response carries a note — relay it and stop. Nothing is broken and reconnecting will not fix it.

Approval is not optional

Every publish goes under the user's name on their real account. Show the approval card — formula, the hook with its character count, the full caption, the hashtag set, the media, the primary goal — and get an explicit "post it" before calling post_to_social. Confirm again before delete_post, which is irreversible.

A successful post may come back with a notice field. Relay it verbatim. Never describe a post as live and public without positive evidence.

Voice rules (baked into every sub-skill)

  1. Em dashes (—) capped at about 1 per 100 words (1-2 per caption, 1 per slide); replace the excess with a comma, colon, parentheses or a line break, never a period. A single em dash is not a tell. No en dashes between clauses, no double dashes.
  2. Use .. or a line break as a soft pause when rhythm calls for it.
  3. Capitalize all personal, company, and product names.
  4. Sentence starts can be lowercase (native caption voice); names stay capitalized.
  5. Avoid AI vocabulary: leverage, fundamentally, streamline, harness, delve, unlock, elevate, foster.
  6. Specific numbers beat adjectives. "47 minutes" beats "fast".
  7. One idea per caption. The first 125 chars carry the hook (the "more" fold).
  8. Hashtags are sizing, not volume: 3-5 sized tags, not 30.

Canonical reference: scripts/references/voice-rules.md.

How Instagram URLs map

URL shape Parsed to
https://www.instagram.com/p/SHORTCODE/ shortcode, type post
https://www.instagram.com/reel/SHORTCODE/ shortcode, type reel
https://www.instagram.com/USERNAME/ username, type profile
https://www.instagram.com/stories/USER/ID/ username + id, type story

A carousel shares the /p/ path with a single image; the carousel is detected from the media, not the URL.

  • social-manager — the canonical myclawbots MCP tool contract and the cross-platform rules. Read it for anything past the Instagram flow above.
  • carousel-generator — renders the slide PNGs ig-carousel-planner writes.
  • instagram-manager — the always-on account-manager persona. This bundle is the craft layer it reaches for when drafting.
  • google-workspace — optional, for saving content calendars to Sheets.

Attribution

Adapted from instagram-skills by Sergey Bulaev (MIT, see LICENSE.upstream). The strategy, formulas and humanizer research are theirs; the publish and read layers were rewritten for the myclawbots MCP tools.

Scripts

28 files ship with this skill. They are installed beside the SKILL.md.

scripts/references/algorithm-heuristics.md7.9 KB
# 2026 Instagram Posting Heuristics

Synthesized from Instagram's public ranking statements (Adam Mosseri's creator
posts), the 2023-2026 algorithm explainers, and observed creator data. Numbers
marked "reported" are community-measured, not officially confirmed. Instagram
ranks each surface (Feed, Reels, Explore, Stories) with its own model, but the
signals below generalize.

## Contents

- Signal weights (relative reach impact)
- The first 30-60 minutes
- Reach suppressors (avoid)
- Reach amplifiers
- Format and media limits (via the publishing API)
- Carousels
- Reels
- Stories
- Timing
- Saves and sends are the underrated levers
- Pre-publish checklist

## Signal weights (relative reach impact)

Instagram scores predicted engagement, and the engagement types are not equal.
Reported relative weights from creator testing and platform statements:

| Signal | Relative weight | Note |
|---|---|---|
| **Send / share** (to a friend in DM, or reshare to story) | highest positive | "sends per reach" is the metric the algorithm leans on hardest in 2026 |
| **Save** | high | the "I will come back to this" signal; drives reach for how-tos, lists, frameworks |
| **Comment** (esp. with author reply back) | high | a real conversation is a strong quality signal |
| **Reel watch time / completion / rewatch** | high (Reels) | for video, retention and rewatch decide the push |
| **Profile visit then follow** | high | the growth signal; payoff content earns it |
| **Like** | low | cheap affirmation, light reach |
| **Negative: "not interested", unfollow, hide, report** | heavy penalty | one report outweighs many likes |

Takeaway: optimize for **sends, saves, and comments**, not likes. The single
most useful question before posting: would a viewer send this to one specific
friend, or save it to use later?

## The first 30-60 minutes

- The opening window sets the trajectory. Early saves, sends, and comments tell
  the ranker to widen distribution to non-followers via Explore and the Reels
  feed.
- **Reply to early comments fast.** Author replies pull more comments and signal
  an active conversation.
- A Reel that holds retention through the first 3 seconds in the opening test
  earns a wider push.

## Reach suppressors (avoid)

- **Engagement bait** ("comment YES", "tag 3 friends", "double tap if") is
  explicitly downranked.
- **Reposted/recycled video with another app's watermark** (a visible logo from
  a different platform) is suppressed in Reels.
- **All-hashtag captions** (20-30 tags crammed at the top) read as spam in 2026
  and do not help reach. Sized 3-5 tags is the current guidance.
- **Aspect ratios outside 4:5 to 1.91:1** get cropped, which hurts a carousel or
  a feed image.
- **High hide/unfollow/report rate** collapses distribution fast.
- **Mixed media in one carousel** is rejected by the API outright.

## Reach amplifiers

- **Sends are the lever.** A post built to be sent to a friend (a relatable
  truth, a useful list, a "you need to see this") out-reaches a like-bait post.
- **Saves compound.** Save-bait formats (lists, frameworks, how-tos, before/
  after) keep earning reach for days as Explore surfaces them.
- **Reels with strong retention** get pushed to non-followers the hardest of any
  format in 2026. Original audio and on-screen text both help.
- **Carousels get a second look:** a viewer who does not swipe may see slide 2
  on a re-surface, so Instagram sometimes re-shows carousels, giving them a
  longer tail.
- **Replying to your own comments and DMs** in the first hour keeps the
  conversation signal alive.

## Format and media limits (via the publishing API)

| Item | Limit |
|---|---|
| Caption | 2,200 chars (first ~125 visible before "more") |
| Hashtags | 30 max per post (but 3-5 sized tags is the 2026 practice) |
| Carousel items | 2-10 (API; the native app allows 20) |
| Image formats | JPEG, PNG, WebP (WebP auto-converts to JPEG) |
| Image max size | 8 MB |
| Reel duration | up to 3 min (180s) via API; 5-90s are eligible for the Reels tab |
| Reel/video max size | 300 MB |
| Carousel video | up to 60s per clip |
| Mixed media in a carousel | not allowed (all images or all video) |
| Aspect ratio | 4:5 (portrait) to 1.91:1 (landscape); portrait 4:5 fills the feed |
| Rate limit | ~50 posts / 24h (some accounts report 25) |

- **Media is required on every post.** Instagram rejects text-only posts. The
  writer skills produce the caption; the user supplies the image or video.
- A single image posts as a photo; 2-10 images post as a carousel; a single
  video posts as a Reel by default (or a Story via `videoType: "STORIES"`).

## Carousels

- **Slide 1 is the entire funnel.** It must promise a payoff and open a loop, or
  the viewer never swipes. Everything else only matters if slide 1 earns the
  swipe.
- **Front-load value.** Swipe-through decays with depth, so the strongest item
  goes on slide 2 or 3, not saved for slide 10.
- **Optimal length: 6-10 slides** for a teaching or list carousel. Each slide
  should make one point and stand alone.
- **The last slide earns the save and the follow.** Close with a one-slide
  summary (the saveable artifact) plus a single clear ask.
- **Design for the 4:5 frame.** Portrait fills more screen and holds attention.

## Reels

- **The first 1-3 seconds decide reach.** Open with a pattern interrupt, an
  on-screen text hook, and the point. No "hey guys, welcome back".
- **Retention and rewatch are the goal.** A loop-able ending (the last frame
  flows into the first) lifts rewatch.
- **On-screen text** lets silent viewers get the hook and improves completion.
- **Original or trending audio** helps, but the hook and retention matter more.
- No visible watermark from another video app.

## Stories

- **Stories do not drive reach** to non-followers; they deepen the relationship
  with existing followers and keep you top-of-mind.
- A **reshare of your feed post to your story** is a send-equivalent signal and
  pushes the original to followers who missed it.
- Interactive stickers (poll, question, quiz) earn the taps that keep you in the
  front of the story tray.

## Timing

| Audience | Best windows (local) |
|---|---|
| US creators / consumers | weekdays 11 AM-1 PM and 7-9 PM, plus Sun evening |
| B2B / founders | Tue-Thu mid-morning and lunch |
| Global mixed | post when your specific audience is online (check your insights) |

- Consistency beats raw frequency. 3-5 high-quality posts a week with a
  steady cadence outperforms a daily dump of filler.
- Reels can be posted more often than carousels without fatigue, because each
  reaches a fresh non-follower audience.

## Saves and sends are the underrated levers

- A **save** means the viewer intends to return: it rewards lists, frameworks,
  how-tos, and before/after content. Design save-bait deliberately (IG5, IG8,
  IG10, IG1, IG6).
- A **send** means the viewer thought of a specific person: it rewards relatable
  truths, myth-busters, and contrarian takes (IG2, IG7, IG3, IG9).
- Both spread reach far more than a like. The hook-formulas goal tags map every
  formula to saves, shares, comments, or follows.

## Pre-publish checklist

- [ ] First 125 chars of the caption stop the scroll on their own.
- [ ] Em dashes (`—`) at or under about one per 100 words (never swap one for a period); no en dashes (`–`) between clauses or double dashes (`--`).
- [ ] No AI vocabulary cluster (3+ markers in one paragraph: leverage, fundamentally, significant, etc.).
- [ ] At least one odd-precision number with a named referent where the claim allows it.
- [ ] 3-5 sized hashtags (not 30), at the end or in the first comment.
- [ ] 0-3 emoji, placed with intent, none sprinkled.
- [ ] Carousel slide 1 promises and opens a loop; the last slide pays off + asks.
- [ ] Media supplied and within limits (JPEG/PNG/WebP, no mixed media, 2-10 slides).
- [ ] Close is a landing or a specific save/send ask, not "what do you think?".
- [ ] A clear primary goal (saves / shares / comments / follows), not all at once.