speakeasy-api/skills/improve-sdk-naming

improve-sdk-naming

Improve SDK method naming using AI-powered suggestions or manual overrides. Covers both automatic speakeasy suggest commands and manual naming with x-speakeasy-group and x-speakeasy-name-override extensions.

When to Use

Use this skill when you want AI-powered suggestions from Speakeasy:

• SDK methods have ugly auto-generated names like GetApiV1Users
• You want Speakeasy AI to suggest better operation IDs
• You want AI-generated suggestions for error types
• Looking to improve spec quality automatically using speakeasy suggest
• User says: "suggest improvements", "speakeasy suggest", "AI suggestions", "suggest operation-ids", "suggest error-types", "get AI recommendations"

NOT for: Manually creating overlays (see manage-openapi-overlays instead)

Inputs

Outputs

Prerequisites

For non-interactive environments (CI/CD, AI agents), set the API key as an environment variable:

export SPEAKEASY_API_KEY="<your-api-key>"

For interactive use, authenticate directly:

speakeasy auth login

Command

AI-Powered Suggestions

# Suggest better operation IDs (SDK method names)
speakeasy suggest operation-ids -s <spec-path>
 
# Suggest error type definitions
speakeasy suggest error-types -s <spec-path>
 
# Output suggestions as an overlay file
speakeasy suggest operation-ids -s <spec-path> -o suggested-overlay.yaml

Check Current Operation IDs

Run the suggest command without -o to preview what would change:

speakeasy suggest operation-ids -s openapi.yaml

SDK Method Naming Convention

Speakeasy generates grouped SDK methods from operation IDs. The naming convention uses x-speakeasy-group for the namespace and x-speakeasy-name-override for the method name.

The operation ID format is {group}_{method}. Speakeasy splits on the underscore to create the namespace and method name in the generated SDK.

Example

Step 1: Get AI Suggestions

speakeasy suggest operation-ids -s openapi.yaml -o operation-ids-overlay.yaml

This analyzes your spec and generates an overlay that transforms names like:

• get_api_v1_users_list -> listUsers
• post_api_v1_users_create -> createUser

Step 2: Review and Apply the Overlay

The AI-generated overlay (from -o) creates naming improvements using x-speakeasy-group and x-speakeasy-name-override.

Note: For manual overlay creation, use the manage-openapi-overlays skill instead of this skill.

Step 3: Add the Overlay to workflow.yaml

sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./operation-ids-overlay.yaml

Step 4: Regenerate the SDK

speakeasy run --output console

Error Type Suggestions

The suggest error-types command analyzes your API and suggests structured error responses:

speakeasy suggest error-types -s openapi.yaml

This suggests:

• Common HTTP error codes (400, 401, 404, 500)
• Custom error schemas appropriate for your API

Output as an overlay:

speakeasy suggest error-types -s openapi.yaml -o error-types-overlay.yaml

What NOT to Do

• Do NOT modify operationIds directly in the source spec if it is externally managed. Use overlays instead.
• Do NOT use generic names like get or post without a group. Always pair x-speakeasy-name-override with x-speakeasy-group.
• Do NOT forget to add the generated overlay to workflow.yaml after creating it. Without this step, the names will not change in the generated SDK.
• Do NOT create duplicate operation names across different groups. Each {group}_{method} combination must be unique.

Troubleshooting