Instagram Publisher

SKILL.md

---
name: Instagram Publisher
description: >
  Instagram publishing skill for posting Instagram images, Reels, and carousels
  through the MyBrandMetrics API. Supports remote URLs, local files, captions,
  carousel items, Reel feed sharing, thumbnail offset, publish status checks,
  and natural-language Instagram posting workflows after Instagram Insights is
  connected in MyBrandMetrics.
---

# Instagram Publisher

Publish Instagram images, Reels, and carousels through the MyBrandMetrics API.

Use this skill to publish to Instagram, post to IG, upload an Instagram Reel,
create an Instagram carousel, publish a single image, or check an Instagram
publishing result after Instagram Insights is connected in MyBrandMetrics.

Website: [https://www.clawbus.com/](https://www.clawbus.com/)  
MyBrandMetrics API: [https://mybrandmetrics.com/](https://mybrandmetrics.com/)

## Why This Instagram Publisher

| This skill | Building your own Instagram publishing integration |
| --- | --- |
| Sign in to MyBrandMetrics with Google and connect Instagram Insights. | Set up and maintain your own Meta developer integration. |
| Use a MyBrandMetrics API key, connection ID, and account ID for publishing. | Manage app credentials, account selection, and publishing tokens yourself. |
| Publish images, Reels, and carousels from local files or remote URLs. | Implement media upload, container creation, and publish flows yourself. |
| Use one script for captions, Reel feed sharing, thumbnail offset, and carousel items. | Build separate request handling for post metadata and media-type differences. |
| Check publishing results with the returned publish ID. | Build your own publish-status polling and error handling. |

Use this when you want Instagram image, Reel, or carousel publishing without
building a full Instagram publishing backend yourself.

## Core Capabilities

| Capability | Details |
| --- | --- |
| Instagram image publishing | Publish a single Instagram image from a remote URL or local file. |
| Instagram Reels publishing | Publish an Instagram Reel from a remote video URL or local video file. |
| Instagram carousel publishing | Publish multi-item Instagram carousels from images, videos, local files, or URLs. |
| Post metadata | Set the caption, Reel feed sharing option, and video thumbnail offset. |
| Publish status checks | Check an Instagram publishing job after a post is submitted. |
| Natural-language posting | Use natural-language prompts in chat after the skill is installed. |

## Setup Flow

1. Open [https://mybrandmetrics.com/](https://mybrandmetrics.com/) and sign in
   with Google.
2. In MyBrandMetrics, open **Data sources**.
3. Connect **Instagram Insights** as a data source.
4. Wait until the MyBrandMetrics connection is ready.
5. In [https://mybrandmetrics.com/](https://mybrandmetrics.com/), get the
   MyBrandMetrics API key.
6. Install the `instagram-publish` skill.
7. Start an Instagram image, Reel, carousel, or publish-status workflow with
   natural-language instructions.

## Authentication

Instagram authorization is handled through MyBrandMetrics. Sign in with Google,
connect Instagram Insights as a data source, get the MyBrandMetrics API key,
and use the Instagram connection ID and account ID from MyBrandMetrics when
running direct script commands.

Example `config.json`:

```json
{
  "instagram": {
    "authorization_token": "YOUR_API_KEY",
    "connection_id": "YOUR_CONNECTION_ID",
    "account_id": "YOUR_ACCOUNT_ID"
  }
}
```

## Workflow

Use natural-language prompts in chat after the skill is installed. Include:

- the media URL, local file, or carousel items;
- the caption;
- the post type when it is not obvious: `IMAGE`, `REELS`, or `CAROUSEL`;
- whether a Reel should be shared to feed.

After the posting flow finishes, confirm the Instagram post is live in the
connected account.

Example:

```text
Post this image to Instagram with the caption "Hello World": https://example.com/image.jpg
```

## Search-Friendly Workflows

Common Instagram workflows include:

- publish Instagram images from a remote URL or local file;
- publish Instagram Reels from video URLs or local video files;
- create Instagram carousels with multiple images or videos;
- add captions to Instagram posts, Reels, and carousels;
- check Instagram publish status after a publishing job is submitted;
- use Instagram Insights as the connected MyBrandMetrics data source.

## Use The Script Directly

Use `scripts/publish_instagram.py`.

Single image from URL:

```bash
python3 scripts/publish_instagram.py \
  --api-key YOUR_KEY \
  --connection-id YOUR_CONNECTION_ID \
  --account-id YOUR_ACCOUNT_ID \
  --type IMAGE \
  --url "https://example.com/image.jpg" \
  --caption "Hello World!"
```

Reel from local file:

```bash
python3 scripts/publish_instagram.py \
  --api-key YOUR_KEY \
  --connection-id YOUR_CONNECTION_ID \
  --account-id YOUR_ACCOUNT_ID \
  --type REELS \
  --path "/path/to/video.mp4" \
  --caption "Check this out!" \
  --thumb-offset 1000
```

Mixed carousel:

```bash
python3 scripts/publish_instagram.py \
  --api-key YOUR_KEY \
  --connection-id YOUR_CONNECTION_ID \
  --account-id YOUR_ACCOUNT_ID \
  --type CAROUSEL \
  --items "/path/to/img1.jpg" "https://example.com/video2.mp4" \
  --caption "My Carousel"
```

Check publish status:

```bash
python3 scripts/publish_instagram.py \
  --api-key YOUR_KEY \
  --connection-id YOUR_CONNECTION_ID \
  --account-id YOUR_ACCOUNT_ID \
  --check-id "PUBLISH_ID"
```

## Parameters

| Parameter | Required | Purpose |
| --- | --- | --- |
| `--api-key` | Yes | MyBrandMetrics API key. |
| `--connection-id` | Yes | Instagram connection ID from MyBrandMetrics. |
| `--account-id` | Yes | MyBrandMetrics account ID. |
| `--type` | No | `IMAGE`, `REELS`, or `CAROUSEL`; default is `IMAGE`. |
| `--caption` | No | Instagram caption text. |
| `--url` | No | Remote media URL for a single image or Reel. |
| `--path` | No | Local media path for a single image or Reel. |
| `--items` | For carousel | Space-separated carousel item URLs or paths. |
| `--thumb-offset` | No | Reel thumbnail offset in milliseconds. |
| `--no-feed` | No | Disable sharing Reels to feed. |
| `--no-wait` | No | Do not wait for publish completion. |
| `--check-id` | No | Check status of an existing publish ID. |

Before publishing, confirm the Instagram account, media source, post type, and
caption. For carousels, review every item before posting.