timbenniks/timbenniks-agent-skills
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
FAQ
No. The audit diagnoses gaps and prescribes concrete fixes; it does not generate client libraries.
What if I only have human-readable REST docs?
I will build an endpoint inventory from the docs and highlight missing schema/auth/error details, then propose a minimal OpenAPI skeleton.
