agentsclimarketplace
Sign in

Api contract audit

Skill VictorAurelius/claude-starter-kit/skills/quality/api-contract-audit

Dùng khi user nói 'api audit', 'contract check', 'kiểm tra API', 'endpoint match docs?', 'breaking change?', hoặc trước release. Verify API endpoints match api-contract.md /100.From its SKILL.md

Install
npx -y skills add VictorAurelius/claude-starter-kit --skill api-contract-audit

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
  • runs commandsInstructs the agent to run 4 commands, including `grep -rn "@GetMapping\|@PostMapping\|@PutMapping\|@DeleteMapping\|@PatchMapping\|@RequestMapping" --include="*.java" src/main/ | grep -v test` and 3 more.

SKILL.md

5.0 KB, ~1.3k tokens by cl100k_base, as published. Nobody here has run it

/api-contract-audit — API ↔ Documentation Sync

Score /100. Verify every controller endpoint is documented and every documented endpoint exists in code. Adapt <module> / <modules> placeholders to your project layout.

Process

1. Extract Endpoints from Code

# Controllers in a single module
grep -rn "@GetMapping\|@PostMapping\|@PutMapping\|@DeleteMapping\|@PatchMapping\|@RequestMapping" \
  --include="*.java" src/main/ | grep -v test

# Controllers across all modules (multi-module project)
grep -rn "@GetMapping\|@PostMapping\|@PutMapping\|@DeleteMapping" \
  --include="*.java" <modules>/*/src/main/ | grep -v test

2. Extract Endpoints from Docs

# API contract docs (3-layer business docs convention)
grep -rn "^### \|^## \|GET \|POST \|PUT \|DELETE \|PATCH " \
  documents/01-business/*/api-contract.md | head -50

3. Primacy: bug-finding > scoring (BLOCKING)

An audit's purpose is to surface API-contract drift BEFORE consumers (mobile app, third-party integrations, partners) hit it. A /100 score with hidden undocumented endpoints is WORSE than a low score listing each with Controller.java:line evidence. Per .claude/rules/audit-skill-rubric-api-contract-audit.md §4 (mirror of the security-audit bug-finding-primacy pattern).

Rules for every audit run:

  1. Enumerate ALL §4 sub-checks per category. NEVER skip "obviously fine."
  2. Each sub-check returns: PASS / FAIL / N/A-with-reason / ❓ UNCHECKED. No partial credit.
  3. Final output starts with bug list (every undocumented/drifted endpoint with file:line + severity) BEFORE the score.
  4. Score is descriptive only; audit-level verdict = FAIL if ANY P0 sub-check FAILS.
  5. If audit time-budget runs out, mark ❓ UNCHECKED — do NOT default to PASS.

4. Score 5 Categories with per-check rubric

Every category binds to a per-check pass/fail rule.

#Category (20pts)Per-check rubric file
1Endpoint Coverage.claude/rules/audit-skill-rubric-api-contract-audit.md §2.1 (6 sub-checks)
2Request/Response Match.claude/rules/audit-skill-rubric-api-contract-audit.md §2.2 (6 sub-checks)
3Error Code Consistency.claude/rules/audit-skill-rubric-api-contract-audit.md §2.3 (5 sub-checks)
4Versioning & Deprecation.claude/rules/audit-skill-rubric-api-contract-audit.md §2.4 (5 sub-checks)
5Integration Test Coverage.claude/rules/audit-skill-rubric-api-contract-audit.md §2.5 (5 sub-checks)

Per-check scoring (all 5 categories)

For each Category N:

  1. Walk through every §2 sub-check in the bound rule.
  2. Mark each sub-check PASS / FAIL / N/A-with-reason / ❓ UNCHECKED.
  3. Score = 20 - (failed_P0_count * 6) - (failed_P1_count * 3) - (failed_P2_count * 1), floor 0; cap 20 if all PASS.
  4. If ANY P0 sub-check fails → category total CAPPED at 16/20 AND audit-level verdict = FAIL.
  5. Each FAIL surfaces in bug list per §3 primacy.

Legacy scoring narrative: reference/scoring-guide.md retained for backward-compat only.

5. Output

Save to documents/audits/api-contract-audit-[date].md

Format: 2-column table per domain — Code endpoints | Doc endpoints — highlight mismatches.

Context Management

Token budget ~30-45K. Multi-microservice projects có thể tạo output rất lớn. Kiểm soát:

  1. Grep output limiting — LUÔN | head -30 per service. Tổng controller grep cho nhiều services nếu không limit = 200+ lines.
  2. Per-service delegation — Nếu >4 microservices, chia subagent theo nhóm service:
    • Agent 1: core module (1 service)
    • Agent 2: remaining services
    • Mỗi agent: extract endpoints → compare với api-contract.md → trả mismatch list
  3. Diff-based audit — Sau baseline, chỉ check endpoints trong files changed since last audit: 
    git diff main --name-only | grep -E 'Controller\.java|api-contract\.md'
  4. Mismatch-first output — KHÔNG list tất cả endpoints khớp. Chỉ output mismatches + summary count.

Gotchas

  • Gateway routes (/api/v1/**) proxy to backend services — check gateway config for actual public paths
  • Multi-microservice projects — check ALL service controllers, not just one
  • Public endpoints (no auth): /public/** — documented differently from authenticated ones
  • Websocket/SSE endpoints may not follow REST pattern — document separately
  • Controller grep output for many services rất lớn — LUÔN limit per service
  • Multi-module scope — single-module greps miss controllers in sibling modules. If adding a new service module, update grep paths OR switch to broad --include="*.java" from repo root.

Skill Contents

  • reference/scoring-guide.md — Detailed rubric per category

What ships with it: 1 file

3.2 KB alongside SKILL.md

reference/

Gives 0 of the 12 instructions most quality gates skills give in ~1.3k tokens

Counted across 1,524 of the 2,830 authors here whose files we hold, read 2026-09-06

  • Read full output and check exit codein 45 of 1524, across 40 files
  • Verify output confirms the claimin 44 of 1524, across 39 files
  • Identify the command that proves the claimin 43 of 1524, across 39 files
  • Execute the full verification commandin 36 of 1524, across 30 files
  • Produce a verification reportin 34 of 1524, across 18 files
  • Review git diff changesin 30 of 1524, across 16 files
  • Fix build failures immediatelyin 29 of 1524, across 9 files
  • Group findings by severityin 28 of 1524
  • State claim only with evidencein 27 of 1524, across 22 files
  • Verify regression tests with red-green cyclein 26 of 1524, across 22 files
  • Run the full test suitein 26 of 1524, across 25 files
  • Run test suite with coveragein 25 of 1524, across 10 files

Said here and by no other author read

  • Enumerate all sub-checks per category
  • Save audit report to the designated documents directory
  • List undocumented or drifted endpoints with file and line
  • Mark unchecked items as UNCHECKED
  • Output bug list before the score
  • Limit grep output to thirty lines per service

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.