Claude GitHub Copilot Skill

facebook

Publish text, link or photo posts to your Facebook Page via the Facebook Pages API, and read your Page's recent posts. Use when the user wants to post to their Facebook Page, share a link, publish a photo, or review their own Page posts. Auth uses a Page access token (BYOC). 支持 F

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

Install

skills CLI npx skills add https://github.com/AceDataCloud/Skills/tree/main/skills/facebook
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 Facebook Graph API (graph.facebook.com) with curl + jq. The connector injects $FACEBOOK_ACCESS_TOKEN (a Page access token with pages_manage_posts + pages_read_engagement) and optionally $FACEBOOK_PAGE_ID. Never echo them.

The Graph API publishes only to a Facebook Page you manage — it cannot post to a personal profile timeline.

Resolve the Page id

If $FACEBOOK_PAGE_ID is set, use it. Otherwise derive it from the token — try the Page-token path first (/me is the Page), then fall back to the user-token path (/me/accounts → first managed Page), so either token type the connector accepts resolves cleanly:

if [ -n "$FACEBOOK_PAGE_ID" ]; then
  PAGE="$FACEBOOK_PAGE_ID"
else
  # Page access token: /me IS the Page
  PAGE=$(curl -sS "https://graph.facebook.com/v21.0/me?fields=id,name&access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r 'select(.name).id // empty')
  if [ -z "$PAGE" ]; then
    # User access token: list the managed Pages, take the first
    PAGE=$(curl -sS "https://graph.facebook.com/v21.0/me/accounts?access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r '.data[0].id // empty')
  fi
fi
echo "page_id=$PAGE"

Errors are JSON with error.message / error.code — show them verbatim. 401 / OAuthException → token expired or missing scope; a null PAGE → the token isn't a Page token / manages no Page (see Gotchas). Reconnect if needed.

If the user token path is used, /me/accounts also returns a per-Page access_token in .data[0].access_token. Prefer that Page token for the publish call when the injected token is a user token; a Page's own token is what pages_manage_posts actually authorizes.

Publish a text or link post

Confirm the message (and link, if any) with the user first. Post to /{page-id}/feed:

# Text-only post
curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/feed" \
  --data-urlencode "message=One endpoint → posters, cards, mockups. #AI #API" \
  -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
# → {"id":"<PAGE_ID>_<POST_ID>"}

# Link post — Facebook renders a link preview card from the URL
curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/feed" \
  --data-urlencode "message=Read our new guide 👇" \
  -d "link=https://acedata.cloud/blog/xxxx" \
  -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .

Publish a photo post

Post to /{page-id}/photos with a public image URL (Facebook server-side fetches it); caption is the post text:

curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/photos" \
  -d "url=https://cdn.acedata.cloud/xxxx.jpg" \
  --data-urlencode "caption=One endpoint → posters, cards, mockups. #AI #API" \
  -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
# → {"id":"<PHOTO_ID>","post_id":"<PAGE_ID>_<POST_ID>"}

To attach multiple photos to one post: upload each with published=false to get its media id, then create the feed post with attached_media[0]={"media_fbid":"<ID1>"} … for each.

Get the post permalink

Use the returned post_id (or id) to fetch the live URL to hand back:

curl -sS "https://graph.facebook.com/v21.0/<PAGE_ID>_<POST_ID>?fields=permalink_url&access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r .permalink_url

Read recent Page posts

curl -sS "https://graph.facebook.com/v21.0/$PAGE/posts?fields=id,message,created_time,permalink_url&limit=10&access_token=$FACEBOOK_ACCESS_TOKEN" | jq .

Gotchas

  • Pages only, not profiles — the Graph API cannot publish to a personal timeline. If the user asks to post to their profile, explain this limitation.
  • Page token, not user token — publishing needs a Page access token with pages_manage_posts. If you only have a user token, resolve the Page token via /me/accounts (see above). A (#200) permissions error means the token lacks pages_manage_posts or the user isn't an admin of the Page.
  • Photo URL must be public on a server Facebook can reach; local files won't work. Host on cdn.acedata.cloud first.
  • Page Publishing Authorization (PPA): some Pages must complete PPA before API publishing works — surface the API error verbatim if it mentions PPA.
  • Token expiry: a Page token derived from a short-lived user token expires fast. If posting 401s soon after connecting, the user needs a long-lived Page token — surface the OAuthException verbatim and suggest reconnecting.
  • API version: keep the vXX.0 path current if you hit a version/deprecation error.

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="post", channel="facebook", 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.8 KB
    ---
    name: facebook
    description: Publish text, link or photo posts to your Facebook Page via the Facebook Pages API, and read your Page's recent posts. Use when the user wants to post to their Facebook Page, share a link, publish a photo, or review their own Page posts. Auth uses a Page access token (BYOC). 支持 Facebook 主页文本 / 链接 / 图片发帖。
    when_to_use: |
      Trigger when the user wants to publish a post (text, link or photo) to their
      Facebook Page, cross-post an article, or review their own recent Page posts.
      Publishing posts as their real Page — confirm the message + any link/photo
      first. This posts to a Facebook Page, not a personal profile (the Graph API
      cannot post to personal timelines).
    connections: [facebook]
    allowed_tools: [Bash]
    license: Apache-2.0
    metadata:
      author: acedatacloud
      version: "1.0"
    ---
    
    Call the **Facebook Graph API** (`graph.facebook.com`) with `curl + jq`. The
    connector injects `$FACEBOOK_ACCESS_TOKEN` (a **Page** access token with
    `pages_manage_posts` + `pages_read_engagement`) and optionally
    `$FACEBOOK_PAGE_ID`. Never echo them.
    
    The Graph API publishes only to a **Facebook Page** you manage — it cannot post
    to a personal profile timeline.
    
    ### Resolve the Page id
    
    If `$FACEBOOK_PAGE_ID` is set, use it. Otherwise derive it from the token — try
    the **Page-token** path first (`/me` is the Page), then fall back to the
    **user-token** path (`/me/accounts` → first managed Page), so either token type
    the connector accepts resolves cleanly:
    
    ```bash
    if [ -n "$FACEBOOK_PAGE_ID" ]; then
      PAGE="$FACEBOOK_PAGE_ID"
    else
      # Page access token: /me IS the Page
      PAGE=$(curl -sS "https://graph.facebook.com/v21.0/me?fields=id,name&access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r 'select(.name).id // empty')
      if [ -z "$PAGE" ]; then
        # User access token: list the managed Pages, take the first
        PAGE=$(curl -sS "https://graph.facebook.com/v21.0/me/accounts?access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r '.data[0].id // empty')
      fi
    fi
    echo "page_id=$PAGE"
    ```
    
    Errors are JSON with `error.message` / `error.code` — show them verbatim.
    `401` / `OAuthException` → token expired or missing scope; a null `PAGE` → the
    token isn't a Page token / manages no Page (see Gotchas). Reconnect if needed.
    
    > If the user token path is used, `/me/accounts` also returns a per-Page
    > `access_token` in `.data[0].access_token`. Prefer that Page token for the
    > publish call when the injected token is a user token; a Page's own token is
    > what `pages_manage_posts` actually authorizes.
    
    ## Publish a text or link post
    
    **Confirm the message (and link, if any) with the user first.** Post to
    `/{page-id}/feed`:
    
    ```bash
    # Text-only post
    curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/feed" \
      --data-urlencode "message=One endpoint → posters, cards, mockups. #AI #API" \
      -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
    # → {"id":"<PAGE_ID>_<POST_ID>"}
    
    # Link post — Facebook renders a link preview card from the URL
    curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/feed" \
      --data-urlencode "message=Read our new guide 👇" \
      -d "link=https://acedata.cloud/blog/xxxx" \
      -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
    ```
    
    ## Publish a photo post
    
    Post to `/{page-id}/photos` with a **public image URL** (Facebook server-side
    fetches it); `caption` is the post text:
    
    ```bash
    curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/photos" \
      -d "url=https://cdn.acedata.cloud/xxxx.jpg" \
      --data-urlencode "caption=One endpoint → posters, cards, mockups. #AI #API" \
      -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
    # → {"id":"<PHOTO_ID>","post_id":"<PAGE_ID>_<POST_ID>"}
    ```
    
    To attach **multiple photos** to one post: upload each with `published=false` to
    get its media id, then create the feed post with
    `attached_media[0]={"media_fbid":"<ID1>"}` … for each.
    
    ## Get the post permalink
    
    Use the returned `post_id` (or `id`) to fetch the live URL to hand back:
    
    ```bash
    curl -sS "https://graph.facebook.com/v21.0/<PAGE_ID>_<POST_ID>?fields=permalink_url&access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r .permalink_url
    ```
    
    ## Read recent Page posts
    
    ```bash
    curl -sS "https://graph.facebook.com/v21.0/$PAGE/posts?fields=id,message,created_time,permalink_url&limit=10&access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
    ```
    
    ## Gotchas
    
    - **Pages only, not profiles** — the Graph API cannot publish to a personal
      timeline. If the user asks to post to their profile, explain this limitation.
    - **Page token, not user token** — publishing needs a Page access token with
      `pages_manage_posts`. If you only have a user token, resolve the Page token via
      `/me/accounts` (see above). A `(#200)` permissions error means the token lacks
      `pages_manage_posts` or the user isn't an admin of the Page.
    - **Photo URL must be public** on a server Facebook can reach; local files won't
      work. Host on cdn.acedata.cloud first.
    - **Page Publishing Authorization (PPA):** some Pages must complete PPA before API
      publishing works — surface the API error verbatim if it mentions PPA.
    - **Token expiry:** a Page token derived from a short-lived user token expires
      fast. If posting 401s soon after connecting, the user needs a long-lived Page
      token — surface the `OAuthException` verbatim and suggest reconnecting.
    - API version: keep the `vXX.0` path current if you hit a version/deprecation error.
    
    ## 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="post", channel="facebook", 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.