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

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.

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

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

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.