x.md for agents

When to reach for x.md, the three ways to call it, and the machine-readable descriptions of all of them.

When to use x.md

Reach for x.md when the job is reading one piece of public X content right now:

The text of a public X post, thread, or X Article, without a browser or an X login.
Resolving an x.com, twitter.com, or t.co link found in a document, issue, changelog, or chat log. Swap the host for x.pcstyle.dev and keep the path.
A public profile’s bio and latest original posts, without holding X credentials.
Who a public account follows, or who follows it.
X search results as structured data rather than a rendered timeline.
Saving a post into notes or a vault — ?format=obsidian emits YAML frontmatter.

When not to use it

Anything that writes. x.md never posts, replies, follows, likes, bookmarks, or sends direct messages, and it accepts no X credentials. A write attempt is 405.
Private, protected, suspended, or deleted content. Never available; no parameter unlocks it.
X Lists, direct messages, notifications, the home timeline, analytics. Not supported.
Bulk or firehose collection. Rate limited and cached for interactive use; a page walk stops at ten pages of twenty items.
Guaranteed completeness or liveness. Upstream providers can be delayed or partial. Check warnings rather than inferring.
Anything needing an SLA or support commitments. Free, best effort, MIT-licensed.

Three ways to call it

No key, no OAuth, no SDK. One GET.

curl -sS -H 'Accept: text/markdown' \
  'https://x.pcstyle.dev/trq212/status/2052809885763747935'

Ask for Accept: application/json (or ?format=json) when you need fields. Every route, parameter, and response schema is in /openapi.json; the stable machine paths are /api/v1/*.

The same reads as Model Context Protocol tools, over Streamable HTTP, no key required.

https://x.pcstyle.dev/mcp

Connect an agent to the MCP server.

A small, read-only skill for coding agents.

bunx skills add pc-style/x-md -g -y --skill browse-x

The skill calls the hosted service. It does not need a local x.md checkout, X login, or provider key.

Use the browse-x CLI

From a checkout, run the included script:

bun skills/browse-x/scripts/browse-x.ts search 'typescript' --feed latest
bun skills/browse-x/scripts/browse-x.ts search 'design' --feed photos --limit 10
bun skills/browse-x/scripts/browse-x.ts search 'vercel' --feed users --json
bun skills/browse-x/scripts/browse-x.ts profile vercel --full
bun skills/browse-x/scripts/browse-x.ts status 'https://x.com/trq212/status/2052809885763747935' --thread off

Option	Effect
`--json`	Structured response
`--full`	Expanded metadata
`--limit 1-20`	Browse result count
`--cursor TOKEN`	Continue a browse result
`--page 1-10`	Walk to a numbered page
`--headers`	Print response headers
`--nocache`	Bypass application caching

The script exits with 2 for invalid arguments and 1 for network or API errors, and with 3 after printing Retry-After when a rate limit rejects the call.

What an unattended client should handle

Signal	Action
`RateLimit` / `RateLimit-Remaining`	Pace against the tightest policy. Limits.
`429` + `Retry-After`	Sleep that many seconds, then retry once. Do not poll.
`Deprecation` / `Sunset`	Follow `Link; rel="successor-version"`. Versioning.
`code` in a problem body	Branch on it, never on `detail`. Error catalogue.
`nextCursor`	Continue; stop only when it is absent. Pagination.
`degraded` / `X-Search-Degraded`	Results are web-indexed snippets, not a live timeline.

Machine-readable entry points

Document	Purpose
`/llms.txt`	What x.md is for, when to use it, and every route, in one text file
`/openapi.json`	OpenAPI 3.1: parameters, response schemas, error bodies, quotas, lifecycle
`/api`	A small JSON index for an agent that has only the domain
`https://x.pcstyle.dev/mcp`	MCP server over Streamable HTTP — see the MCP page
`/.well-known/api-catalog`	RFC 9727 linkset
`/.well-known/ard.json`	Agentic Resource Discovery catalog

Read docs as Markdown

Each documentation page has a Copy as Markdown action. Append .md to any docs URL, send Accept: text/markdown, or add ?mode=agent. The documentation manifest lists every page.