Skip to main content
An agent app is a service built with AI agents as the primary user. Instead of rendering a visual UI for humans to click through, an agent app exposes structured endpoints that agents can discover, understand, and call programmatically.

​
How agents discover your app

Agents find your service through a SKILL.md file hosted at a well-known URL path: /.well-known/SKILL.md. If you’ve worked with web development, this pattern may be familiar:
  • Apple uses /.well-known/apple-app-site-association for universal links
  • SSL certificate authorities use /.well-known/acme-challenge/ to verify domain ownership
  • OAuth uses /.well-known/openid-configuration for discovery
The /.well-known/ convention is a standard way to host metadata at a predictable location. For agent apps, your SKILL.md file lives there so any agent can find it by checking yourdomain.com/.well-known/SKILL.md.

​
What goes in a SKILL.md

Your SKILL.md file describes what your app does, what endpoints are available, and how to use them. Here’s a conceptual template:
Title
# Your App Name

## Description
What your app does, in plain language.

## Endpoints

### POST /api/action-name
- **Description:** What this endpoint does
- **Inputs:** What parameters it expects
- **Output:** What it returns
- **Payment:** Whether it requires x402 payment and the cost

## Authentication
How agents should authenticate (e.g., SIWA, API key, x402).
When an agent reads your SKILL.md, it understands what your service offers and how to interact with it, no human in the loop required.

​
Designing for agent users

Agents aren’t humans. They don’t browse, guess, or interpret visual cues. When building an agent app, follow these guidelines:
  • Document side effects: if an endpoint transfers funds, modifies state, or triggers external actions, say so explicitly in your SKILL.md
  • Return structured JSON: agents parse JSON, not HTML. Every endpoint should return well-structured JSON responses with consistent field names
  • Support x402 for paid access: if your service costs money, implement the x402 protocol so agents can pay per request without pre-registration
  • Use clear error responses: return descriptive error messages with appropriate HTTP status codes so agents can handle failures gracefully

​
Making your app discoverable

Host your SKILL.md at /.well-known/SKILL.md and register your app in the ERC-8004 registry. The same registry used for agent identity is used for app discovery. Once registered, agents can query the registry, find your service, and read your SKILL.md to understand how to interact with it.
The Agent App Framework is experimental. APIs and conventions may change as the standard evolves.
Agent App Frameworkhttps://github.com/base/agent-apps-experimental

​
Continue exploring

Back to overview

Return to the AI agents overview for a summary of all components.