Agent 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

| Input | Required | Description | |-------|----------|-------------| | OpenAPI spec | Yes | Path to the spec file (-s) | | Authentication | Yes | Via speakeasy auth login or SPEAKEASY_API_KEY env var | | Output file | No | Path for overlay output (-o) |

Outputs

| Output | Description | |--------|-------------| | Suggestions | Better operation names or error types printed to console | | Overlay file | Optional: saves suggestions as an overlay YAML file (-o) |

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.

| HTTP Method | SDK Usage | Operation ID | |-------------|-----------|--------------| | GET (list) | sdk.users.list() | users_list | | GET (single) | sdk.users.get() | users_get | | POST | sdk.users.create() | users_create | | PUT | sdk.users.update() | users_update | | DELETE | sdk.users.delete() | users_delete |

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

| Error | Cause | Solution | |-------|-------|----------| | "unauthorized" | Missing or invalid API key | Set SPEAKEASY_API_KEY env var or run speakeasy auth login | | Names unchanged after regeneration | Overlay not added to workflow | Add the overlay to the overlays list in workflow.yaml | | No suggestions returned | Spec already has good naming | No action needed; names are already well-structured | | Duplicate method names | Similar endpoints share names | Use unique x-speakeasy-name-override values for each endpoint | | Timeout during suggest | Very large spec | Try running on a smaller subset or increase timeout |