Headless Domains llms.txt: A Practical Guide for AI Agents

Headless Domains’ llms.txt gives agents a starting map of the platform: where to find workflows, authentication instructions, API documentation, and public identity records. Its useful job is to help a reader choose the next source for a task.

Ask an assistant to help register a name and it has several questions to resolve. Where should it start? Does it need an account? Which calls are public? What would spending money require?

Our live llms.txt file points toward those answers. Use it to find the instructions relevant to the job in front of you.

Start with the task, then follow the map

The file opens with a “Start here” section. It links to the primary skill file, OpenAPI specification, MCP discovery, domain search, canonical resolver, and learning resources.

Those are different destinations. Someone learning the concept needs a different reading path from an agent preparing an authenticated request.

For example, the index points to /api/v1/resolve/ for current identity and action discovery, while retaining /api/v1/lookup/ for profile lookup. That is a useful distinction to preserve when an older article or saved prompt mentions only the lookup endpoint.

For registration help, begin with the linked workflow. For a specific API operation, inspect its contract. For a public identity, use the documented read-only resolution path. Fetch more detail when it answers the next question.

What the llms.txt proposal actually asks for

The current llms.txt proposal describes Markdown background, guidance, and links that help agents use a website. Its v2 guidance supports files at the site root or a relevant subpath, with detail fetched from linked resources as needed.

Our implementation includes a broad site index as well as operational pointers. An agent can use the opening section to orient itself without treating every linked blog post as required reading.

For a general comparison of file roles, see llms.txt, SKILL.md, and agent.json. This article focuses on navigating our actual implementation.

Use the specific documentation for the operation

A link description is a summary. Follow it before relying on a security or payment claim.

One example in our current files makes this clear. The index describes scoped API access, but the more detailed authentication guide explicitly states that the current Headless Domains API-key model does not enforce credential-specific scopes. An agent must not infer a restricted credential simply because an index entry uses the word “scoped.”

The authentication guide also distinguishes direct credential provisioning from the full signed-assertion exchange described by the auth.md proposal. Those implementation details belong in the task-specific source.

If two sources conflict, identify the disagreement. Use the detailed, current contract to investigate, and stop before an action that depends on an unresolved assumption. Picking the more convenient wording is not a verification method.

Why we no longer recommend “internalize these five files”

The earlier version of this article asked an assistant to load the index, workflow, extended context, OpenAPI specification, and Agent Card before doing anything.

That creates unnecessary reading for many tasks. It also gives broad summaries and specific operating instructions the same apparent weight.

The public card endpoint also supplies platform metadata. Finding JSON at that address does not, by itself, verify compatibility with an A2A version or prove that a callable agent service is available.

Read the material needed for the task. Check the contract of any interface you plan to use.

A prompt for a focused first pass

Use this with an assistant that can fetch public web resources. Replace the task with what you actually want to do:

Read https://headlessdomains.com/llms.txt and identify the current documentation relevant to this task:

[Describe the task.]

Follow the relevant links, including skill.md for workflows and auth.md or OpenAPI when the task requires them. Do not load every linked resource by default.

Explain:
- Which documented workflow applies.
- What my environment needs to complete it.
- Which steps are public reads and which require credentials, changes, or payment.
- Any conflicting or missing instructions.

For this first pass, use public read-only requests only. Do not create an account, change records, send messages, or spend money. Return a proposed next step with source links.

This is a planning prompt, not a tested promise that every assistant can use the platform. A chat that can read documentation may still lack HTTP execution tools, secure credential storage, or a funded payment method.

The file provides instructions, not authority

A website can explain how to create an account or pay for a resource. It cannot grant your agent permission to do those things on your behalf.

The same boundary applies to resolved actions. Headless Domains’ machine instructions describe resolution as discovery. The execution provider remains responsible for authentication and authorization.

For developers building that execution path, our agent-ready API guide covers the broader implementation work. A readable index helps an agent locate that machinery; it does not replace it.

Judge the result by what the reader can find

A useful review starts with a real task. Can the assistant find the appropriate workflow, identify its prerequisites, and cite the source behind its answer? Does it notice when a summary and a detailed document disagree?

Keep the index useful by maintaining its links and descriptions alongside the documentation they summarize. When you already know you want to get started with an agent name, go directly to the Headless Domains skill file and ask your assistant to explain the current workflow before taking action.