Agent Surface
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.
What This Repo Contains
- 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
surface skill — 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
What surface Does
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
Audit and Transform
Core outputs:
- scorecard across 11 dimensions,
0-3 each, max raw score 33, scaled to 30 for ratings
- 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
- Multi-Agent and Orchestration
- Testing and Evaluation
- Data Retrievability
Scaffold
For agent system scaffolding, surface chooses the framework from the project shape. It prefers existing deliberate infrastructure, then selects OpenAI Agents SDK, Claude Managed Agents/Claude Code SDK, Vercel AI SDK, Vercel Workflow, Cloudflare Agents, Mastra, LangGraph, or MCP-first patterns based on runtime, deployment target, durability needs, and external agent interoperability.
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 Claude Managed Agents, Mastra, Postgres/pgvector, Workers-native alternatives, or the repo's existing storage
- model routing across providers and gateways
- browser and sandbox tool wrappers with safety boundaries
Repository Contents
High-signal parts of the repo:
skills/surface/ - main skill entrypoint, scoring references, specialist agents, and agent system scaffoldingsrc/content/docs/agents/framework-selection.mdx - current framework selection guidancesrc/content/docs/agents/anthropic-platform.mdx - Claude Managed Agents, Claude Code SDK, Agent Skills, MCP connector, and Anthropic platform notesdisciplines/ - 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
Quick Start
Prerequisites:
Install and run the docs site:
pnpm install
pnpm dev
Other useful commands:
pnpm build
pnpm start
Notes:
postinstall runs fumadocs-mdx- the current
package.json does not define dedicated test or lint scripts
- Biome configuration lives in
biome.json
Using The Skill
surface routes to the right workflow based on the invocation:
