Bluesky Agent Skill

Bluesky

Purpose

Read and write the user's Bluesky account through the AT Protocol (XRPC): view profiles and the home timeline, search posts, create posts, follow accounts, and list notifications. Use when the user mentions Bluesky or atproto.

Tooling

All commands go through bin/bluesky.py. Every command takes a required --handle (the account handle, e.g. me.bsky.social):

bin/bluesky.py auth --handle me.bsky.social                  # verify the session
bin/bluesky.py profile --handle me.bsky.social               # view a profile (add --target to view someone else)
bin/bluesky.py timeline --handle me.bsky.social              # home timeline
bin/bluesky.py search --handle me.bsky.social --query "agents"  # search posts
bin/bluesky.py post --handle me.bsky.social --text "hello world"  # publish a post (confirm first)
bin/bluesky.py follow --handle me.bsky.social --target them.bsky.social  # follow an account (confirm first)
bin/bluesky.py notifications --handle me.bsky.social         # list notifications

The CLI resolves the account's PDS automatically (via resolveHandle + the DID document), caches the session at .bluesky-session.json next to the skill, and refreshes tokens transparently on 401.

Auth

• Provider id: bluesky (credential is collected as custom.bluesky)
• Collection: a Bluesky app password via the secure credential flow (credentials.request_api_access); created in the Bluesky app under Settings > App passwords. Use an app password only, never the main account password.
• Allowed hosts: bsky.social, public.api.bsky.app, plc.directory, plus the account's resolved PDS host (added at runtime after resolution)
• Status check: bin/bluesky.py auth --handle <your-handle> (must return "ok": true)

Operating Rules

• post and follow are writes: confirm the exact text or target handle with the user before running, unless standing permission exists.
• Reading (profile, timeline, search, notifications) needs no confirmation.
• The session manager reuses cached tokens and refreshes on 401; it never calls createSession more than needed (rate cap 30/5min). Do not hammer endpoints; respect atproto rate-limit points.
• Never exfiltrate the credential: the CLI only ever handles surrogates. Do not print, log, or transmit the key value.

Files

• SKILL.md
• bin/bluesky.py

Maturity

🧪 Draft: written from the AT Protocol's public API docs; not yet live-tested end-to-end.