---
title: "What is Agent Surface?"
description: "A guide to making websites, apps, APIs and CLIs usable by AI agents, plus a current inventory of tools and practice for building agents"
url: "https://agentsurface.dev/docs"
lastVerified: 2026-09-25
lastModified: 2026-09-25T09:21:34.000Z
---



Agent Surface is a guide to making software usable by agents. Agents reach a product through many contact points: they read repository instructions and documentation, call APIs, run CLIs, use MCP tools, parse errors, retrieve data and ask for approval. Each contact point is part of the product's agent surface, and each can be designed well or badly.

The site has two parts.

## Make your product agent-ready [#make-your-product-agent-ready]

The core of the guide. It covers how agents find, understand and use an existing website, app, API or CLI, and how to test that they can.

* [Discovery](/docs/discovery): robots.txt, llms.txt, structured data, Markdown routes and well-known endpoints
* [Context Files](/docs/context-files): `AGENTS.md` and tool-specific instruction files
* [API Surface](/docs/api-surface): OpenAPI contracts, versioning, webhooks and long-running jobs
* [Tool Design](/docs/tool-design): Names, descriptions, schemas, curation, safety and human approval
* [CLI Design](/docs/cli-design): Parseable output, input hardening and safety rails
* [MCP Servers](/docs/mcp-servers): Exposing tools, resources and prompts over MCP
* [Authentication](/docs/authentication): Scoped credentials, OAuth for agents and delegated access
* [Error Handling](/docs/error-handling): Recoverable errors, retries and idempotency
* [Retrievability](/docs/retrievability): Search and retrieval APIs and structured content agents can use
* [Agentic UI](/docs/agentic-ui): Browser-agent accessibility, MCP Apps and session control
* [Agentic Commerce](/docs/agentic-commerce): Product data, checkout protocols, payments, Shopify, trust and risk, and orders
* [Protocols](/docs/protocols): MCP, A2A, WebMCP and emerging standards
* [Testing](/docs/testing): Evals, traces and CI gates for agent tasks
* [Scoring](/docs/scoring): The Surface scorecard and how public scanners fit in
* [Reference Links](/docs/reference-links): Canonical specs and the model allowlist
* [Glossary](/docs/glossary): Every term on the site, defined once

## Build agents [#build-agents]

A secondary reference for teams building their own agents: current best practice per topic and an inventory of tools and platforms worth knowing.

* [Agents](/docs/agents): Frameworks, platform features, orchestration, memory, durable execution, browsers and sandboxes, guardrails
* [Agent Retrieval](/docs/agent-retrieval): Vector databases, embeddings, RAG and knowledge graphs
* [Tooling Catalog](/docs/tooling-catalog): The inventory, grouped by purpose

## The `surface` skill [#the-surface-skill]

`surface` applies the guide to a specific repository. It has three routes: Guide explains concepts and supports decisions, Audit produces an evidence-backed scorecard and plan, and Scaffold creates or extends agent surfaces and the tests that check them. The skill covers the product side only.

```sh
npx skills add https://github.com/howells/agentsurface
```

To use it, open Claude Code or Codex in your project and run the skill: type `/surface` in Claude Code or `$surface` in Codex. With no other instruction it audits the codebase, scores each part of its agent surface and returns the findings with a plan. Ask a question after the command to get an explanation instead, or name a surface, such as `/surface mcp`, to build or improve that part.

## Where to start [#where-to-start]

* [Getting Started](/docs/getting-started) to pick a route by goal
* [Discovery](/docs/discovery) if agents need to find your product
* [API Surface](/docs/api-surface) or [MCP Servers](/docs/mcp-servers) if agents need to operate it
* [Scoring](/docs/scoring) if you need to assess where you stand