The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Agent Surface listing page.
Agent Surface is a field guide and implementation kit for engineering teams making software operable by agents: discoverable, understandable, callable, recoverable, and evaluable.
Agents do not reach software through one interface. They read docs, inspect repositories, call APIs, run CLIs, use MCP tools, parse errors, and retrieve data. Agent Surface treats all of those contact points as one design problem: the agent surface.
The site has two labelled parts.
Part 1 - Make your product agent-ready (the core guide). Product-side, framework-neutral
guidance for making an existing product usable by agents: discovery, API surface, tool
design, CLI design, MCP servers, authentication, error handling, context files
(AGENTS.md/CLAUDE.md), agentic UI, retrievability (search APIs, retrieval contracts,
structured content), protocols, testing, scoring, and reference links. This is the guide the
surface skill applies.
Part 2 - Build agents (the agent-building inventory). A secondary, condensed reference for
teams building their own agents: frameworks (including Mastra), platform features,
orchestration, memory, durable execution, browser and sandbox access, guardrails
(/docs/agents), and agent retrieval - vector databases, embeddings, RAG, knowledge graphs
(/docs/agent-retrieval) - plus a tooling catalog. This inventory gives one short summary of
current practice per topic; it sits outside the core guide and outside the surface skill.
An earlier version of this repo kept agent-internal architecture out entirely. We keep the inventory because it is worth maintaining as a reference, but it stays separate so the guide does not turn into a general agent-building toolkit.
surface Skillsurface is a single skill with three routes, all product-side and framework-neutral:
plan and transform are Audit modes, not
separate routes; transform executes only after explicit confirmation.The 10 audit dimensions:
See skills/surface/SKILL.md for the operative workflow and
skills/surface/references/ for the per-dimension and
per-mode detail.
skills/surface/ - skill entrypoint, audit/scaffold references, and specialist agent promptssrc/content/docs/ - the two-part MDX guide served by the docs sitedisciplines/ - longer-form guidance on agent-surface design topicstemplates/ - reusable starter files the implementation kit points tosrc/app/ - Next.js application for the docs sitedocs/ - ADRs and internal supporting documentsPrerequisites:
Install and run the docs site:
Other useful commands:
Notes:
postinstall runs fumadocs-mdxpnpm prepush runs typecheck, lint, then test - the full local gateoxlint.config.ts and oxfmt.config.tssurface routes to the matching workflow based on the request:
/surface - explain a concept, or run a full audit with scorecard and findings, depending on the ask/surface score - scorecard only/surface plan - audit plus transformation plan/surface transform - audit, plan, and execution (after confirmation)/surface --dimension=X - focus on a single dimension/surface --format=json - structured output/surface init - initialize baseline agent-surface conventions (AGENTS.md, llms.txt, .well-known)/surface api / /surface cli / /surface mcp - scaffold or upgrade that surface/surface tool <name> - scaffold or refine one typed tool contract/surface test-harness - scaffold an evaluation harness for a surfaceThese are skill/runtime invocations, not an npm binary. This repository does not publish a bin entry in package.json.
surface can delegate focused work to specialist prompts in skills/surface/agents:
context-writer, discovery-writer, error-designer, api-optimizer, cli-enhancer, auth-upgrader, mcp-builder, test-writer, tool-design-writer - improve an existing surface in placeretrievability-engineer - build or upgrade search/query APIs, retrieval contracts, and structured contentscore-* prompts - score one audit dimension in parallel delegationThese agents apply focused fixes after an audit identifies the highest-impact gaps; they are task resources, not required context for ordinary guide/audit/scaffold routing.
The Next.js site in src/app publishes the guidance in src/content/docs, split into the two parts described above.
This repository is structured to be readable by multiple agent runtimes.
AGENTS.md provides repo-level guidanceskills/surface/SKILL.md provides execution instructions for the Guide, Audit, and Scaffold routesAGENTS.md plus the linked skill fileThe docs site also exposes a lightweight HTTP MCP endpoint at /mcp for documentation search and page retrieval. This is a docs discovery surface, not a generated project MCP server; the surface skill, templates, and guidance remain the primary distribution artifacts.
Visible in the checked-in code:
MIT
Daniel Howells