Skip to content

Commit ce4af87

Browse files
beezythebotbeezythebot
committed
Sync open source content 🐝 (from c8beca1a29f6359d3f2dac21d3dd031cd3a2aa91)
1 parent 61f1018 commit ce4af87

File tree

2 files changed

+200
-2
lines changed

2 files changed

+200
-2
lines changed

‎docs/index.mdx‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,16 @@ alwaysShowInSidebar: true
66

77
import { Button } from "@/components/ui/button";
88
import { CardGrid } from "@/mdx/components";
9-
import { cards, intro } from "@/lib/data/docs/overview";
10-
import { TechCards } from "@/components/card/variants/docs/tech-cards";
9+
import { cards, intro, cliInstall } from "@/lib/data/docs/overview";
10+
import { TechCards } from "@/components/card/variants/docs/tech-cards";
1111
import { DocsHeaderIndex } from "@/components/nextra/docs/docs-header-index";
12+
import { CodeWithTabs } from "@/components/code-tabs";
1213

1314
<div className="docs-index bsmnt-container-md flex flex-col mt-10 gap-14">
1415
<DocsHeaderIndex title={intro?.title} description={intro?.description} />
16+
<section className="-mt-8">
17+
<CodeWithTabs tabs={cliInstall.tabs} className="max-w-[540px]" />
18+
</section>
1519
<section>
1620
<CardGrid cards={cards?.start} heading="Start building" columns={4} />
1721
</section>

‎docs/speakeasy-reference/skills.mdx‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: Skills for Claude Code
3+
description: Install Speakeasy agent skills to enable AI-powered SDK generation, OpenAPI management, and API tooling directly in Claude Code.
4+
---
5+
6+
# Skills for Claude Code
7+
8+
Speakeasy provides a collection of skills that enable Claude Code to help with SDK generation, OpenAPI spec management, Terraform provider creation, and more. These skills give Claude deep knowledge of Speakeasy best practices and workflows.
9+
10+
## Installation
11+
12+
Add Speakeasy skills to Claude Code with a single command:
13+
14+
```bash
15+
npx skills add speakeasy-api/agent-skills
16+
```
17+
18+
After installation, Claude Code can assist with all Speakeasy-related tasks using these specialized skills.
19+
20+
## Available skills
21+
22+
### start-new-sdk-project
23+
24+
Initialize a new SDK project with `speakeasy quickstart`. Use this skill when starting a brand new SDK project or setting up Speakeasy for the first time.
25+
26+
**Triggers:** "create SDK", "generate SDK", "new SDK", "quickstart", "get started with Speakeasy"
27+
28+
**Capabilities:**
29+
- Generate SDKs from local OpenAPI files, URLs, or registry sources
30+
- Support for TypeScript, Python, Go, Java, C#, PHP, Ruby, Kotlin, and Terraform
31+
- Create workflow configuration files automatically
32+
33+
### sdk-tf-generation-best-practices
34+
35+
Comprehensive best-practices reference for generating SDKs and Terraform providers. This skill covers the full lifecycle from OpenAPI spec preparation to testing.
36+
37+
**Triggers:** "generate SDK", "regenerate SDK", "SDK best practices", "terraform provider", "SDK customization"
38+
39+
**Capabilities:**
40+
- SDK generation workflows and patterns
41+
- Code-first OpenAPI extraction (FastAPI, Flask, Django, Spring Boot, NestJS, Hono, Rails, Laravel)
42+
- Language-specific SDK guides
43+
- Multi-target and multi-repo SDK generation
44+
- Version management and upgrades
45+
46+
### generate-mcp-server
47+
48+
Generate a Model Context Protocol (MCP) server from an OpenAPI spec. The MCP server exposes API operations as tools that AI assistants like Claude can call directly.
49+
50+
**Triggers:** "generate MCP server", "MCP server", "Model Context Protocol", "AI assistant tools", "Claude tools"
51+
52+
**Capabilities:**
53+
- Create MCP servers from OpenAPI specs
54+
- Configure scope-based access control for tools
55+
- Deploy with stdio or SSE transports
56+
- Integration with Claude Desktop and Claude Code
57+
58+
### generate-terraform-provider
59+
60+
Generate a Terraform provider from an OpenAPI specification. This skill covers entity annotations, CRUD mapping, type inference, workflow configuration, and publishing.
61+
62+
**Triggers:** "terraform provider", "generate terraform", "CRUD mapping", "x-speakeasy-entity"
63+
64+
**Capabilities:**
65+
- Annotate OpenAPI specs with Terraform entity metadata
66+
- Map API operations to Terraform CRUD methods
67+
- Configure workflow.yaml for Terraform generation
68+
- Publish providers to the Terraform Registry
69+
70+
### customize-sdk-hooks
71+
72+
Implement SDK lifecycle hooks to customize request/response behavior. Hooks allow adding custom headers, telemetry, security signatures, and error handling.
73+
74+
**Triggers:** "SDK hooks", "add hooks", "BeforeRequestHook", "custom user-agent", "telemetry hook"
75+
76+
**Capabilities:**
77+
- Add custom headers to every SDK request
78+
- Implement telemetry and observability
79+
- Add custom authentication logic (HMAC signatures, token refresh)
80+
- Transform responses or errors before they reach the caller
81+
82+
### customize-sdk-runtime
83+
84+
Configure runtime behavior for Speakeasy-generated SDKs including retries, timeouts, pagination, server selection, and error handling.
85+
86+
**Triggers:** "SDK retries", "timeout configuration", "pagination config", "server selection", "error handling"
87+
88+
**Capabilities:**
89+
- Configure global and per-operation retry logic
90+
- Set timeouts at the document or operation level
91+
- Add pagination support to list endpoints
92+
- Select between multiple server environments
93+
94+
### manage-openapi-overlays
95+
96+
Create, apply, and manage overlays to customize SDK generation without modifying the source OpenAPI spec.
97+
98+
**Triggers:** "create overlay", "apply overlay", "customize SDK", "can't modify spec", "fix with overlay"
99+
100+
**Capabilities:**
101+
- Create overlay files with JSONPath-targeted changes
102+
- Apply overlays to OpenAPI specs
103+
- Fix validation issues without editing source files
104+
- Add x-speakeasy extensions for grouping, naming, and retries
105+
106+
### improve-sdk-naming
107+
108+
Improve SDK method naming using AI-powered suggestions or manual overrides. Transform ugly auto-generated names into clean, grouped methods.
109+
110+
**Triggers:** "suggest improvements", "better operation names", "ugly method names", "improve operation IDs"
111+
112+
**Capabilities:**
113+
- AI-generated suggestions for operation IDs
114+
- Manual naming with x-speakeasy-group and x-speakeasy-name-override
115+
- Transform `GetApiV1Users` into `sdk.users.list()`
116+
- Suggest error type definitions
117+
118+
### diagnose-generation-failure
119+
120+
Diagnose and fix SDK generation failures. This skill helps identify root causes and determine the appropriate fix strategy.
121+
122+
**Triggers:** "generation failed", "speakeasy run failed", "SDK build error", "workflow failed"
123+
124+
**Capabilities:**
125+
- Run lint to get detailed error information
126+
- Categorize issues as fixable with overlays or requiring spec fixes
127+
- Create strategy documents for complex issues
128+
- Identify blocking issues that require user input
129+
130+
### extract-openapi-from-code
131+
132+
Extract an OpenAPI specification from an existing API codebase. Supports eight major frameworks across Python, Java, JavaScript/TypeScript, Ruby, and PHP.
133+
134+
**Triggers:** "extract OpenAPI", "code first", "generate spec from code", "FastAPI OpenAPI"
135+
136+
**Supported frameworks:**
137+
- **Python:** FastAPI, Flask (flask-smorest), Django REST Framework
138+
- **Java:** Spring Boot (springdoc)
139+
- **TypeScript:** NestJS, Hono (zod-openapi)
140+
- **Ruby:** Rails (rswag)
141+
- **PHP:** Laravel (l5-swagger)
142+
143+
### setup-sdk-testing
144+
145+
Set up and run tests for Speakeasy-generated SDKs using contract testing, custom Arazzo workflows, or integration tests against live APIs.
146+
147+
**Triggers:** "SDK testing", "test SDK", "contract testing", "Arazzo tests", "integration tests"
148+
149+
**Capabilities:**
150+
- Enable contract test generation via gen.yaml
151+
- Write custom multi-step API workflow tests with Arazzo
152+
- Configure integration tests against live APIs
153+
- Debug ResponseValidationError and test failures
154+
155+
### writing-openapi-specs
156+
157+
Reference guide for OpenAPI specification best practices, naming conventions, and expressing complex REST API patterns.
158+
159+
**Triggers:** Writing or improving OpenAPI specs, polymorphism, enums, file uploads, server-sent events
160+
161+
**Capabilities:**
162+
- Operation ID naming conventions
163+
- Documentation standards with CommonMark
164+
- Component reusability patterns
165+
- Complex patterns (enums, polymorphism, nullable types)
166+
167+
## Usage example
168+
169+
After installing the skills, ask Claude Code to help with any Speakeasy task:
170+
171+
```
172+
Generate a TypeScript SDK from my OpenAPI spec at ./api/openapi.yaml
173+
```
174+
175+
```
176+
Add retry configuration to my SDK with exponential backoff
177+
```
178+
179+
```
180+
Create an overlay to fix the operation naming in my spec
181+
```
182+
183+
```
184+
Set up contract testing for my generated SDK
185+
```
186+
187+
Claude Code will use the appropriate skill to provide step-by-step guidance and execute the necessary commands.
188+
189+
## Related resources
190+
191+
- [CLI reference](/docs/speakeasy-reference/cli)
192+
- [Workflow file reference](/docs/speakeasy-reference/workflow-file)
193+
- [OpenAPI extensions](/docs/speakeasy-reference/extensions)
194+
- [Getting started with SDKs](/docs/sdks/create-client-sdks)

0 commit comments

Comments
 (0)