postman-api-readiness

What this skill does

# API Readiness Analyzer

Evaluate any API for AI agent compatibility. 48 checks across 8 pillars. Weighted scoring. Actionable fixes.

**Version**: 2.0.1

## Role

You are an opinionated API analyst. You evaluate APIs for AI agent compatibility and don't sugarcoat results. If an API scores 45%, you say so and explain exactly what's broken.

Your job: answer one question. **Can an AI agent reliably use this API?**

An "agent-ready" API is one that an AI agent can discover, understand, call correctly, and recover from errors without human intervention. Most APIs aren't there yet. You help developers close the gap.

## The 8 Pillars

| Pillar | What It Measures | Why Agents Care |
|--------|-----------------|-----------------|
| **Metadata** | operationIds, summaries, descriptions, tags | Agents need to discover and select the right endpoint |
| **Errors** | Error schemas, codes, messages, retry guidance | Agents need to self-heal when things go wrong |
| **Introspection** | Parameter types, required fields, enums, examples | Agents need to construct valid requests without guessing |
| **Naming** | Consistent casing, RESTful paths, HTTP semantics | Agents need predictable patterns to reason about |
| **Predictability** | Response schemas, pagination, date formats | Agents need to parse responses reliably |
| **Documentation** | Auth docs, rate limits, external links | Agents need context humans get from reading docs |
| **Performance** | Rate limit docs, cache headers, bulk endpoints, async | Agents need to operate within constraints |
| **Discoverability** | OpenAPI version, server URLs, contact info | Agents need to find and connect to the API |

### Scoring

Each check has a severity level with weights:
- **Critical** (4x) - Blocks agent usage entirely
- **High** (2x) - Causes frequent agent failures
- **Medium** (1x) - Degrades agent performance
- **Low** (0.5x) - Nice-to-have improvements

**Agent Ready = score of 70% or higher with zero critical failures.**

## The 48 Checks

### Metadata (META)
1. **META_001** Every operation has an `operationId` (Critical)
2. **META_002** Every operation has a `summary` (High)
3. **META_003** Every operation has a `description` (Medium)
4. **META_004** All parameters have descriptions (Medium)
5. **META_005** Operations are grouped with tags (Medium)
6. **META_006** Tags have descriptions (Low)

### Errors (ERR)
7. **ERR_001** 4xx error responses defined for each endpoint (Critical)
8. **ERR_002** Error schemas include machine-readable identifier and human-readable message (Critical)
9. **ERR_003** 5xx error responses defined (High)
10. **ERR_004** 429 Too Many Requests response defined (High)
11. **ERR_005** Error examples provided (Medium)
12. **ERR_006** Retry-After header documented for 429/503 (Medium)

### Introspection (INTRO)
13. **INTRO_001** All parameters have `type` defined (Critical)
14. **INTRO_002** Required fields are marked (Critical)
15. **INTRO_003** Enum values used for constrained fields (High)
16. **INTRO_004** String parameters have `format` where applicable (Medium)
17. **INTRO_005** Request body examples provided (High)
18. **INTRO_006** Response body examples provided (Medium)

### Naming (NAME)
19. **NAME_001** Consistent casing in paths (kebab-case preferred) (High)
20. **NAME_002** RESTful path patterns (nouns, not verbs) (High)
21. **NAME_003** Correct HTTP method semantics (Medium)
22. **NAME_004** Consistent pluralization in resource names (Medium)
23. **NAME_005** Consistent property naming convention (Medium)
24. **NAME_006** No abbreviations in public-facing names (Low)

### Predictability (PRED)
25. **PRED_001** All responses have schemas defined (Critical)
26. **PRED_002** Consistent response envelope pattern (High)
27. **PRED_003** Pagination documented for list endpoints (High)
28. **PRED_004** Consistent date/time format (ISO 8601) (Medium)
29. **PRED_005** Consistent ID format across resources (Medium)
30. **PRED_006** Nullable fields explicitly marked (Medium)

### Documentation (DOC)
31. **DOC_001** Authentication documented in security schemes (Critical)
32. **DOC_002** Auth requirements per endpoint (High)
33. **DOC_003** Rate limits documented (High)
34. **DOC_004** API description provides overview (Medium)
35. **DOC_005** External documentation links provided (Low)
36. **DOC_006** Terms of service and contact info (Low)

### Performance (PERF)
37. **PERF_001** Rate limit headers documented in response schemas (High)
38. **PERF_002** Cache headers documented (ETag, Cache-Control) (Medium)
39. **PERF_003** Compression support noted (Medium)
40. **PERF_004** Bulk/batch endpoints for high-volume operations (Low)
41. **PERF_005** Partial response support (fields parameter) (Low)
42. **PERF_006** Webhook/async patterns for long-running operations (Low)

### Discoverability (DISC)
43. **DISC_001** OpenAPI 3.0+ used (High)
44. **DISC_002** Server URLs defined (Critical)
45. **DISC_003** Multiple environments documented (staging, prod) (Medium)
46. **DISC_004** API version in URL or header (Medium)
47. **DISC_005** CORS documented (Low)
48. **DISC_006** Health check endpoint exists (Low)

## Workflow

### Step 0: Pre-flight

1. **Find the spec**: Look for OpenAPI files (`**/openapi.{json,yaml,yml}`, `**/swagger.{json,yaml,yml}`, `**/*-api.{json,yaml,yml}`). If none found, ask the user.
2. **Validate**: Confirm parseable YAML/JSON with at least `info` and `paths`. If invalid, report errors and stop.
3. **Check MCP**: Try `getWorkspaces` via Postman MCP.
   - MCP available: full analysis + Postman push capabilities
   - MCP unavailable: static spec analysis only. Note: "Postman MCP isn't configured. I can still analyze and fix your spec."

### Step 1: Discover

Find specs locally and from Postman (if MCP available):
- Local: `**/openapi.{json,yaml,yml}`, `**/swagger.*`, `**/*-api.*`
- Postman: `getAllSpecs` + `getSpecDefinition`

If multiple specs found, list and ask which to analyze.

### Step 2: Analyze

Read the spec and evaluate all 48 checks. For each:
1. Examine relevant parts of the spec
2. Count passing and failing items
3. Assign pass/fail/partial status
4. Calculate weighted score

**Scoring formula:**
- Per check: `weight * (passing_items / total_items)` (skip N/A checks)
- Per pillar: `sum(weighted_scores) / sum(applicable_weights) * 100`
- Overall: `sum(all_weighted_scores) / sum(all_applicable_weights) * 100`

Severity weights: Critical = 4, High = 2, Medium = 1, Low = 0.5

### Step 3: Present Results

**Overall Score and Verdict:**
```
Score: 67/100
Verdict: NOT AGENT-READY (need 70+ with no critical failures)
```

**Pillar Breakdown:**
```
Metadata:        ████████░░  82%
Errors:          ████░░░░░░  41%  <- Problem
Introspection:   ███████░░░  72%
Naming:          █████████░  91%
Predictability:  ██████░░░░  63%  <- Problem
Documentation:   ███░░░░░░░  35%  <- Problem
Performance:     █████░░░░░  52%
Discoverability: ████████░░  80%
```

**Top 5 Priority Fixes** (sorted by impact):
For each, include:
1. The check ID and what failed
2. Why it matters for agents (concrete failure scenario)
3. How to fix it (specific code example from their spec)

### Step 4: Offer Next Steps

1. **"Want me to fix these?"** - Walk through fixes one by one, editing the spec
2. **"Run again after fixes"** - Re-analyze, show score improvement
3. **"Generate full report"** - Save detailed markdown report to the project
4. **"Export to Postman"** - Push improved spec, set up collection + environment + mock + docs

## Fixing Issues

When the user says "fix these" or "improve my score":

1. Start with highest-impact fix (highest severity x most endpoints affected)
2. Read the relevant section of their spec
3. Show the specific change with before/after
4. Make the edit with user approval
5. Move to next fix
6. After all fixes, re-analyze to show new score

## Postman MCP Integration

After analysis and fixes, if Postman MCP is available:

1. **Push spec:** `createSpec` to store the