howells/agentsurface/surface

Surface

Surface improves the contact points agents use to reach existing software: discovery, context files, APIs, CLIs, MCP servers, tool contracts, auth, errors, retrieval and the tests that prove them. It is framework-neutral and product-side. For agent internals (frameworks, orchestration, memory, model routing, an agent's own RAG), say this skill doesn't cover them and point to https://agentsurface.dev/docs/agents and /docs/agent-retrieval.

• Report audits in your reply, never into the repo. Give the scorecard,

findings and plan in the response. File them to a tracker only when the user asks and has one.

• Transform only after the user approves the plan.
• Read each reference with its own command. Long output is cut in the

middle, so never concatenate several references in one read.

• Score what exists, not intent. Mark a dimension N/A only when the project

can't expose that surface, and never penalize an optional capability the product doesn't have (MCP metadata without a remote MCP server, OAuth metadata without protected resources, commerce manifests without a commerce flow).

• Check the content, not the file. A .well-known file that returns 200

but points at nothing scores as absent.

• Merge, don't replace, existing AGENTS.md, CLAUDE.md, llms.txt and MCP

files.

• A direct ask gets the artifact. "Write our llms.txt" doesn't need a full

audit: detect narrowly, make it, and say what wasn't audited. An ambiguous "make this agentic" starts with an audit.

Guide

For explanations, comparisons and design decisions, answer from the Agent Surface guide: src/content/docs/ in its own repository, otherwise https://agentsurface.dev/docs (every page has a Markdown twin at <path>.md; the index is https://agentsurface.dev/llms.txt). Read only the pages the question needs. Verify fast-moving standards against primary sources before calling anything current.

Audit

Modes: score (scorecard only), plan (scorecard, findings and plan), transform (plan, then execution), --dimension=<name>, --format=json.

1. Read references/audit-workflow.md first. It holds detection,

applicability, scoring rules, product journeys and every output format.

1. Before scoring a dimension, read its reference. Each holds that dimension's

0-3 rubric, the evidence to gather and the fixes:

1. For a storefront, marketplace or anything agents can buy, read

references/agentic-commerce.md; it informs the dimensions above and is not an eleventh.

1. When delegating dimensions in parallel, give each helper its

agents/score-<dimension>.md prompt.

Monorepos get per-package and aggregate scores. A polyglot repo is scored per surface, reporting the weakest user-facing path. A pure CLI or a project with no web presence isn't penalized for missing public llms.txt; judge its repo-local context files and package metadata.

Scaffold

Modes: init (AGENTS.md, llms.txt, .well-known), api, cli, mcp, tool <name>, test-harness.

Read references/scaffold-workflow.md before generating anything, then the reference for the mode:

A search or retrieval surface needs references/retrievability.md; auth work needs references/authentication.md. For a targeted change in one specialty, also read the matching writer prompt in agents/ (context-writer, discovery-writer, api-optimizer, cli-enhancer, mcp-builder, tool-design-writer, error-designer, auth-upgrader, retrievability-engineer, test-writer).

• Resolve identity server-side. Never accept a user or tenant id as a tool

or API parameter.

• Ship each surface with the first test that proves it works.
• Browsers and sandboxes only to validate a surface, never as a

general-purpose capability.

Standards that models get wrong

• AGENTS.md is the one instruction file. Claude Code reads it when no

CLAUDE.md exists on the path. Add CLAUDE.md only for Claude-only instructions, with @AGENTS.md as its first line; a CLAUDE.md that says "see AGENTS.md" in prose doesn't load it. Other tools' rule files stay thin overlays that point at AGENTS.md.

• `llms.txt` aids inference-time retrieval, not SEO or citation. Pair it

with crawlable docs, structured data, a sitemap and stable canonical URLs.

• MCP `2026-07-28` is current and every Tier 1 SDK supports it. It removes

sessions and the initialize handshake, adds server/discover (servers must implement it) and subscriptions/listen, moves Tasks into an extension, and deprecates roots, sampling and logging. Audit against it; keep 2025-11-25 compatibility only when a real client needs it.

• MCP tools should have input schemas, outputSchema with

structuredContent, annotations, resource links where useful and structured recoverable errors. Annotations and descriptions are hints, not authorization: enforce approvals, auth and scopes in the server.

• Protected remote MCP servers publish RFC 9728 protected-resource

metadata and validate issuer, audience, expiry and scopes on every request. DPoP (RFC 9449) is separate; claim it only when implemented.

• WebMCP (document.modelContext) is a browser-native draft for

page-scoped tools, distinct from remote MCP and the old webmcp.dev library.

• Claude model IDs, context limits and beta headers change often. Check the

Claude Platform release notes before hard-coding them.