Agent Surface is a practical resource for making software legible, callable, and useful to AI agents.
It combines documentation, implementation approaches, reusable templates, and a single skill: surface, which routes to the right workflow — audit, scaffold, transform, or generate.
The premise is simple: agents do not consume software through one interface. They read docs, inspect repositories, call APIs, run CLIs, use MCP tools, parse errors, retrieve context, and execute workflows. Agent Surface treats all of those as one design problem.
- Documentation — a Fumadocs site covering API surface, CLI design, MCP servers, discovery, authentication, errors, testing, multi-agent patterns, scoring, protocols, and tool design
- Approaches — opinionated patterns for making software agent-ready without turning every product into an agent framework
surfaceskill — a single skill that routes to audit, scaffold, transform, and generate workflows, scoring a codebase across 11 dimensions and scaffolding agents, tools, workflows, memory, model routing, browser access, and sandboxes- Specialist agents — focused workers for context files, discovery, errors, API shape, CLI ergonomics, auth, MCP, testing, retrievability, and agentic patterns
- Templates — reusable examples for discovery, auth, MCP, errors, evals, orchestration, and agent-facing contracts
- Tooling catalog — a curated list of well-regarded AI and agent tooling grouped by purpose
surface is a single skill that routes to the right workflow based on the request. It handles:
- audit this codebase for agent readiness
- make this repo easier for AI agents to use
- improve API, CLI, MCP, discovery, auth, testing, or retrievability surfaces
- produce a transformation plan
- execute the highest-impact upgrades
- create an agent
- add a tool
- build a workflow
- add memory
- set up model routing
- update an existing agent correctly
Core outputs:
- scorecard across 11 dimensions,
0-3each, max33 - clustered findings with concrete fixes
- prioritized transformation plan
- post-change delta scorecard
The 11 dimensions are:
- API Surface
- CLI Design
- MCP Server
- Discovery and AEO
- Authentication
- Error Handling
- Tool Design
- Context Files
- Data Retrievability
- Multi-Agent and Orchestration
- Testing and Evaluation
For agent system scaffolding, surface is Mastra-first for local TypeScript agent infrastructure, while respecting existing AI SDK, MCP, LangGraph, and Cloudflare Workers projects. It detects project shape before scaffolding and chooses conservative defaults for the runtime already in front of it.
Core outputs:
- agent definitions with clear instructions and tool registration
- typed tools with Zod schemas and MCP annotations
- workflow scaffolds with state, triggers, and safety patterns
- memory setup for Mastra, Postgres/pgvector, or Workers-native alternatives
- model routing across providers and gateways
- browser and sandbox tool wrappers with safety boundaries
High-signal parts of the repo:
skills/surface/- main skill entrypoint, scoring references, specialist agents, and agent system scaffoldingdisciplines/- longer-form guidance on agent design topicstemplates/- reusable templates for discovery, auth, MCP, errors, evals, and orchestrationsrc/app/- Next.js application for the docs sitesrc/content/docs/- MDX documentation content served by the sitedocs/- working specs and internal supporting documents
Prerequisites:
- Node.js 20+
- npm
Install and run the docs site:
npm install
npm run devOther useful commands:
npm run build
npm startNotes:
postinstallrunsfumadocs-mdx- the current
package.jsondoes not define dedicatedtestorlintscripts - Biome configuration lives in
biome.json
surface routes to the right workflow based on the command:
/surface- full audit with scorecard and findings/surface score- scorecard only/surface plan- audit plus transformation plan/surface transform- audit, plan, and execution/surface --dimension=X- focus on a single dimension/surface --format=json- structured output/surface init- initialize agent infrastructure/surface agent <name>- scaffold an agent/surface tool <name>- scaffold a typed tool/surface workflow <name>- scaffold a workflow/surface memory- add memory/surface model- configure model routing/surface browser- add browser/web access tooling/surface sandbox- add isolated code execution tooling
See skills/surface/SKILL.md for the operative workflow.
surface can delegate work to specialist agents in skills/surface/agents:
context-writerdiscovery-writererror-designerapi-optimizercli-enhancerauth-upgradermcp-buildertest-writerretrievability-engineeragentic-patterns-writer
These agents are used to apply focused fixes after the audit identifies the highest-impact gaps.
The Next.js site in src/app publishes the guidance stored in src/content/docs.
Current documentation areas include:
- API surface design
- CLI design
- context files
- discovery and AEO
- error handling
- MCP servers
- multi-agent patterns
- testing
- tool design
- data retrievability
- agent system scaffolding
- scoring and calibration
- protocols
- cookbook patterns
This repository is structured to be readable by multiple agent runtimes.
AGENTS.mdprovides repo-level guidanceskills/surface/SKILL.mdprovides execution instructions for audits, transformations, and agent system scaffolding- Claude Code can consume the plugin and skill layout directly
- Codex and other generic runtimes can use
AGENTS.mdplus the linked skill file
No standalone MCP server is bundled in this repository today. The repo mainly distributes the surface skill, related templates, and supporting documentation.
Visible in the checked-in code:
- Next.js 16
- React 19
- TypeScript 6
- Tailwind CSS 4
- Fumadocs
MIT
Daniel Howells