get-ai-suggestions

name	get-ai-suggestions
description	Use when SDK method names are ugly, wanting to improve operation IDs, or asking "how can I improve my spec"

get-ai-suggestions

Use speakeasy suggest for AI-powered improvements.

Prerequisites

For non-interactive environments (CI/CD, AI agents), set:

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

See configure-authentication skill for details.

Commands

# Suggest better operation IDs (method names)
speakeasy suggest operation-ids -s <spec-path>

# Suggest error type definitions
speakeasy suggest error-types -s <spec-path>

# Output suggestions as overlay file
speakeasy suggest operation-ids -s <spec-path> -o suggested-overlay.yaml

Operation ID Suggestions

Transforms auto-generated names into intuitive SDK method names:

• get_api_v1_users_list → listUsers
• post_api_v1_users_create → createUser

Error Type Suggestions

Analyzes your API and suggests structured error responses:

• Common HTTP error codes (400, 401, 404, 500)
• Custom error schemas

Applying Suggestions

# Generate overlay with suggestions
speakeasy suggest operation-ids -s openapi.yaml -o operation-ids-overlay.yaml

# Add to workflow.yaml
sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./operation-ids-overlay.yaml

# Regenerate
speakeasy run