What is Agent Surface?

Agent Surface is a practical resource for designing software that AI agents can understand and use.

The core idea is that agents do not interact with a product through one neat interface. They read repository instructions, follow documentation, call APIs, run CLIs, inspect schemas, use MCP tools, parse errors, retrieve context, and coordinate work across tools. Each of those contact points is a surface. If the surfaces are ambiguous, agents improvise. If the surfaces are explicit, agents can work reliably.

Agent Surface exists to make those surfaces intentional.

The Story

Most software was built for human operators. A person can scan a docs page, infer missing context, recover from vague errors, and ask another person what a field means.

Agents are less forgiving. They need contracts, schemas, examples, recovery paths, permission boundaries, and machine-readable context. They can be powerful when the system gives them clear handles. They become brittle when every step depends on guessing.

Agent Surface treats agent readiness as an engineering discipline:

1. Name the surfaces agents touch.
2. Define what good looks like for each surface.
3. Score a codebase against those expectations.
4. Fix the highest-impact gaps first.
5. Keep the surfaces current as the product changes.

What This Includes

Documentation

The docs are the field guide. They explain the surfaces that matter:

• API surface and OpenAPI design
• CLI design for automation
• MCP servers and tool definitions
• discovery files such as AGENTS.md and llms.txt
• authentication for machine-to-machine access
• structured errors and recovery hints
• testing, evaluations, and observability
• retrievability, RAG, and knowledge access
• multi-agent orchestration patterns
• protocol choices and tradeoffs

Approaches

The approaches are the reusable patterns behind the docs. They cover how to make existing software agent-friendly without rebuilding it around an agent framework.

Examples include:

• publish machine-readable contracts before adding new orchestration
• make CLIs predictable before making them conversational
• design errors as recovery instructions
• expose tools with narrow, typed, idempotent operations
• separate human UX from agent-operable surfaces
• measure readiness before transforming a codebase

The surface Skill

surface is the operational part of Agent Surface. It reads your project and routes to the right workflow — auditing, scoring, scaffolding, or transforming.

In audit mode, it scores a codebase across 11 dimensions, each rated 0 to 3, and produces evidence-backed findings:

1. API Surface
2. CLI Design
3. MCP Server
4. Discovery and AEO
5. Authentication
6. Error Handling
7. Tool Design
8. Context Files
9. Data Retrievability
10. Multi-Agent and Orchestration
11. Testing and Evaluation

It can stop at a scorecard, produce a transformation plan, delegate focused improvements to specialist agents, or scaffold new agent infrastructure shaped to the existing project.

Resources

The repo also carries reusable resources:

• templates for discovery, auth, MCP, errors, evals, and orchestration
• specialist agent prompts for targeted codebase improvements
• scoring rubrics and calibration guidance
• a reference index for canonical standards, specs, and official docs
• a tooling catalog for respected AI and agent infrastructure
• cookbook patterns for production agent systems

How to Use It

Use the documentation when you are designing an agent-facing surface.

Use the scoring rubric when you need to compare projects or prioritize work.

Use surface when you want an evidence-backed audit, a concrete transformation plan, or to scaffold and update agent infrastructure in the shape of the existing project.

Use the templates when you are implementing a specific surface and want a starting point that is already shaped for agents.

Where to Start

• Getting Started for a quick assessment
• Reference Links for canonical standards, specs, and official docs
• Scoring for the readiness model
• API Surface for machine-readable API design
• CLI Design for automation-friendly commands
• MCP Servers for tool exposure
• Tooling Catalog for the broader AI tooling landscape