Terminal
Terminal/Skill
Uses the speakeasy suggest command to get AI suggestions for clearer SDK method names and error types, saved as an optional overlay.
By Speakeasy
Works with
npx skills add speakeasy-api/sdk-generation-skills --skill improve-sdk-namingImprove 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.
Use this skill when you want AI-powered suggestions from Speakeasy:
GetApiV1Usersspeakeasy suggestNOT for: Manually creating overlays (see manage-openapi-overlays instead)
| 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) |
| Output | Description |
|---|---|
| Suggestions | Better operation names or error types printed to console |
| Overlay file | Optional: saves suggestions as an overlay YAML file (-o) |
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
# 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
Run the suggest command without -o to preview what would change:
speakeasy suggest operation-ids -s openapi.yaml
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.
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 -> listUserspost_api_v1_users_create -> createUserThe 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.
sources:
my-api:
inputs:
- location: ./openapi.yaml
overlays:
- location: ./operation-ids-overlay.yaml
speakeasy run --output console
The suggest error-types command analyzes your API and suggests structured error responses:
speakeasy suggest error-types -s openapi.yaml
This suggests:
Output as an overlay:
speakeasy suggest error-types -s openapi.yaml -o error-types-overlay.yaml
get or post without a group. Always pair x-speakeasy-name-override with x-speakeasy-group.workflow.yaml after creating it. Without this step, the names will not change in the generated SDK.{group}_{method} combination must be unique.| 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 |