Skill: minupla/bluesky-api (version 1.0.3)

--- name: bluesky version: "1.0.3" description: "Read, search, post, and monitor Bluesky (AT Protocol) accounts" metadata: { "openclaw": { "emoji": "🦋" } } allowed-tools: ["exec", "web_fetch"] required-binaries: ["curl", "jq"] --- # Bluesky Skill Interact with Bluesky via the AT Protocol API. Supports public reads, search, authenticated posting, and profile monitoring. ## Configuration Credentials can come from openclaw config or environment variables: | Source | Handle | App Password | |--------|--------|--------------| | Config | `channels.bluesky.handle` | `channels.bluesky.appPassword` | | Env var | `BSKY_HANDLE` | `BSKY_APP_PASSWORD` | App passwords are created at: https://bsky.app/settings/app-passwords **Never use a main account password. Always use an app password.** --- ## 1. Read — Fetch Recent Posts from a Profile **No auth required.** Uses the public API. ### API Endpoint ``` GET https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=<handle>&limit=<n> ``` - `actor` — Bluesky handle (e.g. `alice.bsky.social`) or DID - `limit` — number of posts to return (1–100, default 50) ### curl Example ```bash curl -s "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=alice.bsky.social&limit=5" | jq '.feed[] | {text: .post.record.text, createdAt: .post.record.createdAt, uri: .post.uri}' ``` ### Helper Script ```bash ./scripts/bsky-read.sh alice.bsky.social 5 ``` ### Response Structure The response JSON has a `feed` array. Each entry contains: - `.post.record.text` — the post text - `.post.record.createdAt` — ISO 8601 timestamp - `.post.uri` — AT URI of the post - `.post.author.handle` — author handle - `.post.author.displayName` — author display name - `.post.likeCount`, `.post.repostCount`, `.post.replyCount` — engagement counts --- ## 2. Search — Find Posts by Keyword **No auth required.** Uses the public API. ### API Endpoint ``` GET https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q=<query>&limit=<n> ``` - `q` — search query (keywords, hashtags, phrases) - `limit` — number of results (1–100, default 25) ### curl Example ```bash curl -s "https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q=openclaw&limit=10" | jq '.posts[] | {text: .record.text, author: .author.handle, createdAt: .record.createdAt}' ``` ### Helper Script ```bash ./scripts/bsky-search.sh "openclaw" 10 ``` ### Response Structure The response JSON has a `posts` array. Each entry contains: - `.record.text` — the post text - `.record.createdAt` — ISO 8601 timestamp - `.author.handle` — author handle - `.author.displayName` — author display name - `.uri` — AT URI of the post --- ## 3. Post — Create a New Post **Requires auth.** Uses app password authentication. ### Step 1: Authenticate ``` POST https://bsky.social/xrpc/com.atproto.server.createSession Content-Type: application/json {"identifier": "<handle>", "password": "<app_password>"} ``` This returns a session with `accessJwt` and `did`. #### curl Example ```bash # Always use env vars — never interpolate credentials directly into shell strings SESSION=$(curl -s -X POST "https://bsky.social/xrpc/com.atproto.server.createSession" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg h "$BSKY_HANDLE" --arg p "$BSKY_APP_PASSWORD" '{identifier: $h, password: $p}')") ACCESS_TOKEN=$(echo "$SESSION" | jq -r '.accessJwt') DID=$(echo "$SESSION" | jq -r '.did') ``` ### Step 2: Create the Post ``` POST https://bsky.social/xrpc/com.atproto.repo.createRecord Authorization: Bearer <accessJwt> Content-Type: application/json { "repo": "<did>", "collection": "app.bsky.feed.post", "record": { "$type": "app.bsky.feed.post", "text": "<post text>", "createdAt": "<ISO 8601 timestamp>" } } ``` #### curl Example ```bash curl -s -X POST "https://bsky.social/xrpc/com.atproto.repo.createRecord" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d "{ \"repo\": \"${DID}\", \"collection\": \"app.bsky.feed.post\", \"record\": { \"\$type\": \"app.bsky.feed.post\", \"text\": \"Hello from OpenClaw!\", \"createdAt\": \"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)\" } }" ``` ### Helper Script ```bash # Pass app password via env var — never as a CLI argument (visible in ps/shell history) BSKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx ./scripts/bsky-post.sh alice.bsky.social "Hello from OpenClaw!" ``` ### Post Length Limit Bluesky posts have a 300-character limit (grapheme count). Check length before posting. --- ## 4. Monitor — Check for New Posts Since Last Check Use the read endpoint with a timestamp comparison to detect new posts. This is useful for heartbeat monitoring. ### Approach 1. Fetch recent posts from the target profile. 2. Compare `.post.record.createdAt` against the last-known timestamp. 3. Any post with a `createdAt` newer than the stored timestamp is new. ### curl Example ```bash # Fetch the 10 most recent posts FEED=$(curl -s "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=alice.bsky.social&limit=10") # Filter posts newer than a given timestamp SINCE="2026-03-24T00:00:00.000Z" echo "$FEED" | jq --arg since "$SINCE" '.feed[] | select(.post.record.createdAt > $since) | {text: .post.record.text, createdAt: .post.record.createdAt}' ``` ### Monitoring Loop Pattern For heartbeat use, store the latest seen timestamp and compare on each check: ```bash # Use a user-owned state dir, not world-readable /tmp LAST_SEEN_FILE="${XDG_STATE_HOME:-$HOME/.local/state}/bsky-monitor-${HANDLE}.txt" mkdir -p "$(dirname "$LAST_SEEN_FILE")" HANDLE="alice.bsky.social" # Read last seen timestamp (or default to 24h ago) if [ -f "$LAST_SEEN_FILE" ]; then SINCE=$(cat "$LAST_SEEN_FILE") else SINCE=$(date -u -v-24H +%Y-%m-%dT%H:%M:%S.000Z 2>/dev/null || date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%S.000Z) fi FEED=$(curl -s "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=${HANDLE}&limit=20") NEW_POSTS=$(echo "$FEED" | jq --arg since "$SINCE" '[.feed[] | select(.post.record.createdAt > $since)]') COUNT=$(echo "$NEW_POSTS" | jq 'length') if [ "$COUNT" -gt 0 ]; then echo "Found $COUNT new post(s) from $HANDLE since $SINCE" echo "$NEW_POSTS" | jq '.[] | {text: .post.record.text, createdAt: .post.record.createdAt}' # Update last seen to the most recent post timestamp echo "$NEW_POSTS" | jq -r '.[0].post.record.createdAt' > "$LAST_SEEN_FILE" else echo "No new posts from $HANDLE since $SINCE" fi ``` --- ## Error Handling | HTTP Status | Meaning | Action | |-------------|---------|--------| | 200 | Success | Parse response | | 400 | Bad request | Check parameters | | 401 | Unauthorized | Re-authenticate (token may be expired) | | 404 | Not found | Check handle/DID exists | | 429 | Rate limited | Back off and retry after delay | ### Auth Token Expiry Access tokens expire. If you get a 401, re-authenticate by calling `createSession` again. Do not cache tokens for more than a few minutes. --- ## Quick Reference | Operation | Auth? | Script | |-----------|-------|--------| | Read profile feed | No | `./scripts/bsky-read.sh <handle> [limit]` | | Search posts | No | `./scripts/bsky-search.sh <query> [limit]` | | Create post | Yes | `./scripts/bsky-post.sh <handle> <app_password> <text>` | | Monitor new posts | No | Use read + timestamp filter (see section 4) |

path: scripts/bsky-post.sh
content: #!/usr/bin/env bash
set -euo pipefail

# Post to Bluesky via AT Protocol (requires app password)
# Usage: bsky-post.sh <handle> <app_password> <text>

HANDLE="${1:-${BSKY_HANDLE:-}}"
# Prefer env var for app password — never pass secrets as CLI args (visible in ps/history)
APP_PASSWORD="${BSKY_APP_PASSWORD:-}"
TEXT="${2:-}"

if [ -z "$HANDLE" ] || [ -z "$APP_PASSWORD" ] || [ -z "$TEXT" ]; then
  echo "Usage: BSKY_APP_PASSWORD=<password> bsky-post.sh <handle> <text>" >&2
  echo "  handle           — Bluesky handle (e.g. alice.bsky.social), or set BSKY_HANDLE" >&2
  echo "  text             — Post text (max 300 characters)" >&2
  echo "  BSKY_APP_PASSWORD — App password (env var, never pass as CLI arg)" >&2
  exit 1
fi

# Check post length using grapheme count (Bluesky's actual limit is 300 graphemes)
# Use Python if available for accurate Unicode grapheme counting, fall back to char count
if command -v python3 &>/dev/null; then
  GRAPHEME_COUNT=$(python3 -c "
import unicodedata, sys
text = sys.stdin.read()
# NFC normalize then count (approximation; full grapheme cluster counting needs 'grapheme' lib)
normalized = unicodedata.normalize('NFC', text)
print(len(normalized))
" <<< "$TEXT")
else
  GRAPHEME_COUNT=${#TEXT}
fi

if [ "$GRAPHEME_COUNT" -gt 300 ]; then
  echo "Error: post text is ${GRAPHEME_COUNT} graphemes (max 300)" >&2
  exit 1
fi

# Step 1: Authenticate
SESSION=$(curl -sf -X POST "https://bsky.social/xrpc/com.atproto.server.createSession" \
  -H "Content-Type: application/json" \
  -d "{\"identifier\": $(printf '%s' "$HANDLE" | jq -Rs .), \"password\": $(printf '%s' "$APP_PASSWORD" | jq -Rs .)}") || {
  echo "Error: authentication failed for '${HANDLE}'" >&2
  exit 1
}

ACCESS_TOKEN=$(echo "$SESSION" | jq -r '.accessJwt')
DID=$(echo "$SESSION" | jq -r '.did')

if [ "$ACCESS_TOKEN" = "null" ] || [ -z "$ACCESS_TOKEN" ]; then
  # Never print SESSION JSON — it contains accessJwt and DID
  ERROR_MSG=$(echo "$SESSION" | jq -r '.error // "unknown error"' 2>/dev/null || echo "unknown error")
  echo "Error: authentication failed — ${ERROR_MSG}" >&2
  exit 1
fi

# Step 2: Create the post
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)

RESULT=$(curl -sf -X POST "https://bsky.social/xrpc/com.atproto.repo.createRecord" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"repo\": $(printf '%s' "$DID" | jq -Rs .),
    \"collection\": \"app.bsky.feed.post\",
    \"record\": {
      \"\$type\": \"app.bsky.feed.post\",
      \"text\": $(printf '%s' "$TEXT" | jq -Rs .),
      \"createdAt\": \"${TIMESTAMP}\"
    }
  }") || {
  echo "Error: failed to create post" >&2
  exit 1
}

echo "Post created successfully!"
echo "$RESULT" | jq '{uri: .uri, cid: .cid}'


path: scripts/bsky-read.sh
content: #!/usr/bin/env bash
set -euo pipefail

# Fetch recent posts from a Bluesky profile (public, no auth needed)
# Usage: bsky-read.sh <handle> [limit]

HANDLE="${1:-}"
LIMIT="${2:-10}"

if [ -z "$HANDLE" ]; then
  echo "Usage: bsky-read.sh <handle> [limit]" >&2
  echo "  handle  — Bluesky handle (e.g. alice.bsky.social)" >&2
  echo "  limit   — number of posts to fetch (default: 10, max: 100)" >&2
  exit 1
fi

# Validate limit is a positive integer to prevent URL injection
if ! [[ "$LIMIT" =~ ^[0-9]+$ ]] || [ "$LIMIT" -lt 1 ] || [ "$LIMIT" -gt 100 ]; then
  echo "Error: limit must be an integer between 1 and 100" >&2
  exit 1
fi

API_URL="https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=$(printf '%s' "$HANDLE" | jq -sRr @uri)&limit=${LIMIT}"

RESPONSE=$(curl -sf "$API_URL") || {
  echo "Error: failed to fetch feed for '${HANDLE}'" >&2
  exit 1
}

echo "$RESPONSE" | jq '.feed[] | {
  text: .post.record.text,
  createdAt: .post.record.createdAt,
  uri: .post.uri,
  author: .post.author.handle,
  likes: .post.likeCount,
  reposts: .post.repostCount,
  replies: .post.replyCount
}'


path: scripts/bsky-search.sh
content: #!/usr/bin/env bash
set -euo pipefail

# Search Bluesky posts by keyword (public, no auth needed)
# Usage: bsky-search.sh <query> [limit]

QUERY="${1:-}"
LIMIT="${2:-25}"

if [ -z "$QUERY" ]; then
  echo "Usage: bsky-search.sh <query> [limit]" >&2
  echo "  query  — search terms (keywords, hashtags, phrases)" >&2
  echo "  limit  — number of results (default: 25, max: 100)" >&2
  exit 1
fi

# Validate limit is a positive integer to prevent URL injection
if ! [[ "$LIMIT" =~ ^[0-9]+$ ]] || [ "$LIMIT" -lt 1 ] || [ "$LIMIT" -gt 100 ]; then
  echo "Error: limit must be an integer between 1 and 100" >&2
  exit 1
fi

API_URL="https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q=$(printf '%s' "$QUERY" | jq -sRr @uri)&limit=${LIMIT}"

RESPONSE=$(curl -sf "$API_URL") || {
  echo "Error: search failed for query '${QUERY}'" >&2
  exit 1
}

echo "$RESPONSE" | jq '.posts[] | {
  text: .record.text,
  author: .author.handle,
  createdAt: .record.createdAt,
  uri: .uri
}'


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)