From 92ba4d97ba4a9059fde956ab9528143f825b44e8 Mon Sep 17 00:00:00 2001 From: Patrick Singletary Date: Mon, 17 Aug 2026 22:04:22 -0400 Subject: [PATCH] =?UTF-8?q?skills:=20red-team=20doer=20pass=20=E2=80=94=20?= =?UTF-8?q?fix=20SKILL-01..07=20(verified=20verify-steps,=20remove=20stale?= =?UTF-8?q?=20planned=20markers,=20portability,=20replay-layer=20notes,=20?= =?UTF-8?q?snapshot=20banners)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/SKILLS-INDEX.md | 4 ++ .../atproto-ecosystem-map/SKILL.md | 46 +++++++++++-------- .../atproto-feeds-algorithms/SKILL.md | 3 ++ .../atproto-identity-deep/SKILL.md | 3 ++ .../atproto-jetstream-providers/SKILL.md | 10 +++- .../atproto-lexicon-registry/SKILL.md | 5 +- .../atproto-moderation-tools/SKILL.md | 6 ++- .../atproto-pds-ops/SKILL.md | 8 +++- .../atproto-relays-firehose/SKILL.md | 14 ++++-- .../atproto-security-landscape/SKILL.md | 3 ++ .../atproto-tools-catalog/SKILL.md | 10 ++-- 11 files changed, 79 insertions(+), 33 deletions(-) diff --git a/skills/SKILLS-INDEX.md b/skills/SKILLS-INDEX.md index 096d837..beecd0d 100644 --- a/skills/SKILLS-INDEX.md +++ b/skills/SKILLS-INDEX.md @@ -58,6 +58,10 @@ first if you're not sure which skill you need — it routes every task. - Skills live in `software-development/`; symlinked into `~/.hermes/skills/` (Hermes) and `~/.agents/skills/` (Claude Code) so any agent can load them. +- Re-linking on a new machine (symlinks are machine state, not in git): for each + skill run `ln -sfn ~/dev/_shared/skills/software-development/ ~/.hermes/skills/software-development/` + and `ln -sfn ~/dev/_shared/skills/software-development/ ~/.agents/skills/`. + See the multi-machine-hermes-setup skill for the full migration flow. - All ecosystem facts date from the digest snapshot (2026-08-17); live infra registry facts should be re-verified via firehose.directory / pds.directory / plc.directory before production use. diff --git a/skills/software-development/atproto-ecosystem-map/SKILL.md b/skills/software-development/atproto-ecosystem-map/SKILL.md index f5f41c4..e648d7b 100644 --- a/skills/software-development/atproto-ecosystem-map/SKILL.md +++ b/skills/software-development/atproto-ecosystem-map/SKILL.md @@ -15,8 +15,11 @@ metadata: One-page orientation to the AT Protocol network: what each service type is, who runs the notable public instances, and which skill to load for deeper work. Distilled from the AT://links and DEEP AT://magic Semble collections (897 URLs, digested 2026-08-17). -Source data: `~/dev/_shared/docs/atproto-digest/` (catalog.md, classification.json, -notes/). +Source data: the `docs/atproto-digest/` directory of this repo (on this machine: +`~/dev/_shared/docs/atproto-digest/`) — catalog.md, classification.json, notes/. + +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. ## When to Use @@ -64,13 +67,14 @@ Key mental model: regional relays. Replay window 72h. `wss://.firehose.network/xrpc/com.atproto.sync.subscribeRepos`. Per-relay pages offer: check PDS status, request PDS crawl, DID/handle status. - **bsky.network** (+ relay1.us-west/east.bsky.network): Bluesky's own relay, - largest (5,942 PDSes, ~23M accounts). + largest (5,942 PDSes, ~23M accounts — snapshot 2026-08). - **fire.hose.cam**: relay.fire.hose.cam, relay3.fr.hose.cam. - **atproto.africa**: runs **rsky-relay** codebase (github.com/blacksky-algorithms/rsky) — a community relay implementation, not the official one. - Others: relay.feeds.blue, relay1.eurosky.network, zlay.waow.tech, relay.waow.tech, relay.upcloud.world. (relay.xero.systems was unreachable at digest time.) -- **Index/status:** firehose.directory — relay index (16 relays, ~6,175 PDSes). +- **Index/status:** firehose.directory — relay index (16 relays, ~6,175 PDSes — + snapshot 2026-08). ### Jetstreams (JSON streaming) - **firehose.stream** (vayumandala): sfo (relay: northamerica, replay 72h), @@ -80,16 +84,16 @@ Key mental model: - Edge cache: **slingshot.firehose.stream** — caches records from Jetstream for fast lookups. Notifications firehose: **spacedust.firehose.stream** — watch any handle/DID/AT-URI's notifications. -- Full provider detail: load `atproto-jetstream-providers` (planned, Phase 3). +- Full provider detail: load `atproto-jetstream-providers`. ### PDS hosting / ops -- **pds.directory** — index of all public PDSes (6,175; hostname, version, users, - open registration, relay status). +- **pds.directory** — index of all public PDSes (6,175 at digest time; hostname, + version, users, open registration, relay status). - **protobase.at** — managed multi-PDS hosting (provision in minutes, quota views). - **pds.tokyonight.city** (Tranquil PDS, small private), **altq.net** (self-hosted PDS, code = bluesky-social/pds), **pds.club** (unreachable at digest time). - **atpairport.com** (Airport) — PDS migration + PLC key recovery assistance. -- Deeper ops knowledge: load `atproto-pds-ops` (planned, Phase 3). +- Deeper ops knowledge: load `atproto-pds-ops`. ### Identity / DID - **plc.directory** — canonical DID:PLC registry. **didplc.directory** — community @@ -97,13 +101,13 @@ Key mental model: - did:web creation guides: whtwnd.com "Creating a did:web atproto account using goat" (bnewbold), blog.smokesignal.events did-method-web identity post. - Passkeys as PLC rotation keys: plc-passkey.wisp.place. -- Deeper: load `atproto-identity-deep` (planned, Phase 4); for DID:WEB serving +- Deeper: load `atproto-identity-deep`; for DID:WEB serving patterns see the atproto-development skill. ### Lexicon registries - **lexicon.garden** (browser), **lexicon.store** (schema registry), **lexicons.bio**, **rite.mino.mobi/lexicon** (word-level archive analysis), **at-store** lexicons. -- Deeper: load `atproto-lexicon-registry` (planned, Phase 4). +- Deeper: load `atproto-lexicon-registry`. ### Content/community (misc) - Firehose games (firehose.games, tic-tac-toe on ATProto), wisp.place static hosting, @@ -121,14 +125,14 @@ Key mental model: | Bluesky post embeds in web apps | `bluesky-post-embeds` | | Semble (Cosmik) API | `semble-cosmik` | | Relays + firehose in depth | `atproto-relays-firehose` | -| Jetstream providers, edge caches, notifications firehose | `atproto-jetstream-providers` (planned) | -| PDS provisioning/ops/migration | `atproto-pds-ops` (planned) | -| Lexicon authoring/discovery | `atproto-lexicon-registry` (planned) | -| did:web via goat, PLC replica, passkey rotation | `atproto-identity-deep` (planned) | -| Feed generators, engagement graphs | `atproto-feeds-algorithms` (planned) | -| Ozone, labelers, moderation | `atproto-moderation-tools` (planned) | -| Scam/phish/security landscape | `atproto-security-landscape` (planned) | -| Client/viewer/utility catalog | `atproto-tools-catalog` (planned) | +| Jetstream providers, edge caches, notifications firehose | `atproto-jetstream-providers` | +| PDS provisioning/ops/migration | `atproto-pds-ops` | +| Lexicon authoring/discovery | `atproto-lexicon-registry` | +| did:web via goat, PLC replica, passkey rotation | `atproto-identity-deep` | +| Feed generators, engagement graphs | `atproto-feeds-algorithms` | +| Ozone, labelers, moderation | `atproto-moderation-tools` | +| Scam/phish/security landscape | `atproto-security-landscape` | +| Client/viewer/utility catalog | `atproto-tools-catalog` | ## Pitfalls @@ -147,8 +151,10 @@ Key mental model: ## Verify -- `curl -s https://firehose.directory` shows live relay statuses. -- `curl -s https://pds.directory` shows current PDS count (6,175 at digest time). +- `curl -s https://bsky.network/xrpc/_health` returns `{"status":"ok"}` (relay health). +- `curl -s -o /dev/null -w '%{http_code}' https://europe.firehose.network/xrpc/com.atproto.sync.subscribeRepos` + returns 400 (endpoint live; a 404 means the relay is gone). firehose.directory / + pds.directory are JS apps — open in a browser for live counts. - `curl -s https://plc.directory/` resolves any DID to its document. - A websocket client connecting to `wss://sfo.firehose.stream/tap` receives JSON frames within seconds (no auth needed for public streams). diff --git a/skills/software-development/atproto-feeds-algorithms/SKILL.md b/skills/software-development/atproto-feeds-algorithms/SKILL.md index f0dcd79..7c51466 100644 --- a/skills/software-development/atproto-feeds-algorithms/SKILL.md +++ b/skills/software-development/atproto-feeds-algorithms/SKILL.md @@ -16,6 +16,9 @@ How custom feeds work on AT Protocol, the tooling to build them, notable algorit designs, and where the ecosystem discovers feeds. Distilled from the AT://links and DEEP AT://magic Semble collections (2026-08-17). +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. + ## When to Use - You are building or running a custom feed (feed generator) for Bluesky/ATProto. diff --git a/skills/software-development/atproto-identity-deep/SKILL.md b/skills/software-development/atproto-identity-deep/SKILL.md index d120774..dcfc7b6 100644 --- a/skills/software-development/atproto-identity-deep/SKILL.md +++ b/skills/software-development/atproto-identity-deep/SKILL.md @@ -17,6 +17,9 @@ operating against PLC (directory, mirrors, ops, audit), and passkeys as PLC rotation keys. Distilled from the AT://links and DEEP AT://magic Semble collections (2026-08-17). For basic DID:WEB serving patterns see `atproto-development`. +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. + ## When to Use - You are creating a did:web ATProto account (self-hosted, non-Bluesky path). diff --git a/skills/software-development/atproto-jetstream-providers/SKILL.md b/skills/software-development/atproto-jetstream-providers/SKILL.md index fac375a..6aa437f 100644 --- a/skills/software-development/atproto-jetstream-providers/SKILL.md +++ b/skills/software-development/atproto-jetstream-providers/SKILL.md @@ -18,6 +18,9 @@ public provider network, the v2 wire protocol, and the supporting services (edge caches, notifications firehose). Distilled from the AT://links and DEEP AT://magic Semble collections (2026-08-17); re-verify live status before relying on any host. +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. + ## When to Use - You want real-time ATProto events as plain JSON without decoding DAG-CBOR/CAR. @@ -43,6 +46,9 @@ Semble collections (2026-08-17); re-verify live status before relying on any hos best-effort, falls back to uncompressed if the dictionary can't be fetched. - **Verifiability**: jetstream carries NO repo signatures/MST proofs — data cannot be cryptographically verified. Use the firehose when verification matters. +- **Instance replay != relay replay**: the per-provider replay windows in the table + below are the jetstream instance's buffer, NOT the upstream relay's (see + atproto-relays-firehose). Persist cursors per provider. ## Public providers (status as of 2026-08) @@ -114,8 +120,8 @@ client.start(on_message) - `wscat -c wss://sfo.firehose.stream/tap` (or any ws client) receives JSON frames within seconds, no auth. -- `curl -s https://slingshot.firehose.stream` — edge cache lookup works. -- `curl -s https://spacedust.firehose.stream` — notification watcher page loads. +- slingshot.firehose.stream and spacedust.firehose.stream are JS apps — open in a + browser and run a lookup/watch (curl returns only the HTML shell). - Python: `JetstreamClient().start(print)` prints parsed events immediately. ## Related skills diff --git a/skills/software-development/atproto-lexicon-registry/SKILL.md b/skills/software-development/atproto-lexicon-registry/SKILL.md index 2812957..259e345 100644 --- a/skills/software-development/atproto-lexicon-registry/SKILL.md +++ b/skills/software-development/atproto-lexicon-registry/SKILL.md @@ -16,6 +16,9 @@ How to discover, understand, author, and publish ATProto lexicon schemas, and wh the ecosystem's registries live. Distilled from the AT://links and DEEP AT://magic Semble collections (2026-08-17). +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. + ## When to Use - You need to find an existing lexicon before inventing a record type. @@ -103,4 +106,4 @@ Semble collections (2026-08-17). - `atproto-ecosystem-map` — network roles; lexicon registries in the registry table. - `atproto-python` / `atproto-development` — SDK model generation from lexicons, creating records. -- `atproto-tools-catalog` (planned) — clients/viewers grouped by shared lexicons. +- `atproto-tools-catalog` — clients/viewers grouped by shared lexicons. diff --git a/skills/software-development/atproto-moderation-tools/SKILL.md b/skills/software-development/atproto-moderation-tools/SKILL.md index f7a605f..f6d2cbd 100644 --- a/skills/software-development/atproto-moderation-tools/SKILL.md +++ b/skills/software-development/atproto-moderation-tools/SKILL.md @@ -18,6 +18,9 @@ Semble collections (2026-08-17) plus core protocol knowledge; the digest's moderation cluster was thin, so protocol-level facts below are from SDK/docs knowledge, flagged where applicable. +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. + ## When to Use - You need to run or integrate a labeler (custom moderation labels on the network). @@ -89,7 +92,8 @@ knowledge, flagged where applicable. - `curl -s https://ozone.tools` — ozone project up (source: bluesky-social/ozone). - Python: `FirehoseSubscribeLabelsClient().start(print)` shows label events from mod.bsky.app within seconds. -- `curl -s https://labels.bunnynabbit.com` — label explorer loads. +- Open https://labels.bunnynabbit.com in a browser (JS app; curl returns only the + HTML shell). - A labeler service record resolves: `at:///app.bsky.labeler.service/self`. ## Related skills diff --git a/skills/software-development/atproto-pds-ops/SKILL.md b/skills/software-development/atproto-pds-ops/SKILL.md index 44338d4..7510aa0 100644 --- a/skills/software-development/atproto-pds-ops/SKILL.md +++ b/skills/software-development/atproto-pds-ops/SKILL.md @@ -16,6 +16,9 @@ Operating, migrating, and debugging AT Protocol Personal Data Servers. Distilled the AT://links and DEEP AT://magic Semble collections (2026-08-17). PDS = the server that hosts accounts: their repo, records, and blobs. +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. + ## When to Use - You are provisioning or choosing a PDS (self-host vs managed). @@ -118,9 +121,10 @@ that hosts accounts: their repo, records, and blobs. ## Verify -- `curl -s https://pds.directory` — live PDS index. +- `curl -s https://bsky.network/xrpc/_health` returns `{"status":"ok"}`; pds.directory + is a JS app — open in a browser for the live index (curl returns only the HTML shell). - Run a target PDS/handle through check.cirrus.earth read-only checks. -- `curl -s https://debug.hose.cam` — debugger loads; paste a handle to see +- Open https://debug.hose.cam in a browser (JS app) and paste a handle to see relay repo status and PLC PDS history. - Migration drill: `com.atproto.sync.getRepo` on your own account downloads a valid .car. diff --git a/skills/software-development/atproto-relays-firehose/SKILL.md b/skills/software-development/atproto-relays-firehose/SKILL.md index 4643bec..f73ff19 100644 --- a/skills/software-development/atproto-relays-firehose/SKILL.md +++ b/skills/software-development/atproto-relays-firehose/SKILL.md @@ -16,6 +16,9 @@ How the relay network works, which public relays exist, and how to subscribe to firehose. Distilled from the AT://links and DEEP AT://magic Semble collections (digested 2026-08-17); re-verify live status via firehose.directory. +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. + ## When to Use - You need real-time ATProto data: every post, like, follow, delete, label event @@ -31,8 +34,9 @@ firehose. Distilled from the AT://links and DEEP AT://magic Semble collections - **subscribeRepos** = the websocket subscription (`com.atproto.sync.subscribeRepos`) that delivers commits as binary DAG-CBOR frames (MST/CAR blocks) — NOT JSON. - **Replay window** = how far back a relay can replay history to a fresh cursor - (typically 72h; Bluesky-mirror jetstreams often 24h). Events older than the window - are unrecoverable from that relay. + (typically 72h). Events older than the window are unrecoverable from that relay. + NOTE: a jetstream instance's replay window is a DIFFERENT layer (see + atproto-jetstream-providers) — don't conflate the two when choosing cursors. - **Crawl requests**: relays can be asked to crawl a specific PDS (per-relay status pages offer this) — useful when a newly-hosted account isn't appearing. @@ -109,7 +113,9 @@ client.start(on_message) ## Verify -- `curl -s https://firehose.directory` — relay statuses are live. +- `curl -s https://bsky.network/xrpc/_health` returns `{"status":"ok"}`; HTTP 400 + (not 404) from any relay's subscribeRepos URL means the endpoint is live. + firehose.directory is a JS app — use a browser for the dashboard. - Connect to `wss://northamerica.firehose.network/xrpc/com.atproto.sync.subscribeRepos` and confirm frames arrive within seconds (no auth). - SDK check: `FirehoseSubscribeReposClient().start(print)` shows commits immediately. @@ -119,4 +125,4 @@ client.start(on_message) - `atproto-ecosystem-map` — network roles + full provider registry (load first if you're not sure which service you need). - `atproto-python` — FirehoseSubscribeReposClient / Labels client in depth. -- `atproto-jetstream-providers` (planned) — JSON re-streams, edge caches, filters. +- `atproto-jetstream-providers` — JSON re-streams, edge caches, filters. diff --git a/skills/software-development/atproto-security-landscape/SKILL.md b/skills/software-development/atproto-security-landscape/SKILL.md index e4cdcee..3bf58d6 100644 --- a/skills/software-development/atproto-security-landscape/SKILL.md +++ b/skills/software-development/atproto-security-landscape/SKILL.md @@ -18,6 +18,9 @@ Distilled from the AT://links and DEEP AT://magic Semble collections (2026-08-17 note: the digest's "security" cluster was thin and mostly misfiled (events/privacy apps), so this skill leans on protocol-level knowledge where flagged. +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. + ## When to Use - You are auditing an account/app/PDS for security posture (OAuth conformance, diff --git a/skills/software-development/atproto-tools-catalog/SKILL.md b/skills/software-development/atproto-tools-catalog/SKILL.md index 351bfe5..95143dd 100644 --- a/skills/software-development/atproto-tools-catalog/SKILL.md +++ b/skills/software-development/atproto-tools-catalog/SKILL.md @@ -14,9 +14,13 @@ metadata: Index of the ATProto/Bluesky app landscape: clients, utilities, games, feeds, infrastructure. The FULL one-line catalog of 897 URLs (every entry, categorized) is -committed at `~/dev/_shared/docs/atproto-digest/catalog.md` — grep it for anything +committed in this repo at `docs/atproto-digest/catalog.md` (on this machine: +`~/dev/_shared/docs/atproto-digest/catalog.md`) — grep it for anything not listed here. This skill curates the notable entries per category. +> Snapshot: hard numbers are digest-time (2026-08-17) — re-verify live figures +> before production use. + ## When to Use - You want to know what exists in the ecosystem before building something @@ -27,7 +31,7 @@ not listed here. This skill curates the notable entries per category. ## How to search the full catalog ```bash -grep -i '' ~/dev/_shared/docs/atproto-digest/catalog.md +grep -i '' docs/atproto-digest/catalog.md # from repo root (this machine: ~/dev/_shared) ``` Categories in catalog.md: bsky-clients (290), streaming (51), pds-ops (43), @@ -107,7 +111,7 @@ blobs-media (12), security (9), moderation (4), other (283). ## Verify -- `grep -i '' ~/dev/_shared/docs/atproto-digest/catalog.md` returns the +- `grep -i '' docs/atproto-digest/catalog.md` (repo-root-relative) returns the entries you expect. - Spot-check 2-3 links from this skill still resolve. -- 2.51.2