Learn-skills.dev api-audit

Audit API routes against shared types — scan routes, plugins, and types for mismatches. Read-only, no changes. Use before PRs, after adding routes, or for periodic API contract validation.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/acedergren/agentic-tools/api-audit" ~/.claude/skills/neversight-learn-skills-dev-api-audit && rm -rf "$T"

manifest: data/skills-md/acedergren/agentic-tools/api-audit/SKILL.md

source content

API Route & Type Audit Skill

Scan API routes and plugins, catalog every endpoint, and cross-reference against type definitions to find mismatches. Read-only — do not modify any files.

Steps

1. Scan Route Files

Scan your routes directory recursively. For each route registration, extract:

HTTP method (GET, POST, PUT, PATCH, DELETE)
Path (e.g.,
```
/api/users
```
,
```
/api/admin/settings
```
)
Auth requirements (public, session-required, RBAC permissions)
Request schema (Zod/validation schema name, if defined)
Response schema (Zod/validation schema name, if defined)

Look for framework-specific patterns (e.g., Fastify schema objects, Express middleware chains, Next.js route handlers).

2. Scan Plugin/Middleware Files

Scan middleware or plugin directories for:

Auth middleware registration (which routes get auth protection)
Permission mappings
Rate limiting configurations per route
Any route-level decorators or hooks

3. Catalog Shared Types

Scan type definition directories for:

Validation schemas used as request/response validators
TypeScript interfaces/types that correspond to API payloads
Exported schema names and their shapes

4. Cross-Reference and Detect Mismatches

Category	What to check
Missing schemas	Routes without request/response validation
Type drift	Route handler using a type that differs from the shared schema
Orphan types	Schemas in types package not referenced by any route
Auth gaps	Routes missing auth hooks that should have them (e.g., `/admin/*` )

5. Report Findings

Output a markdown table grouped by severity:

Critical: Auth gaps, missing validation on mutation endpoints
Warning: Type drift, missing response schemas
Info: Orphan types, routes with inline schemas that could use shared ones

Include summary counts: total routes, full coverage, partial coverage, no validation, mismatches.

Arguments

```
$ARGUMENTS
```
: Optional scope filter
- Example:
```
/api-audit admin
```
  — only audit admin routes
- If empty, audit all routes

Execution Strategy

Use two parallel Explore agents for speed:

Agent A: Scan routes + plugins — catalog all endpoints
Agent B: Scan types directories — catalog all shared schemas

Then synthesize their findings into the cross-reference table.

Key Rules

Read-only — do not create, modify, or delete any files
Be specific — report exact file paths and line numbers
No false positives — only report genuine mismatches
Include context — show the relevant type/schema snippet for each mismatch