chore: improve claude plugin structure for easier adding

.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "speakeasy",
+  "version": "0.1.0-alpha",
+  "description": "SDK generation and OpenAPI tooling with Speakeasy CLI",
+  "owner": {
+    "name": "Speakeasy",
+    "email": "support@speakeasy.com"
+  },
+  "plugins": [
+    {
+      "name": "speakeasy",
+      "description": "SDK generation and OpenAPI tooling with Speakeasy CLI",
+      "version": "0.1.0-alpha",
+      "author": {
+        "name": "Speakeasy",
+        "email": "support@speakeasy.com"
+      },
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "speakeasy",
+  "version": "0.2.0-alpha",
+  "description": "SDK generation and OpenAPI tooling with Speakeasy CLI",
+  "skills": "./skills/"
+}

README.md

@@ -197,3 +197,43 @@ Refer to the [Speakeasy CLI installation documentation](https://www.speakeasy.co
 ### Usage
 
 Refer to the [Speakeasy CLI Reference](https://www.speakeasy.com/docs/speakeasy-reference/cli) for usage documentation. Additionally, every CLI command and subcommand supports a `--help` flag for usage information.
+
+## Claude Code Plugin
+
+Use Speakeasy directly within [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with our official plugin.
+
+### Installation
+
+```bash
+# Add the Speakeasy marketplace
+/plugin marketplace add speakeasy-api/speakeasy
+
+# Install the plugin
+/plugin install speakeasy
+```
+
+### Usage
+
+Once installed, you can use Speakeasy skills directly in Claude Code:
+
+```bash
+/speakeasy:check-workspace-status    # View current Speakeasy setup
+/speakeasy:validate-openapi-spec     # Validate an OpenAPI spec
+/speakeasy:start-new-sdk-project     # Initialize a new SDK project
+```
+
+### Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `start-new-sdk-project` | Generate an SDK from an OpenAPI spec |
+| `regenerate-sdk` | Re-run SDK generation after spec changes |
+| `validate-openapi-spec` | Check if an OpenAPI spec is valid |
+| `get-ai-suggestions` | Get AI suggestions to improve your spec |
+| `check-workspace-status` | View current Speakeasy setup and targets |
+| `create-openapi-overlay` | Create overlays to customize SDK generation |
+| `apply-openapi-overlay` | Apply an overlay file to a spec |
+| `merge-openapi-specs` | Combine multiple OpenAPI specs |
+| `diagnose-generation-failure` | Debug SDK generation failures |
+| `fix-validation-errors-with-overlays` | Fix lint errors via overlays |
+| `improve-operation-ids` | Improve SDK method names |

skills/apply-openapi-overlay/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: apply-openapi-overlay
+description: Use when applying an overlay file to a spec
+---
+
+# apply-openapi-overlay
+
+## Command
+
+```bash
+speakeasy overlay apply -s <spec-path> -o <overlay-path> --out <output-path>
+```
+
+## Example
+
+```bash
+# Apply overlay and output merged spec
+speakeasy overlay apply -s openapi.yaml -o my-overlay.yaml --out openapi-modified.yaml
+```
+
+## Using in Workflow
+
+Better approach - add overlay to workflow.yaml:
+
+```yaml
+sources:
+  my-api:
+    inputs:
+      - location: ./openapi.yaml
+    overlays:
+      - location: ./naming-overlay.yaml
+      - location: ./grouping-overlay.yaml
+```
+
+Overlays are applied in order, so later overlays can override earlier ones.

skills/check-workspace-status/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: check-workspace-status
+description: Use when asking what targets/sources are configured, or wanting to see current Speakeasy setup
+---
+
+# check-workspace-status
+
+Use `speakeasy status` to view workspace state.
+
+## Command
+
+```bash
+speakeasy status
+```
+
+## What It Shows
+
+- Configured sources and their locations
+- Configured targets and output directories
+- Current Speakeasy version
+- Any configuration issues
+
+## Use Cases
+
+- Verify setup before running generation
+- Debug workflow configuration issues
+- Check what targets are configured

skills/create-openapi-overlay/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: create-openapi-overlay
+description: Use when you need to customize SDK generation without editing the source spec, or can't modify the original OpenAPI file
+---
+
+# create-openapi-overlay
+
+Overlays let you customize an OpenAPI spec for SDK generation without modifying the source.
+
+## Create Overlay Template
+
+```bash
+speakeasy overlay create -s <spec-path> -o <output-path>
+```
+
+## When to Use Overlays
+
+**Overlays are great for:**
+- Renaming operations (x-speakeasy-name-override)
+- Adding descriptions/summaries
+- Grouping operations (x-speakeasy-group)
+- Adding retry configuration
+- Marking endpoints as deprecated
+- Adding SDK-specific extensions
+- Fixing spec issues without modifying the source
+- Adding new endpoints or schemas
+- Making portable patches that work across spec versions
+
+**Overlays cannot easily handle:**
+- Deduplication of schemas (requires structural analysis)
+
+## Example Overlay
+
+```yaml
+overlay: 1.0.0
+info:
+  title: SDK Customizations
+  version: 1.0.0
+actions:
+  - target: "$.paths['/users'].get"
+    update:
+      x-speakeasy-group: users
+      x-speakeasy-name-override: list
+  - target: "$.paths['/users'].post"
+    update:
+      x-speakeasy-group: users
+      x-speakeasy-name-override: create
+  - target: "$.paths['/users/{id}'].get"
+    update:
+      x-speakeasy-group: users
+      x-speakeasy-name-override: get
+  - target: "$.paths['/users/{id}'].delete"
+    update:
+      x-speakeasy-group: users
+      x-speakeasy-name-override: delete
+      deprecated: true
+```
+
+This produces: `sdk.users.list()`, `sdk.users.create()`, `sdk.users.get()`, `sdk.users.delete()`
+
+## JSONPath Targeting
+
+| Target | Selects |
+|--------|---------|
+| `$.paths['/users'].get` | GET /users operation |
+| `$.paths['/users/{id}'].*` | All operations on /users/{id} |
+| `$.components.schemas.User` | User schema |
+| `$.info` | API info object |

skills/diagnose-generation-failure/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: diagnose-generation-failure
+description: Use when SDK generation failed, seeing "Step Failed: Workflow", or `speakeasy run` errors
+---
+
+# diagnose-generation-failure
+
+When SDK generation fails, determine the root cause and fix strategy.
+
+## Diagnosis Steps
+
+1. **Run lint to get detailed errors:**
+   ```bash
+   speakeasy lint openapi -s <spec-path>
+   ```
+
+2. **Categorize issues:**
+   - **Fixable with overlays:** Missing descriptions, poor operation IDs
+   - **Requires spec fix:** Invalid schema, missing required fields
+   - **Requires user input:** Design decisions, authentication setup
+
+## Decision Framework
+
+| Issue Type | Fix Strategy | Example |
+|------------|--------------|---------|
+| Missing operationId | Overlay | Use `speakeasy suggest operation-ids` |
+| Missing description | Overlay | Add via overlay |
+| Invalid $ref | **Ask user** | Broken reference needs spec fix |
+| Circular reference | **Ask user** | Design decision needed |
+| Missing security | **Ask user** | Auth design needed |
+
+## What NOT to Do
+
+- **Do NOT** disable lint rules to hide errors
+- **Do NOT** try to fix every issue one-by-one
+- **Do NOT** modify source spec without asking
+- **Do NOT** assume you can fix structural problems
+
+## Strategy Document
+
+For complex issues, produce a document:
+
+```markdown
+## OpenAPI Spec Analysis
+
+### Blocking Issues (require user input)
+- [List issues that need human decision]
+
+### Fixable Issues (can use overlays)
+- [List issues with proposed overlay fixes]
+
+### Recommended Approach
+[Your recommendation]
+```

skills/fix-validation-errors-with-overlays/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: fix-validation-errors-with-overlays
+description: Use when you have lint errors but can't modify the source spec, or need to add missing descriptions/tags via overlay
+---
+
+# fix-validation-errors-with-overlays
+
+## Overlay-Appropriate Fixes
+
+| Issue | Overlay Solution |
+|-------|------------------|
+| Poor operation names | `x-speakeasy-name-override` |
+| Missing descriptions | Add `summary` or `description` |
+| Missing tags | Add `tags` array |
+| Need operation grouping | `x-speakeasy-group` |
+| Need retry config | `x-speakeasy-retries` |
+
+## NOT Overlay-Appropriate
+
+| Issue | Why |
+|-------|-----|
+| Invalid JSON/YAML | Syntax error in source |
+| Missing required fields | Schema incomplete |
+| Broken $ref | Source needs fixing |
+| Wrong data types | API design issue |
+
+## Quick Fix Workflow
+
+```bash
+# 1. Generate suggestions
+speakeasy suggest operation-ids -s openapi.yaml -o fixes.yaml
+
+# 2. Add to workflow
+# Edit .speakeasy/workflow.yaml to include overlay
+
+# 3. Regenerate
+speakeasy run
+```

skills/get-ai-suggestions/SKILL.md

@@ -0,0 +1,51 @@
+---
+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.
+
+## Commands
+
+```bash
+# 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
+
+```bash
+# 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
+```