Skip to content

Commit be205da

Browse files
simplesagarclaude
simplesagar
and
claude
authored
feat: add Claude Code plugin with skills for SDK generation (#1792)
## Summary Adds a Claude Code plugin with skills-based guidance for Speakeasy SDK generation. **Philosophy:** Claude Code already calls CLIs reliably. Instead of wrapping CLI commands in MCP tools, this plugin provides decision frameworks and usage guidance triggered by user intent and error patterns. **Version:** `0.1.0-alpha` ## Installation ```bash claude /install github:speakeasy-api/speakeasy/plugins/claude-code ``` ## Skills Each skill is a separate file with YAML frontmatter for Claude discovery: | Skill | Use When... | |-------|-------------| | `start-new-sdk-project` | You have an OpenAPI spec and want to generate an SDK | | `regenerate-sdk` | Your spec changed and you need to regenerate | | `validate-openapi-spec` | Checking if spec is valid, running `speakeasy lint` | | `get-ai-suggestions` | SDK method names are ugly, wanting to improve operation IDs | | `check-workspace-status` | Asking what targets/sources are configured | | `create-openapi-overlay` | Need to customize SDK without editing source spec | | `apply-openapi-overlay` | Applying an overlay file to a spec | | `merge-openapi-specs` | Combining multiple OpenAPI specs | | `diagnose-generation-failure` | SDK generation failed, seeing "Step Failed: Workflow" | | `fix-validation-errors-with-overlays` | Have lint errors but can't modify source spec | | `improve-operation-ids` | SDK methods have names like GetApiV1Users | ## Key Principles 1. **Don't auto-fix everything** - Distinguish between: - Small issues (naming, descriptions) → Fix with overlays - Structural issues (invalid refs) → Ask the user - Design issues (auth, API structure) → Produce strategy document 2. **AI-friendly output** - Use `speakeasy run --output console` for structured output, pipe to `grep`/`tail` to reduce context 3. **Overlay over modify** - Never modify source specs directly. Overlays make patches portable across spec versions. 4. **Grouped SDK methods** - Guide users toward `sdk.users.list()` pattern using `x-speakeasy-group` + `x-speakeasy-name-override` ## Plugin Structure ``` plugins/claude-code/ ├── .claude-plugin/ │ └── plugin.json # Plugin metadata ├── skills/ # Individual skill files with frontmatter │ ├── start-new-sdk-project.md │ ├── regenerate-sdk.md │ ├── validate-openapi-spec.md │ └── ... (11 total) ├── marketplace.json # Marketplace metadata └── README.md ``` ## Test plan - [ ] Install plugin via `claude /install github:speakeasy-api/speakeasy/plugins/claude-code` - [ ] Verify skills are loaded and available - [ ] Test quickstart → run workflow - [ ] Test with broken spec to confirm decision framework works --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 0f43ac7 commit be205da

14 files changed

Lines changed: 629 additions & 0 deletions

‎plugins/claude-code/.claude-plugin/plugin.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "speakeasy",
3+
"version": "0.1.0-alpha",
4+
"description": "SDK generation and OpenAPI tooling with Speakeasy CLI",
5+
"skills": [
6+
"../skills/start-new-sdk-project.md",
7+
"../skills/regenerate-sdk.md",
8+
"../skills/validate-openapi-spec.md",
9+
"../skills/get-ai-suggestions.md",
10+
"../skills/check-workspace-status.md",
11+
"../skills/create-openapi-overlay.md",
12+
"../skills/apply-openapi-overlay.md",
13+
"../skills/merge-openapi-specs.md",
14+
"../skills/diagnose-generation-failure.md",
15+
"../skills/fix-validation-errors-with-overlays.md",
16+
"../skills/improve-operation-ids.md"
17+
]
18+
}

‎plugins/claude-code/README.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Speakeasy Plugin for Claude Code
2+
3+
Generate production-ready SDKs from OpenAPI specifications with guidance for the Speakeasy CLI.
4+
5+
## Installation
6+
7+
```bash
8+
claude /install github:speakeasy-api/speakeasy/plugins/claude-code
9+
```
10+
11+
## What This Provides
12+
13+
This plugin provides **skills** - usage guidance and decision frameworks for Speakeasy CLI operations:
14+
15+
| Skill | Use When... |
16+
|-------|-------------|
17+
| `start-new-sdk-project` | You have an OpenAPI spec and want to generate an SDK |
18+
| `regenerate-sdk` | Your spec changed and you need to regenerate |
19+
| `validate-openapi-spec` | Checking if spec is valid, running `speakeasy lint` |
20+
| `get-ai-suggestions` | SDK method names are ugly, wanting to improve operation IDs |
21+
| `check-workspace-status` | Asking what targets/sources are configured |
22+
| `create-openapi-overlay` | Need to customize SDK without editing source spec |
23+
| `apply-openapi-overlay` | Applying an overlay file to a spec |
24+
| `merge-openapi-specs` | Combining multiple OpenAPI specs |
25+
| `diagnose-generation-failure` | SDK generation failed, seeing "Step Failed: Workflow" |
26+
| `fix-validation-errors-with-overlays` | Have lint errors but can't modify source spec |
27+
| `improve-operation-ids` | SDK methods have names like GetApiV1Users |
28+
29+
## Philosophy
30+
31+
Claude Code already calls CLIs reliably. This plugin doesn't wrap CLI commands - instead it provides:
32+
33+
1. **Usage guidance** - How to use each command effectively
34+
2. **Decision frameworks** - When to use overlays vs ask the user
35+
3. **Troubleshooting** - How to diagnose and fix common issues
36+
37+
## Key Principles
38+
39+
### Use the Workflow
40+
41+
```bash
42+
# Initialize project
43+
speakeasy quickstart -s openapi.yaml -t typescript
44+
45+
# Regenerate after changes (use --output console for AI-friendly output)
46+
speakeasy run --output console
47+
```
48+
49+
### Overlay Over Modify
50+
51+
Never modify the source OpenAPI spec directly. Use overlays to:
52+
- Rename operations
53+
- Add descriptions
54+
- Configure SDK behavior
55+
- Make portable patches across spec versions
56+
57+
### Don't Auto-Fix Everything
58+
59+
When encountering spec issues:
60+
- **Small issues** (naming, descriptions) → Fix with overlays
61+
- **Structural issues** (invalid refs, missing schemas) → Ask the user
62+
- **Design issues** (auth, API structure) → Produce strategy document
63+
64+
## Plugin Structure
65+
66+
```
67+
plugins/claude-code/
68+
├── .claude-plugin/
69+
│ └── plugin.json # Plugin metadata
70+
├── skills/ # Individual skill files
71+
│ ├── start-new-sdk-project.md
72+
│ ├── regenerate-sdk.md
73+
│ ├── validate-openapi-spec.md
74+
│ └── ...
75+
├── marketplace.json # Marketplace metadata
76+
└── README.md
77+
```
78+
79+
## Prerequisites
80+
81+
Install Speakeasy CLI:
82+
83+
```bash
84+
# macOS
85+
brew install speakeasy-api/homebrew-tap/speakeasy
86+
87+
# Other platforms
88+
curl -fsSL https://raw.githubusercontent.com/speakeasy-api/speakeasy/main/install.sh | sh
89+
```
90+
91+
## Resources
92+
93+
- [Speakeasy Documentation](https://speakeasy.com/docs)
94+
- [OpenAPI Best Practices](https://speakeasy.com/docs/openapi)
95+
- [SDK Customization](https://speakeasy.com/docs/customize-sdks)
96+
97+
## License
98+
99+
Apache-2.0

‎plugins/claude-code/marketplace.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"name": "speakeasy",
3+
"version": "0.1.0-alpha",
4+
"description": "SDK generation and OpenAPI tooling with Speakeasy CLI",
5+
"author": "Speakeasy",
6+
"repository": "https://github.com/speakeasy-api/speakeasy",
7+
"homepage": "https://speakeasy.com",
8+
"keywords": ["sdk", "openapi", "api", "codegen", "typescript", "python", "go"]
9+
}

‎plugins/claude-code/skills/apply-openapi-overlay.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
description: Use when applying an overlay file to a spec
3+
---
4+
5+
# apply-openapi-overlay
6+
7+
## Command
8+
9+
```bash
10+
speakeasy overlay apply -s <spec-path> -o <overlay-path> --out <output-path>
11+
```
12+
13+
## Example
14+
15+
```bash
16+
# Apply overlay and output merged spec
17+
speakeasy overlay apply -s openapi.yaml -o my-overlay.yaml --out openapi-modified.yaml
18+
```
19+
20+
## Using in Workflow
21+
22+
Better approach - add overlay to workflow.yaml:
23+
24+
```yaml
25+
sources:
26+
my-api:
27+
inputs:
28+
- location: ./openapi.yaml
29+
overlays:
30+
- location: ./naming-overlay.yaml
31+
- location: ./grouping-overlay.yaml
32+
```
33+
34+
Overlays are applied in order, so later overlays can override earlier ones.

‎plugins/claude-code/skills/check-workspace-status.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
description: Use when asking what targets/sources are configured, or wanting to see current Speakeasy setup
3+
---
4+
5+
# check-workspace-status
6+
7+
Use `speakeasy status` to view workspace state.
8+
9+
## Command
10+
11+
```bash
12+
speakeasy status
13+
```
14+
15+
## What It Shows
16+
17+
- Configured sources and their locations
18+
- Configured targets and output directories
19+
- Current Speakeasy version
20+
- Any configuration issues
21+
22+
## Use Cases
23+
24+
- Verify setup before running generation
25+
- Debug workflow configuration issues
26+
- Check what targets are configured

‎plugins/claude-code/skills/create-openapi-overlay.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
description: Use when you need to customize SDK generation without editing the source spec, or can't modify the original OpenAPI file
3+
---
4+
5+
# create-openapi-overlay
6+
7+
Overlays let you customize an OpenAPI spec for SDK generation without modifying the source.
8+
9+
## Create Overlay Template
10+
11+
```bash
12+
speakeasy overlay create -s <spec-path> -o <output-path>
13+
```
14+
15+
## When to Use Overlays
16+
17+
**Overlays are great for:**
18+
- Renaming operations (x-speakeasy-name-override)
19+
- Adding descriptions/summaries
20+
- Grouping operations (x-speakeasy-group)
21+
- Adding retry configuration
22+
- Marking endpoints as deprecated
23+
- Adding SDK-specific extensions
24+
- Fixing spec issues without modifying the source
25+
- Adding new endpoints or schemas
26+
- Making portable patches that work across spec versions
27+
28+
**Overlays cannot easily handle:**
29+
- Deduplication of schemas (requires structural analysis)
30+
31+
## Example Overlay
32+
33+
```yaml
34+
overlay: 1.0.0
35+
info:
36+
title: SDK Customizations
37+
version: 1.0.0
38+
actions:
39+
- target: "$.paths['/users'].get"
40+
update:
41+
x-speakeasy-group: users
42+
x-speakeasy-name-override: list
43+
- target: "$.paths['/users'].post"
44+
update:
45+
x-speakeasy-group: users
46+
x-speakeasy-name-override: create
47+
- target: "$.paths['/users/{id}'].get"
48+
update:
49+
x-speakeasy-group: users
50+
x-speakeasy-name-override: get
51+
- target: "$.paths['/users/{id}'].delete"
52+
update:
53+
x-speakeasy-group: users
54+
x-speakeasy-name-override: delete
55+
deprecated: true
56+
```
57+
58+
This produces: `sdk.users.list()`, `sdk.users.create()`, `sdk.users.get()`, `sdk.users.delete()`
59+
60+
## JSONPath Targeting
61+
62+
| Target | Selects |
63+
|--------|---------|
64+
| `$.paths['/users'].get` | GET /users operation |
65+
| `$.paths['/users/{id}'].*` | All operations on /users/{id} |
66+
| `$.components.schemas.User` | User schema |
67+
| `$.info` | API info object |

‎plugins/claude-code/skills/diagnose-generation-failure.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
description: Use when SDK generation failed, seeing "Step Failed: Workflow", or `speakeasy run` errors
3+
---
4+
5+
# diagnose-generation-failure
6+
7+
When SDK generation fails, determine the root cause and fix strategy.
8+
9+
## Diagnosis Steps
10+
11+
1. **Run lint to get detailed errors:**
12+
```bash
13+
speakeasy lint openapi -s <spec-path>
14+
```
15+
16+
2. **Categorize issues:**
17+
- **Fixable with overlays:** Missing descriptions, poor operation IDs
18+
- **Requires spec fix:** Invalid schema, missing required fields
19+
- **Requires user input:** Design decisions, authentication setup
20+
21+
## Decision Framework
22+
23+
| Issue Type | Fix Strategy | Example |
24+
|------------|--------------|---------|
25+
| Missing operationId | Overlay | Use `speakeasy suggest operation-ids` |
26+
| Missing description | Overlay | Add via overlay |
27+
| Invalid $ref | **Ask user** | Broken reference needs spec fix |
28+
| Circular reference | **Ask user** | Design decision needed |
29+
| Missing security | **Ask user** | Auth design needed |
30+
31+
## What NOT to Do
32+
33+
- **Do NOT** disable lint rules to hide errors
34+
- **Do NOT** try to fix every issue one-by-one
35+
- **Do NOT** modify source spec without asking
36+
- **Do NOT** assume you can fix structural problems
37+
38+
## Strategy Document
39+
40+
For complex issues, produce a document:
41+
42+
```markdown
43+
## OpenAPI Spec Analysis
44+
45+
### Blocking Issues (require user input)
46+
- [List issues that need human decision]
47+
48+
### Fixable Issues (can use overlays)
49+
- [List issues with proposed overlay fixes]
50+
51+
### Recommended Approach
52+
[Your recommendation]
53+
```

‎plugins/claude-code/skills/fix-validation-errors-with-overlays.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
description: Use when you have lint errors but can't modify the source spec, or need to add missing descriptions/tags via overlay
3+
---
4+
5+
# fix-validation-errors-with-overlays
6+
7+
## Overlay-Appropriate Fixes
8+
9+
| Issue | Overlay Solution |
10+
|-------|------------------|
11+
| Poor operation names | `x-speakeasy-name-override` |
12+
| Missing descriptions | Add `summary` or `description` |
13+
| Missing tags | Add `tags` array |
14+
| Need operation grouping | `x-speakeasy-group` |
15+
| Need retry config | `x-speakeasy-retries` |
16+
17+
## NOT Overlay-Appropriate
18+
19+
| Issue | Why |
20+
|-------|-----|
21+
| Invalid JSON/YAML | Syntax error in source |
22+
| Missing required fields | Schema incomplete |
23+
| Broken $ref | Source needs fixing |
24+
| Wrong data types | API design issue |
25+
26+
## Quick Fix Workflow
27+
28+
```bash
29+
# 1. Generate suggestions
30+
speakeasy suggest operation-ids -s openapi.yaml -o fixes.yaml
31+
32+
# 2. Add to workflow
33+
# Edit .speakeasy/workflow.yaml to include overlay
34+
35+
# 3. Regenerate
36+
speakeasy run
37+
```

0 commit comments

Comments
 (0)