# Surface Audit

> Score whether an API, SDK, or documentation surface can actually be used by developers and AI agents, then rank the gaps by impact. Audits the API contract, documentation, time-to-first-value, SDKs and examples, MCP tooling, auth and permissions, and observability, and writes a report with a remediation sequence. Works on a local repo, an OpenAPI or GraphQL schema, a docs directory, or a public developer site. Use when asked whether a product is agent-ready or developer-ready, to audit or score a developer surface, to find adoption or integration friction, or to review an API before exposing it to AI agents.

- Skill: `agentrel/surface-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add agentrel/surface-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agentrel/surface-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: agentrel (https://skillmd.com/u/agentrel)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agentrel/surface-audit

---


# Surface audit

Score a developer surface across seven core dimensions and three conditional ones, then
produce a ranked remediation sequence. Read-only: never modify the audited project.

Load `references/rubric.md` before scoring. It holds the per-dimension criteria and the
band definitions. Do not score from memory — the rubric is the contract, and consistent
scores across runs are the point of this skill.

## Applies to

| | |
|---|---|
| **Project types** | REST or GraphQL APIs, SDKs, developer platforms, internal services being opened up to other teams |
| **Stage** | Any stage with a callable surface. Highest value before an integration push, before exposing anything to agents, or when adoption has stalled with no obvious cause |
| **Needs** | A repository, or a public docs URL plus a reachable spec |
| **Skip if** | There is no API or SDK yet — there is nothing to score. Or you want one dimension in depth, in which case run that skill directly |

Works on a partial surface. Missing artifacts are findings, not blockers, so an early-stage
product gets a useful report — it just gets a low one.

## How to use

```
/agentrel:surface-audit                          audit the current repository
/agentrel:surface-audit ./packages/api           audit a subdirectory
/agentrel:surface-audit https://docs.acme.com    audit a public surface
```

Takes a few minutes. Produces `surface-audit-report.md` plus a printed score table.
Read-only — nothing in the audited project is modified.

A remote audit sees less than a repository audit. Run it against the repo where you can.

## 1. Establish scope

Identify what you are auditing before you score anything. Ask the user only if the target
is genuinely ambiguous after looking.

| Signal | Where to look |
|--------|---------------|
| API contract | `openapi.{json,yaml}`, `swagger.*`, `schema.graphql`, `*.proto`, a `/docs` or `/openapi.json` route |
| Documentation | `docs/`, `README.md`, a docs site URL, `mint.json`, `docusaurus.config.*`, `fern.config.json` |
| SDKs | `packages/`, `sdks/`, published package names in the README |
| Agent surface | `.mcp.json`, `mcp.json`, an `mcp` directory, a `server.ts` exposing `ListTools` |
| Examples | `examples/`, `samples/`, `*.postman_collection.json` |

Record what you found and, critically, **what is absent**. An absent artifact is a finding,
not a blocker.

If the target is a public site rather than a repo, use `WebFetch` on the docs root and the
OpenAPI URL. Say so in the report — a remote audit sees less than a repo audit and the
report must not imply otherwise.

## 2. Score each dimension

Seven core dimensions are always scored. Three conditional dimensions are scored **only
when the product's business model calls for them**, and otherwise marked `n/a` with a
one-line reason.

**Core**

| # | Dimension | Asks |
|---|-----------|------|
| 1 | API contract | Is the interface described precisely enough to generate a correct call? |
| 2 | Documentation | Can a stranger understand what this does and how to use it? |
| 3 | Time to first value | How far is a cold developer from a working call? |
| 4 | SDKs and examples | Is there a paved path, or only a specification? |
| 5 | Agent tooling | Can an autonomous agent discover, select, and call these capabilities? |
| 6 | Auth and permissions | Are boundaries explicit, scoped, and enforceable? |
| 7 | Observability | When an integration fails, can the developer tell why? |

**Conditional** — mark `n/a` unless the product genuinely needs them

| # | Dimension | Score only when |
|---|-----------|-----------------|
| 8 | Agent collaboration | The product is one participant in a multi-agent workflow |
| 9 | Agentic commerce | It is a metered digital service an agent could legitimately buy |
| 10 | Community and education | The product depends on an external developer ecosystem |

Marking a conditional dimension `n/a` is the correct and common outcome. Never inflate an
overall score by scoring a dimension the product has no reason to implement, and never
imply a product is deficient for not shipping a protocol it does not need.

Score each dimension 0–100 using the bands in the rubric. For every dimension record:

- the score and the band name
- the specific evidence, as `file:line` or a URL — never a general impression
- each gap, with its severity and the fix

**If a dimension cannot be assessed, emit `n/a` and say why.** Never estimate a score from
partial evidence. A tool that invents numbers is worse than no tool.

## 3. Rank the gaps

Order gaps by remediation value, not by severity alone. A blocking gap that takes a quarter
ranks below three moderate gaps that take a day each.

```
value = (severity × dimension_weight) ÷ effort
```

Dimension weights live in the rubric. Effort is `S` (hours), `M` (days), `L` (weeks).

Group the ranked output into three waves, and state the dependency when one gap blocks
another — fixing docs before the API contract is settled wastes the work.

## 4. Write the report

Write `surface-audit-report.md` in the working directory with these sections, in order:

1. **Scope** — what was audited, what was reachable, what was not
2. **Score table** — every dimension, score, band, gap count
3. **Dimension detail** — evidence and gaps per dimension
4. **Remediation sequence** — the three waves with effort and dependencies
5. **Method** — rubric version, date, and the limits of this run

Then print this summary to the conversation. Keep the format exact; other tools parse it.

```
DIMENSION                SCORE   GAPS
API contract                78      3
Documentation               73      4
Time to first value         52      6
SDKs and examples           64      3
Agent tooling               41      7
Auth and permissions        70      2
Observability               58      4
Agent collaboration        n/a      –
Agentic commerce           n/a      –
Community and education     45      5

Overall                  60/100
Report → ./surface-audit-report.md
```

Overall is the mean of scored dimensions only. Conditional dimensions marked `n/a` are
excluded from the mean — they neither help nor hurt.

## 5. Close honestly

End with the single highest-value fix and its effort. One sentence, no upsell.

If the surface scores above 85 overall, say so plainly and do not manufacture concerns.
A clean audit is a legitimate result and reporting it accurately is what makes the low
scores credible.

## Notes

- **MCP dimension**: if `mcpx` is installed, run it and fold its grade into dimension 5
  rather than duplicating its checks. Degrade gracefully when absent — never require it.
- **Never write to the audited project.** This skill produces one report file in the
  working directory and nothing else.
- **No network calls other than fetching the audit target.** No telemetry, no submission,
  no phoning home.