Agent Surface

Make software
legible to agents.

A practical resource for the surfaces AI agents depend on — APIs, CLIs, tools, MCP servers, docs, errors, auth, retrieval, and the skill that ties them together. Part field guide, part scoring model, part workflow.

Read the docsInstall the skill

The 11 surfaces

scored 0–3 each · 33 total

Every dimension an agent touches when it operates inside your codebase. Each one has a reference guide, scoring rubric, and transformation path.

01

API Surface

Machine-readable contracts and tool definitions

02

CLI Design

Predictable commands with structured output

03

MCP Servers

Protocol-native tool exposure

04

Discovery & AEO

Agent-findable capabilities and metadata

05

Authentication

Machine-to-machine access and token flows

06

Error Handling

Structured errors with recovery paths

07

Tool Design

Narrow, typed, idempotent operations

08

Context Files

AGENTS.md, CLAUDE.md, and boundary definitions

09

Retrievability

Searchable, retrievable knowledge access

10

Multi-Agent

Coordination, delegation, and orchestration

11

Testing & Evals

Metrics, red-team suites, and observability

/surface

One skill that routes to the right workflow — audit your codebase, scaffold agent infrastructure, generate MCP servers, write context files, or fix specific gaps. It reads your project and asks what you need.

Works with Claude Code, Codex, Cursor, and any agent that reads markdown skill files.

$ npx skills add https://github.com/howells/agentsurface

Also in the docs

ApproachesReusable patterns for agent-friendly software without rebuilding around a frameworkProtocols & StandardsMCP, A2A, ACP, and the agent communication landscapeScoring FrameworkThe 0–3 rubric and calibration guidance behind each dimensionTooling CatalogCurated AI and agent infrastructure worth knowing aboutReference LinksCanonical standards, specs, and official documentation