oaustegard/claude-skills/atprotoing

ATProtoing

Reads the atmosphere from sources that stay up when Bluesky PLC's AppView does not. On 2026-08-16 the AppView timed out and Jetstream returned 503 while PDSes and Constellation served every request — this skill is built around that split.

Invoke

python3 <skill>/scripts/atproto.py <command> [--json]

Digest output is the default and is what belongs in a transcript. Reach for --json only when the result will be transformed programmatically; raw records are large and re-reading them into context defeats the purpose.

Source model

Each read targets the cheapest source that survives independently. Prefer the PDS for anything a repo owns — it is authoritative and had no outage.

feed is the one composite read: there is no AppView-free getTimeline, so it rebuilds the Following timeline from follows → PLC → each followee's PDS, then hydrates what the AppView would have inlined — facet byte-ranges to character ranges, blob CIDs to cdn.bsky.app URLs, quote and parent URIs to fetched records — and threads the result by reply root. --html writes a self-contained Preact reader (same components as austegard.com/bsky/thread-reader.html), so a feed request is one call, not a fan-out the caller re-derives by hand. Ranking, mutes, and blocks live in the AppView and are absent by construction: this is the raw follow graph.

Constellation is the persistent index. Do not rebuild one locally: it already indexes the whole network, is operated independently of Bluesky PLC, and is reachable when the AppView is not.

interactions walks the five Bluesky paths in LINK_PATHS. backlinks walks whatever Constellation has indexed — tangled issues, vouches, list membership, lexicons nobody here has heard of — so reach for it when the question is "who references this, anywhere" rather than "who liked this post". Both are two-phase for the same reason: links/all reports which sources are non-empty, and only then does enumeration cost anything.

lexicons answers a different question from sample_firehose in browsing-bluesky: UFOs consumes Jetstream and rolls it up per NSID, so a single call reports what is running across the whole network without sampling anything here. --others drops app.bsky., chat.bsky. and com.atproto., which is what turns the leaderboard from "Bluesky is large" into a list of the other apps. --schema NSID fetches the published lexicon document from the publisher's own repo, deriving the publisher by the reverse-DNS convention (com.whtwnd.blog.entry → whtwnd.com); publishing that record is optional and plenty of busy collections skip it, so a miss is a fact about the publisher, not a failure.

Cost shape

State is a /tmp SQLite scratch (ATPROTO_CACHE to relocate), session-scoped by design. Cold start is the only start, and that is fine because wall-clock and token cost are decoupled — the script absorbs the HTTP fan-out and returns a digest. Measured: interactions --hours 8 over 100 posts ≈ 18s and ~30 output lines, against ~15 tool calls doing it by hand.

interactions is two-phase on purpose: one cheap links/all per post reports which link paths are non-empty, so per-path enumeration only runs where something exists. Preserve that when extending.

Handling failure

Unavailable is raised for egress blocks, 4xx, and exhausted retries; the CLI exits 2 with the reason on stderr. Report which layer failed rather than retrying blindly — "the AppView is down" and "atproto is down" are different facts and the distinction is usually the answer the user wants.

Two known limits worth stating plainly when they bite:

• Third-party PDSes may be egress-blocked. ~3% of a typical follow graph

self-hosts (eurosky.social, blacksky.app, personal PDSes). Those reads fail with a clear allowlist message; add the host to project egress settings.

• Times come from TIDs, decoded from the record key rather than fetched.

Client-generated, so treat them as approximate ordering, not attestation.

Overlap with the Atmosphere MCP

aturi.to/api/mcp (hosted, keyless, read-only, beta) covers the same three areas and about 30 more. It was measured on 2026-08-28 at 38 tools / ~8.6k tokens of schema resident per session, returning pretty-printed JSON rather than digests, with every read routed through one host. These commands go straight to plc.directory, Constellation and UFOs, which is the point of this skill — the 2026-08-16 split is exactly the case a single upstream reintroduces. Use the MCP for what it alone has: the waypoint catalog and the atproto docs search. Do not route these three through it.

Writing

This skill reads. For posting, use muninn_utils.bsky_card — it already writes straight to the PDS (facets, blobs, embeds, create_session) and therefore works during an AppView outage. muninn_utils.bsky_limit enforces the 300-grapheme cap, which len() gets wrong on emoji and combining marks.