speakeasy-api

improve-operation-ids

@speakeasy-api/improve-operation-ids
speakeasy-api
377
30 forks
Updated 1/18/2026
View on GitHub

Use when SDK methods have auto-generated names like GetApiV1Users, or wanting `sdk.users.list()` style naming

Installation

$skills install @speakeasy-api/improve-operation-ids
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

Repositoryspeakeasy-api/speakeasy
Pathskills/improve-operation-ids/SKILL.md
Branchmain
Scoped Name@speakeasy-api/improve-operation-ids

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions

name: improve-operation-ids description: Use when SDK methods have auto-generated names like GetApiV1Users, or wanting sdk.users.list() style naming

improve-operation-ids

Check Current State

speakeasy suggest operation-ids -s openapi.yaml

SDK Method Naming

Speakeasy generates grouped SDK methods using x-speakeasy-group:

HTTP MethodSDK UsageOperation ID
GET (list)sdk.users.list()users_list
GET (single)sdk.users.get()users_get
POSTsdk.users.create()users_create
PUTsdk.users.update()users_update
PATCHsdk.users.patch()users_patch
DELETEsdk.users.delete()users_delete

Use x-speakeasy-group: users and x-speakeasy-name-override: list to achieve this grouping.

Apply Suggestions

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

# Add to workflow and regenerate
speakeasy run

Manual Override

overlay: 1.0.0
info:
  title: Custom operation names
  version: 1.0.0
actions:
  - target: "$.paths['/api/v1/users'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: listAll

This produces: sdk.users.listAll()

More by speakeasy-api

View all
apply-openapi-overlay
377

Use when applying an overlay file to a spec

get-ai-suggestions
377

Use when SDK method names are ugly, wanting to improve operation IDs, or asking "how can I improve my spec"

merge-openapi-specs
377

Use when combining multiple OpenAPI specs, or have microservices with separate spec files

validate-openapi-spec
377

Use when checking if an OpenAPI spec is valid, looking for errors, or running `speakeasy lint`