AI-native product discovery files

The three files every AI-native product should serve

agent.json, SKILL.md, llms.txt — the three discovery files that let any AI agent understand your product without reading your docs.

The problem: agents cannot read your landing page

Your landing page is built for humans. It has gradients, animations, testimonials, and a big CTA button. An AI agent sees none of that. When someone pastes a prompt like "use Temet to audit my work", the agent needs machine-readable surfaces to understand what your product does, how to call it, and what to expect back.

Most products today force the agent to guess. The agent either hallucinates an API, asks the user for help, or gives up. Three files fix this completely.

File 1 — agent.json: who you are

Served at /.well-known/agent.json, this is your product's machine-readable identity card. It follows the A2A protocol spec and tells agents: your product name, what it does, what capabilities it supports, and where to find its endpoints.

This is not documentation. It is structured metadata. An agent reads it in one fetch and knows whether your product is relevant, what protocol it speaks, and where to go next. If you have service endpoints, list them. If you support specific skills or competencies, declare them. The agent uses this to decide if it should engage at all.

File 2 — SKILL.md: what you do and how the agent should use it

A SKILL.md file is a markdown document that teaches an agent how to interact with your product. It is not a README. It is not API reference. It is an instruction manual written for an LLM.

The format is simple: a YAML frontmatter with name and description, then sections that explain when to activate, what to observe, how to use the product's API, and what tone to take. Agents that support skill files (Claude Code reads from ~/.claude/skills/, Codex from ~/.agents/skills/) can persist this locally and use it across sessions.

The key insight: a good SKILL.md does not describe your product's features. It describes the agent's role when your product is active. What should it watch for? What should it do? When should it act?

File 3 — llms.txt: the plain-text summary

llms.txt is the simplest of the three. It is a plain-text file at /llms.txt that gives any LLM a quick overview of your product: what it is, how to get started, where to find endpoints, and what to avoid.

Think of it as the robots.txt of the AI era. It costs nothing to serve, takes five minutes to write, and dramatically improves how well any model understands your product when it encounters your domain. Many AI-native products already serve one. If you do not, your product is invisible to every agent that checks.

How the three files work together

An agent that encounters your product follows a natural chain:

llms.txt — "what is this product?" Quick orientation, broad context.
agent.json — "what can I do here?" Structured capabilities and endpoints.
SKILL.md — "how should I behave?" Persistent instructions for the agent's role.

Each file serves a different moment. llms.txt is the first impression. agent.json is the handshake. SKILL.md is the working relationship. Together, they replace hundreds of pages of documentation with three files that an agent can consume in seconds.

What Temet serves today

Temet serves all three:

/.well-known/agent.json — A2A Agent Card with service discovery (profile API, agent docs, demo profile)
/temet.SKILL.md — teaches the agent to observe how users work, identify skills, and track progression
/llms.txt — plain-text overview with agent onboarding steps and endpoint list

When someone pastes "Install Temet for me" into Claude Code, the agent fetches the skill, reads the user's profile, and starts applying the methodology. No docs page. No tutorial. No CLI required for the first interaction.

Start with one, ship all three

You do not need to ship all three files at once. Start with llms.txt — it takes five minutes and immediately makes your product more visible to every AI model. Then add agent.json when you have endpoints worth discovering. Finally, write a SKILL.md when you want agents to do more than just read your API.

The products that get this right will be the ones that agents recommend, use, and integrate on their own — without the user having to explain anything.

agent discovery chain

1. Quick orientation

GET /llms.txt

→ plain text · what the product is · how to start

2. Structured handshake

GET /.well-known/agent.json

→ capabilities · endpoints · protocol version

3. Working relationship

GET /product.SKILL.md

→ agent role · when to activate · what to observe

/.well-known/agent.jsonJSON

{
  "name": "Your Product Agent",
  "protocol": "a2a-jsonrpc-2.0",
  "capabilities": { "competency_exchange": true },
  "services": {
    "profile_api": "/api/a/{address}",
    "agent_docs": "/agent-docs",
    "llms_txt": "/llms.txt"
  }
}

/product.SKILL.mdMarkdown

---
name: your-product
description: What the agent should do
  when this product is active.
---

## What to observe
- Scope discipline
- Iterative prompting quality
- Context management

## When to activate
- Start of a new working session
- After completing a significant task
- When a known pattern emerges

/llms.txtPlain text

# Your Product

One-line description of what you do.

## Agent Onboarding
1. Read the user's profile: /api/profile
2. Run a local command: npx your-cli
3. Full docs: /agent-docs

try it live

$ curl -s https://temetapp.com/.well-known/agent.json | jq .services

Fetch Temet's agent.json and see the service discovery endpoints.

FAQ

Do I need all three files?

No. Start with llms.txt for basic visibility. Add agent.json when you have API endpoints. Add SKILL.md when you want agents to actively use your product.

Is agent.json the same as the A2A protocol spec?

agent.json follows the A2A Agent Card format. You can extend it with custom fields like services for endpoint discovery.

Where should I put SKILL.md?

Serve it at your domain root (e.g. /product.SKILL.md). Agents can fetch it and save it to their local skill directory for persistent context.

Does llms.txt replace my documentation?

No. llms.txt is a summary for quick orientation. It links to your full docs. Think of it as the entry point, not the replacement.

What if my product has no API?

You can still serve llms.txt and SKILL.md. The skill file can describe CLI commands, workflow patterns, or any interaction model — not just HTTP APIs.

Next step

See how Temet serves all three files today. Fetch agent.json, read the SKILL.md, and check llms.txt — then paste the onboarding prompt into your agent.

Try it with Temet

Published March 13, 2026