improve-sdk-naming_skill

Overview

This skill improves SDK method naming by providing AI-powered suggestions and manual overlay controls to replace ugly auto-generated operation IDs. It produces suggested operation names, grouped namespaces, and optional overlay YAML that you can apply to your OpenAPI workflow. Use it to get consistent, human-friendly SDK method names and structured error type recommendations.

How this skill works

The skill analyzes your OpenAPI spec and proposes better operation IDs and error type schemas using an AI suggestion engine. It can emit suggestions to the console or write an overlay YAML that sets x-speakeasy-group and x-speakeasy-name-override on operations. Apply the overlay in your workflow and regenerate the SDK to produce grouped methods like sdk.users.list().

When to use it

• Operation IDs are ugly or auto-generated (e.g., GetApiV1Users).
• You want grouped SDK methods like sdk.users.list() instead of flat names.
• You need AI suggestions for operation IDs or API error types.
• You prefer applying non-destructive overlays instead of editing the source spec.
• You are preparing an SDK for public consumption and want consistent naming.

Best practices

• Run suggestions first without -o to preview changes before applying an overlay.
• Use overlays to avoid modifying a source spec that’s externally managed.
• Always set both x-speakeasy-group and x-speakeasy-name-override together to avoid generic names.
• Add the generated overlay to workflow.yaml so changes persist for future SDK generation.
• Avoid duplicate {group}_{method} combinations; ensure uniqueness across groups.

Example use cases

• Convert get_api_v1_users_list -> sdk.users.list() via AI suggestions and overlay.
• Create an overlay that maps CRUD endpoints to users.{list,get,create,update,delete}.
• Suggest structured error types (400/401/404/500) and output as an overlay for consistent error handling.
• Preview suggested name changes in CI before committing overlays to a repo.
• Use suggestions to standardize operation IDs across multiple microservice specs.