# Improve Sdk Naming

> Use when you want AI-powered suggestions for SDK naming improvements via the `speakeasy suggest` command (not manual overlay creation). Triggers on "suggest improvements", "speakeasy suggest", "AI suggestions", "suggest operation-ids", "suggest error-types", "auto-improve naming", "get AI recommendations".

- **Type:** Skill
- **Install:** `agentstack add skill-speakeasy-api-skills-improve-sdk-naming`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [speakeasy-api](https://agentstack.voostack.com/s/speakeasy-api)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [speakeasy-api](https://github.com/speakeasy-api)
- **Source:** https://github.com/speakeasy-api/skills/tree/master/skills/improve-sdk-naming
- **Website:** https://www.speakeasy.com/docs

## Install

```sh
agentstack add skill-speakeasy-api-skills-improve-sdk-naming
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
export SPEAKEASY_API_KEY=""
```

For interactive use, authenticate directly:

```bash
speakeasy auth login
```

## Command

### AI-Powered Suggestions

```bash
# Suggest better operation IDs (SDK method names)
speakeasy suggest operation-ids -s 

# Suggest error type definitions
speakeasy suggest error-types -s 

# Output suggestions as an overlay file
speakeasy suggest operation-ids -s  -o suggested-overlay.yaml
```

### Check Current Operation IDs

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

```bash
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

```bash
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

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

### Step 4: Regenerate the SDK

```bash
speakeasy run --output console
```

## Error Type Suggestions

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

```bash
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:

```bash
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 |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [speakeasy-api](https://github.com/speakeasy-api)
- **Source:** [speakeasy-api/skills](https://github.com/speakeasy-api/skills)
- **License:** Apache-2.0
- **Homepage:** https://www.speakeasy.com/docs

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-speakeasy-api-skills-improve-sdk-naming
- Seller: https://agentstack.voostack.com/s/speakeasy-api
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.