agent-first is the de facto now

I just finished rebuilding our docs at docs.self.xyz, and the whole thing came from one assumption: every page now gets read twice. Once by a developer, and once by the agent sitting next to them. If I only design for the human, the agent reads stale HTML, guesses at our API, and ships code I then have to catch in review.

So I designed for both.

We are building Self to be agent-first, and that is not a detour from good DevEx, it is the next layer of it. The docs are where it starts, but the whole ecosystem points the same way. Here is why that matters, and what we shipped.

the friction is never the protocol

Adopting any new protocol should be the easy part. The friction is rarely the core API. It is everything around it. The page that is one version behind. The concept you did not know existed. The step you got subtly wrong because nothing told you it mattered. None of that is the protocol. All of it eats the afternoon.

DevEx research keeps landing on the same three levers, and onboarding onto something new stresses all three:

• Feedback loops. How fast do you know it works? A test mode and a ten-minute quick-start shorten this.

• Cognitive load. How much do you have to hold in your head before you can make one call? Clear, well-named concepts shrink it. Unfamiliar territory blows it up.

• Flow state. Can you stay in your editor, or do you have to tab out and read a wall of docs? This is the lever agents change the most.

my agent has the same three problems

Here is the part that reframed the whole project for me. When our docs are stale, my agent confidently writes against an SDK shape that no longer exists. When a concept is fuzzy, it picks the wrong option. When an important step is buried, it skips it entirely and writes something that looks right and is not.

So the docs are not just human comfort anymore. They are the context the agent runs on. That meant building a machine-readable surface alongside the human one.

what we shipped

The goal was simple: make the docs agent-first. An agent handed nothing but our docs should be able to ship a correct Self integration. Here is the surface that makes that possible.

Surface	What it is	What it is for
Per-page .md + Copy page	Clean Markdown of any doc page (append .md to any URL)	Agent context with no nav, CSS, or HTML chrome eating the token budget
Open in Claude / Open in ChatGPT	A button that prefills a prompt pointing at the page's .md	The developer who wants to ask the page a question, not read it top to bottom
Copy Prompt (landing page)	A ready task: read the quickstart, then add verification to my app	Handing the whole integration to a coding agent in one paste
llms.txt	A one-line index of every page	Discovery, so the agent routes to the right page instead of scraping
llms-full.txt	The entire doc set concatenated into one file	One-shot ingestion when an agent wants the full picture in context
Skills (SKILL.md)	Procedural recipes for Self workflows	Teaching the agent how to integrate, not just what the API is
MCP	Live, queryable docs over a standard interface	Always-current answers, never a cached version from three releases ago

The split between these matters. llms.txt is the index, llms-full.txt is the corpus, skills are the muscle memory, and MCP is the live connection. An agent picks the cheapest one that answers the question. A developer never sees most of it, which is the point.

why this compounds for an identity protocol

A bad error message costs one developer a few minutes. A bad doc page now costs every developer plus every agent, and a confused agent does not just lose time. It produces plausible wrong code, and when the thing you are integrating is a security primitive, wrong is not cosmetic. A subtle mistake in a security flow is a real hole, not a visual bug. That is exactly the kind of error a machine-readable, current doc surface prevents.

The flip side is the leverage.

Tight feedback loops mean the agent iterates fast and I catch mistakes early. Low cognitive load means a developer can write one sentence, paste the prompt, and trust the surrounding context to fill in the rest. That is the difference between a ten-minute quickstart that holds and one that quietly breaks on the first real integration.

what actually changed

The protocol is the same. What changed is the DevEx around it. Self is agent-first now, so the fastest way to feel the difference is to let your agent do the work: point it at the Self MCP, ask it to integrate Self Enterprise into your app, and you are done in about ten minutes.

Prefer to read first? Start with the Quickstart.