agent-first is the de facto now

UpdatedJune 22, 2026

A code-dependent life form.

Comments (4)

Really interesting perspective. The idea that every doc page now has two readers — the developer and the agent — feels very accurate.

What stood out to me most is that agent-first docs are not just about formatting content differently. They reduce wrong assumptions by giving agents cleaner, current, machine-readable context. For security or identity protocols, that matters even more because a small misunderstanding can turn into a real implementation risk.

I also like the split between llms.txt, llms-full.txt, Skills, and MCP. It makes the documentation layer feel less like static content and more like part of the developer tooling itself.

Lara Laurielle1mo ago

The "every product gets a second customer" idea is actually a pretty interesting way to think about it

Suny Choudhary1mo ago

“Every page gets read twice” is the right line.

Once by the developer, once by the agent that will confidently misuse anything vague or stale.

Mateo Ruiz1mo ago

The line that stood out to me was: "every page now gets read twice." That perfectly captures what's changing in developer tooling.

For years, good documentation was about helping humans understand a system. Now it also has to help agents execute against it correctly. The cost of stale docs isn't just developer frustration anymore it's agents confidently generating incorrect implementations at scale.

What's interesting is that this shifts documentation from being a support asset to being part of the product itself. If APIs, SDKs, and MCP endpoints are the interface, then machine-readable docs become part of the runtime context that determines whether integrations succeed or fail.

The challenge now isn't making docs agent-friendly. It's keeping them synchronized with reality as fast as the product evolves. That's where most teams will struggle.

More from this blog

Passport Chips, Explained

The first time I held my phone against my passport and watched an app pull my own photo off the chip, I had two reactions. First: that's really cool. Second: wait, how did it do that? So I went diggin

Jul 9, 20268 min read

Watching the Black Box

The final part of a series on agent harnesses. We started with the model-plus-harness idea, then built subagents, gave them a safe place to work, and wired up tools, memory, and workflows. This last p

Jun 6, 20267 min read

Hands, Memory, and a Job to Do

Part four of a series on agent harnesses. The earlier pieces covered the model-plus-harness idea, subagents, and sandboxes. This one is about the three things that turn a capable agent into one that e

Jun 6, 20267 min read

Letting Agents Run, Safely

Part three of a series on agent harnesses. Part one introduced the model-plus-harness idea, and part two split work across subagents. This piece is about the layer where agents stop just talking and s

Jun 5, 20268 min read

Kartik Mehta

43 posts

Engineering and Product Development harmoniously united.

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.

Command Palette