What is Agent Surface?

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

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.

1. 01Discovery: robots.txt, llms.txt, structured data, Markdown routes and well-known endpoints
2. 02Context Files: AGENTS.md and tool-specific instruction files
3. 03API Surface: OpenAPI contracts, versioning, webhooks and long-running jobs
4. 04Tool Design: Names, descriptions, schemas, curation, safety and human approval
5. 05CLI Design: Parseable output, input hardening and safety rails
6. 06MCP Servers: Exposing tools, resources and prompts over MCP
7. 07Authentication: Scoped credentials, OAuth for agents and delegated access
8. 08Error Handling: Recoverable errors, retries and idempotency
9. 09Retrievability: Search and retrieval APIs and structured content agents can use
10. 10Agentic UI: Browser-agent accessibility, MCP Apps and session control
11. 11Agentic Commerce: Product data, checkout protocols, payments, Shopify, trust and risk, and orders
12. 12Protocols: MCP, A2A, WebMCP and emerging standards
13. 13Testing: Evals, traces and CI gates for agent tasks
14. 14Scoring: The Surface scorecard and how public scanners fit in
15. 15Reference Links: Canonical specs and the model allowlist
16. 16Glossary: Every term on the site, defined once

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.

1. Agents: Frameworks, platform features, orchestration, memory, durable execution, browsers and sandboxes, guardrails
2. Agent Retrieval: Vector databases, embeddings, RAG and knowledge graphs
3. Tooling Catalog: The inventory, grouped by purpose

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.

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

• Getting Started to pick a route by goal
• Discovery if agents need to find your product
• API Surface or MCP Servers if agents need to operate it
• Scoring if you need to assess where you stand