sdk-readiness-audit_skill

Overview

This skill audits an API surface (OpenAPI 3.0/3.1, GraphQL schema, or REST docs) for SDK readiness and developer experience. It diagnoses gaps, produces a prioritized scorecard, lists concrete refactors, and suggests OpenAPI fixes and x-* extensions. The audit does not generate an SDK; it shows what must change to make SDKs reliable and pleasant to use.

How this skill works

I parse the provided source of truth (OpenAPI/GraphQL/REST docs), build an endpoint and schema inventory, then evaluate each area against a weighted rubric to produce a score and actionable recommendations. The output includes a readiness verdict, per-category evidence, prioritized refactors (P0/P1/P2), likely developer pain points if an SDK is shipped today, and specific OpenAPI/x-* changes. Please answer these intake questions in one concise block: 1) Source of truth: OpenAPI URL or local path, GraphQL SDL/introspection, or REST docs link/markdown; 2) Target SDK consumers: primary languages/platforms and top workflows; 3) Auth and environments: auth methods, token types, prod/sandbox; 4) Known pain points: current client friction or support issues.

When to use it

• Before investing in generating or maintaining official SDKs
• When deciding whether an API is ready for public client libraries
• To prioritize spec fixes that improve client generator output
• During API design reviews to ensure consistent SDK-friendly patterns
• When onboarding SDK engineers to surface ambiguous or missing behaviours

Best practices

• Provide a single source of truth (OpenAPI or introspection) and keep it authoritative
• Define consistent error schema (Problem Details) and document retry semantics
• Standardize pagination, auth, and idempotency with clear spec fields or x-* flags
• Use operationId, tags, and examples to produce stable method names and docs
• Call out unknowns explicitly and avoid guessing—request missing inputs

Example use cases

• Audit an OpenAPI file to generate a prioritized list of spec fixes and x-* extensions for client generation
• Evaluate a GraphQL schema for pagination, input design, enums, and nullability issues before building SDKs
• Turn REST markdown docs into an endpoint inventory and identify missing auth/error details
• Produce a ‘what would hurt’ list if an SDK shipped today to inform product risk decisions
• Create a readiness scorecard to track improvements across sprints