Tool documentation

How a Bluesky custom feed works, and how to debug it

The parts of a Bluesky custom feed: the generator record, the service DID, the #bsky_fg service, skeleton and hydrated feeds, and how to fix each health check.

The parts of a custom feed

A custom feed has two halves that live in different places:

  • The record, app.bsky.feed.generator, on its creator's account: its name, description, avatar, and a did field naming the feed generator that serves it. Its address is the feed's AT URI, at://<creator>/app.bsky.feed.generator/<rkey>, and its bsky.app link is https://bsky.app/profile/<creator>/feed/<rkey>.
  • The feed generator, a server identified by that DID (a did:web or a did:plc). Its DID document has a service with the id #bsky_fg and the type BskyFeedGenerator, whose serviceEndpoint is the server's https address.

One generator can serve many feeds, each from its own record.

Skeleton and hydrated feed

When someone opens a feed, the app asks Bluesky's AppView for app.bsky.feed.getFeed. The AppView reads the record, resolves the generator's DID, finds its #bsky_fg endpoint, and calls app.bsky.feed.getFeedSkeleton there. The generator answers a skeleton: a list of post URIs, nothing else.

json
{
  "feed": [
    { "post": "at://did:plc:abc/app.bsky.feed.post/3l2k7yqzx2c2a" }
  ],
  "cursor": "1731567000000"
}

The AppView then hydrates it: it fetches each post, its author and its counts, applies blocks, mutes and labels, and returns full post views. The generator never sees who reads the feed unless the viewer is signed in, in which case the request carries a token naming them.

The AppView also tracks each generator: isOnline says it reached the generator recently, isValid that its answers had the right shape. The feed inspector shows both.

The DID document

For a did:web, the document is served at https://<host>/.well-known/did.json; for a did:plc, the PLC directory holds it. A minimal one:

json
{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:web:feed.example.com",
  "service": [
    {
      "id": "#bsky_fg",
      "type": "BskyFeedGenerator",
      "serviceEndpoint": "https://feed.example.com"
    }
  ]
}

The generator must also answer app.bsky.feed.describeFeedGenerator with the same DID and the AT URI of every feed it serves.

The health check, step by step

The inspector's health check runs only when you ask, and follows the same path as the AppView:

  1. Service DID. The record's did must be a did:web on a bare host name (no port, no path) or a did:plc. Otherwise, publish the record again with the right DID.
  2. #bsky_fg service. The DID document must exist, be valid JSON whose id is the DID, and hold a #bsky_fg service of type BskyFeedGenerator with an https endpoint.
  3. describeFeedGenerator. GET <endpoint>/xrpc/app.bsky.feed.describeFeedGenerator must answer 200 with a did equal to the service DID and a feeds list.
  4. The feed is listed. The feed's AT URI should be in that feeds list. A missing feed is a warning: some generators serve feeds they do not list.
  5. getFeedSkeleton. GET <endpoint>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1 must answer 200 with a feed array. A 401 means the feed needs a signed-in viewer: it works in the app, but not for logged-out readers, nor in the inspector's preview.

Each request has 4 seconds and 64 KB, and the time it took is shown. The requests go through our safety checks: https on port 443 only, and never to a private or local address, so a generator on a home network or behind a tunnel to localhost fails the check even when the app reaches it through a public address.

Common fixes

  • Offline, but the server works: check the endpoint in the DID document (a typo, http:// instead of https://, a trailing path) and that the certificate is valid for that host.
  • Valid is false: the skeleton must be an object with a feed array of { "post": "<at uri>" } items; extra fields are fine, other shapes are not.
  • The preview is empty but the skeleton is not: the posts it returns may be deleted, from blocked or taken-down accounts, or from authors who share only with signed-in users.
  • It worked, then stopped: a did:web generator that moved to a new host needs its DID document updated; a did:plc one needs a PLC operation.

The AT Protocol's custom feed tutorial and Bluesky's feed generator starter kit cover building one. Bluesky.bot runs its own generator for the bots feed; its DID document is at /.well-known/did.json.

Feed inspector

Preview a custom feed and find out why it shows nothing.