Claude GitHub Copilot Skill

threads

Publish text, image, video or carousel posts to your Threads (@threads) account via the official Threads API, and read your own recent posts. Use when the user wants to post to Threads, cross-post a short update / thread, attach an image or link, or review their own Threads posts

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download acedatacloud-skills-skills_threads-c3d1703.zip · 2 KB

Install

skills CLI npx skills add https://github.com/AceDataCloud/Skills/tree/main/skills/threads
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install acedatacloud-skills@llmmart
Git git clone https://github.com/AceDataCloud/Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole acedatacloud/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Call the Threads API (graph.threads.net) with curl + jq. The connector injects one credential: $THREADS_ACCESS_TOKEN (a long-lived Threads access token with the threads_basic + threads_content_publish scopes). Never echo it.

Resolve the caller's Threads user id once (every publish needs it):

ME=$(curl -sS "https://graph.threads.net/v1.0/me?fields=id,username&access_token=$THREADS_ACCESS_TOKEN")
TID=$(echo "$ME" | jq -r .id)
echo "$ME"     # {"id":"<THREADS_USER_ID>","username":"..."}

Errors are JSON with error.message / error.code — show them verbatim. 401 / OAuthException → the token expired or lacks scope; reconnect the Threads connector.

Publish a post (two-step: create container → publish)

Confirm the text with the user first (it publishes as their real account). Text ≤ 500 characters (emoji counted as UTF-8 bytes).

Step 1 — create a media container. Text-only (guard the 500-byte limit first):

TEXT="Shipping one API for AI images → posters, cards, mockups. https://platform.acedata.cloud #AI #API"
[ "$(printf %s "$TEXT" | wc -c)" -le 500 ] || { echo "text exceeds Threads 500-byte limit — shorten it"; }
CID=$(curl -sS -X POST "https://graph.threads.net/v1.0/$TID/threads" \
  --data-urlencode "media_type=TEXT" \
  --data-urlencode "text=$TEXT" \
  -d "access_token=$THREADS_ACCESS_TOKEN" | jq -r .id)
echo "container=$CID"

Image post — add media_type=IMAGE + a public image_url (Threads cURLs it server-side, so it must be on a public server); video uses media_type=VIDEO + video_url:

CID=$(curl -sS -X POST "https://graph.threads.net/v1.0/$TID/threads" \
  --data-urlencode "media_type=IMAGE" \
  -d "image_url=https://cdn.acedata.cloud/xxxx.jpg" \
  --data-urlencode "text=caption here" \
  -d "access_token=$THREADS_ACCESS_TOKEN" | jq -r .id)

Step 2 — publish the container. Text posts publish immediately; for IMAGE / VIDEO / carousel containers you MUST wait ≥30s first so Threads can fetch/process the upload — publishing too early fails or returns no id:

sleep 30   # REQUIRED for IMAGE / VIDEO / carousel; skip for TEXT-only posts
curl -sS -X POST "https://graph.threads.net/v1.0/$TID/threads_publish" \
  -d "creation_id=$CID" -d "access_token=$THREADS_ACCESS_TOKEN" | jq .
# → {"id":"<THREADS_MEDIA_ID>"}

If threads_publish returns no id, the container isn't ready yet — poll GET /v1.0/<CID>?fields=status&access_token=$THREADS_ACCESS_TOKEN until status=FINISHED, then retry publish.

Get the public URL of the published post and hand it to the user:

curl -sS "https://graph.threads.net/v1.0/<THREADS_MEDIA_ID>?fields=id,permalink&access_token=$THREADS_ACCESS_TOKEN" | jq -r .permalink

Carousel (2–20 items)

Create each child with is_carousel_item=true, then a media_type=CAROUSEL container with children=<ID1>,<ID2>,..., then publish the carousel id. Links: add link_attachment=<URL> (text-only posts, ≤5 links). Topic tag: topic_tag=<TAG>.

List my recent posts

curl -sS "https://graph.threads.net/v1.0/$TID/threads?fields=id,text,permalink,timestamp&limit=20&access_token=$THREADS_ACCESS_TOKEN" | jq '.data'

Gotchas

  • 500-char limit; emoji count as their UTF-8 byte length.
  • Media must be a public URL — Threads server-side cURLs image_url/video_url; local files won't work. Upload to a public host / cdn.acedata.cloud first.
  • Wait ~30s before publishing media containers (text publishes instantly); if threads_publish doesn't return an id, poll GET /<container-id>?fields=status.
  • Rate limit: 250 published posts per 24h per profile (a carousel counts as 1).
  • Threads tokens differ from Facebook/Instagram tokens — they come from the Threads OAuth flow on graph.threads.net, not graph.facebook.com.

Record the output

After you successfully publish and obtain the live permalink, call the built-in publish_artifact tool ONCE so the user can track it in My Outputs:

publish_artifact(kind="message", channel="threads", title="<title>", url="<the REAL permalink>", status="delivered")

Use the real returned URL — never fabricate one. Call it once per published item, only after delivery is confirmed; skip it (or use status="failed") if publishing failed. See _shared/artifacts.md.

Files (skills)
  • SKILL.md 5.1 KB
    ---
    name: threads
    description: Publish text, image, video or carousel posts to your Threads (@threads) account via the official Threads API, and read your own recent posts. Use when the user wants to post to Threads, cross-post a short update / thread, attach an image or link, or review their own Threads posts. Auth uses a Threads access token (BYOC). 支持 Threads 文本 / 图片 / 视频 / 轮播发布与自有贴文读取。
    when_to_use: |
      Trigger when the user wants to publish a post to their Threads account or
      review their own recent Threads posts. Threads is Meta's text-first social
      app; the connector stores a Threads access token with threads_content_publish.
      Posting publishes as their real account — confirm the text with the user first.
    connections: [threads]
    allowed_tools: [Bash]
    license: Apache-2.0
    metadata:
      author: acedatacloud
      version: "1.0"
    ---
    
    Call the **Threads API** (`graph.threads.net`) with `curl + jq`. The connector
    injects one credential: `$THREADS_ACCESS_TOKEN` (a long-lived Threads access
    token with the `threads_basic` + `threads_content_publish` scopes). Never echo it.
    
    Resolve the caller's Threads user id once (every publish needs it):
    
    ```bash
    ME=$(curl -sS "https://graph.threads.net/v1.0/me?fields=id,username&access_token=$THREADS_ACCESS_TOKEN")
    TID=$(echo "$ME" | jq -r .id)
    echo "$ME"     # {"id":"<THREADS_USER_ID>","username":"..."}
    ```
    
    Errors are JSON with `error.message` / `error.code` — show them verbatim.
    `401` / `OAuthException` → the token expired or lacks scope; reconnect the
    Threads connector.
    
    ## Publish a post (two-step: create container → publish)
    
    **Confirm the text with the user first** (it publishes as their real account).
    Text ≤ **500 characters** (emoji counted as UTF-8 bytes).
    
    Step 1 — create a media container. Text-only (guard the 500-byte limit first):
    
    ```bash
    TEXT="Shipping one API for AI images → posters, cards, mockups. https://platform.acedata.cloud #AI #API"
    [ "$(printf %s "$TEXT" | wc -c)" -le 500 ] || { echo "text exceeds Threads 500-byte limit — shorten it"; }
    CID=$(curl -sS -X POST "https://graph.threads.net/v1.0/$TID/threads" \
      --data-urlencode "media_type=TEXT" \
      --data-urlencode "text=$TEXT" \
      -d "access_token=$THREADS_ACCESS_TOKEN" | jq -r .id)
    echo "container=$CID"
    ```
    
    Image post — add `media_type=IMAGE` + a **public** `image_url` (Threads cURLs it
    server-side, so it must be on a public server); video uses `media_type=VIDEO` + `video_url`:
    
    ```bash
    CID=$(curl -sS -X POST "https://graph.threads.net/v1.0/$TID/threads" \
      --data-urlencode "media_type=IMAGE" \
      -d "image_url=https://cdn.acedata.cloud/xxxx.jpg" \
      --data-urlencode "text=caption here" \
      -d "access_token=$THREADS_ACCESS_TOKEN" | jq -r .id)
    ```
    
    Step 2 — publish the container. **Text posts publish immediately; for IMAGE /
    VIDEO / carousel containers you MUST wait ≥30s first** so Threads can
    fetch/process the upload — publishing too early fails or returns no id:
    
    ```bash
    sleep 30   # REQUIRED for IMAGE / VIDEO / carousel; skip for TEXT-only posts
    curl -sS -X POST "https://graph.threads.net/v1.0/$TID/threads_publish" \
      -d "creation_id=$CID" -d "access_token=$THREADS_ACCESS_TOKEN" | jq .
    # → {"id":"<THREADS_MEDIA_ID>"}
    ```
    
    If `threads_publish` returns no id, the container isn't ready yet — poll
    `GET /v1.0/<CID>?fields=status&access_token=$THREADS_ACCESS_TOKEN` until
    `status=FINISHED`, then retry publish.
    
    Get the public URL of the published post and hand it to the user:
    
    ```bash
    curl -sS "https://graph.threads.net/v1.0/<THREADS_MEDIA_ID>?fields=id,permalink&access_token=$THREADS_ACCESS_TOKEN" | jq -r .permalink
    ```
    
    ## Carousel (2–20 items)
    
    Create each child with `is_carousel_item=true`, then a `media_type=CAROUSEL`
    container with `children=<ID1>,<ID2>,...`, then publish the carousel id. Links:
    add `link_attachment=<URL>` (text-only posts, ≤5 links). Topic tag: `topic_tag=<TAG>`.
    
    ## List my recent posts
    
    ```bash
    curl -sS "https://graph.threads.net/v1.0/$TID/threads?fields=id,text,permalink,timestamp&limit=20&access_token=$THREADS_ACCESS_TOKEN" | jq '.data'
    ```
    
    ## Gotchas
    
    - **500-char limit**; emoji count as their UTF-8 byte length.
    - **Media must be a public URL** — Threads server-side cURLs `image_url`/`video_url`;
      local files won't work. Upload to a public host / cdn.acedata.cloud first.
    - **Wait ~30s before publishing media** containers (text publishes instantly); if
      `threads_publish` doesn't return an id, poll `GET /<container-id>?fields=status`.
    - **Rate limit:** 250 published posts per 24h per profile (a carousel counts as 1).
    - Threads tokens differ from Facebook/Instagram tokens — they come from the
      Threads OAuth flow on `graph.threads.net`, not `graph.facebook.com`.
    
    ## Record the output
    
    After you successfully publish and obtain the live permalink, call the built-in
    `publish_artifact` tool ONCE so the user can track it in **My Outputs**:
    
    ```
    publish_artifact(kind="message", channel="threads", title="<title>", url="<the REAL permalink>", status="delivered")
    ```
    
    Use the real returned URL — never fabricate one. Call it once per published item,
    only after delivery is confirmed; skip it (or use `status="failed"`) if publishing failed.
    See `_shared/artifacts.md`.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.