API Client Generator — SDK Generation Full Pipeline
An agent team collaborates to generate API spec parsing, type generation, client code, tests, and documentation.
Execution Mode
Agent Team — Five agents communicate directly via SendMessage and perform cross-validation.
Agent Composition
| Agent |
File |
Role |
Type |
| spec-parser |
.claude/agents/spec-parser.md |
API spec analysis, endpoint extraction |
general-purpose |
| type-generator |
.claude/agents/type-generator.md |
Type definition generation |
general-purpose |
| sdk-developer |
.claude/agents/sdk-developer.md |
Client SDK code development |
general-purpose |
| test-engineer |
.claude/agents/test-engineer.md |
Test code authoring |
general-purpose |
| doc-writer |
.claude/agents/doc-writer.md |
Usage documentation |
general-purpose |
Workflow
Phase 1: Preparation (performed directly by the orchestrator)
- Extract the following from user input:
- API spec: File path/URL, spec format (OpenAPI/GraphQL/gRPC)
- Target language: TypeScript, Python, Go, Java, etc.
- SDK name: Package/module name
- Settings (optional): Authentication priority, naming conventions, additional features
- Create the
_workspace/ directory and subdirectories
- Organize the input and save it to
_workspace/00_input.md
- Copy the API spec file to
_workspace/
- If pre-existing files are available, copy them to
_workspace/ and skip the corresponding phase
- Determine the execution mode based on the scope of the request
Phase 2: Team Assembly and Execution
| Order |
Task |
Owner |
Dependencies |
Deliverable |
| 1 |
Spec analysis |
spec-parser |
None |
01_spec_analysis.md |
| 2 |
Type generation |
type-generator |
Task 1 |
02_types/ |
| 3 |
SDK development |
sdk-developer |
Tasks 1, 2 |
03_client/ |
| 4a |
Test authoring |
test-engineer |
Tasks 2, 3 |
04_tests/ |
| 4b |
Documentation |
doc-writer |
Tasks 1, 3 |
05_docs/ |
Tasks 4a (tests) and 4b (docs) run in parallel.
Inter-agent communication flow:
- spec-parser completes > passes model details to type-generator, endpoint groupings to sdk-developer
- type-generator completes > passes type import info to sdk-developer, factory data to test-engineer
- sdk-developer completes > passes public API list to test-engineer, usage examples to doc-writer
- test-engineer/doc-writer > requests fixes from sdk-developer if code/doc inconsistencies are found
Phase 3: Integration and Final Deliverables
- Verify all files in
_workspace/
- Final consistency check across code, types, tests, and documentation
- Report the final summary along with build/test execution commands
Execution Modes by Request Scope
| User Request Pattern |
Execution Mode |
Agents Deployed |
| "Generate full SDK", "full client" |
Full pipeline |
All 5 agents |
| "Just generate types" |
Type mode |
spec-parser + type-generator |
| "Client code only" |
Code mode |
spec-parser + type-generator + sdk-developer |
| "Write tests only" (existing SDK) |
Test mode |
test-engineer only |
| "Write docs only" (existing SDK) |
Doc mode |
doc-writer only |
| "Spec analysis only" |
Analysis mode |
spec-parser only |
Data Transfer Protocol
| Strategy |
Method |
Purpose |
| File-based |
_workspace/ directory |
Code, types, tests, documentation |
| Message-based |
SendMessage |
Key information transfer, fix requests |
Error Handling
| Error Type |
Strategy |
| Spec parsing failure |
Report syntax error location; proceed with parseable portions only |
| Incomplete spec |
Supplement with type inference; mark as "inferred" |
| Circular references |
Auto-apply lazy reference pattern |
| Non-standard authentication |
Provide custom interceptor extension points |
| Agent failure |
Retry once; if still failing, proceed without that deliverable |
| Code-doc inconsistency |
doc-writer/test-engineer requests fix from sdk-developer (up to 2 rounds) |
Test Scenarios
Normal Flow
Prompt: "Generate a TypeScript SDK from this OpenAPI 3.1 spec"
Expected result:
- Spec analysis: Endpoint groupings, model list, authentication method identification
- Types: TypeScript interfaces/types, enums, union types, serialization helpers
- SDK: Resource-based client classes, authentication, pagination, retry
- Tests: Per-resource unit tests, authentication integration tests, mock server
- Docs: README, quick start, API reference, code examples
Existing File Reuse Flow
Prompt: "Extract just Python types from this Swagger file"
Expected result:
- spec-parser analyzes the schema
- type-generator produces Python dataclass/Pydantic models
- sdk-developer, test-engineer, and doc-writer are not deployed
Error Flow
Prompt: "Create an SDK for this API" (incomplete spec, many undefined response types)
Expected result:
- spec-parser catalogs and reports the incomplete portions
- type-generator generates types within the inferrable scope, adds "inferred" comments
- sdk-developer adds a runtime type-check layer
- doc-writer records the undefined response list in a "Known Limitations" section
Agent Extension Skills
| Skill |
Path |
Enhanced Agent |
Role |
| openapi-spec-patterns |
.claude/skills/openapi-spec-patterns/skill.md |
spec-parser |
Endpoint grouping, auth mapping, pagination/error patterns, GraphQL/gRPC |
| sdk-design-patterns |
.claude/skills/sdk-design-patterns/skill.md |
sdk-developer |
Builder pattern, interceptor chain, retry, type safety, pagination wrapper |
1---2name: api-client-generator3description: Full pipeline for auto-generating API client SDKs. An agent team collaborates to parse API specs (OpenAPI/GraphQL/gRPC), generate types, write client code, create tests, and produce usage documentation. Use this skill for requests like 'create an API client', 'SDK generation', 'client from OpenAPI', 'API wrapper', 'REST client', 'GraphQL client', 'API type generation', 'SDK from Swagger', etc. Note: API server implementation, API gateway configuration, and API monitoring dashboard setup are outside the scope of this skill.4---56# API Client Generator — SDK Generation Full Pipeline78An agent team collaborates to generate API spec parsing, type generation, client code, tests, and documentation.910## Execution Mode1112**Agent Team** — Five agents communicate directly via SendMessage and perform cross-validation.1314## Agent Composition1516| Agent | File | Role | Type |17|-------|------|------|------|18| spec-parser | `.claude/agents/spec-parser.md` | API spec analysis, endpoint extraction | general-purpose |19| type-generator | `.claude/agents/type-generator.md` | Type definition generation | general-purpose |20| sdk-developer | `.claude/agents/sdk-developer.md` | Client SDK code development | general-purpose |21| test-engineer | `.claude/agents/test-engineer.md` | Test code authoring | general-purpose |22| doc-writer | `.claude/agents/doc-writer.md` | Usage documentation | general-purpose |2324## Workflow2526### Phase 1: Preparation (performed directly by the orchestrator)27281. Extract the following from user input:29 - **API spec**: File path/URL, spec format (OpenAPI/GraphQL/gRPC)30 - **Target language**: TypeScript, Python, Go, Java, etc.31 - **SDK name**: Package/module name32 - **Settings** (optional): Authentication priority, naming conventions, additional features332. Create the `_workspace/` directory and subdirectories343. Organize the input and save it to `_workspace/00_input.md`354. Copy the API spec file to `_workspace/`365. If pre-existing files are available, copy them to `_workspace/` and skip the corresponding phase376. **Determine the execution mode** based on the scope of the request3839### Phase 2: Team Assembly and Execution4041| Order | Task | Owner | Dependencies | Deliverable |42|-------|------|-------|-------------|-------------|43| 1 | Spec analysis | spec-parser | None | `01_spec_analysis.md` |44| 2 | Type generation | type-generator | Task 1 | `02_types/` |45| 3 | SDK development | sdk-developer | Tasks 1, 2 | `03_client/` |46| 4a | Test authoring | test-engineer | Tasks 2, 3 | `04_tests/` |47| 4b | Documentation | doc-writer | Tasks 1, 3 | `05_docs/` |4849Tasks 4a (tests) and 4b (docs) run **in parallel**.5051**Inter-agent communication flow:**52- spec-parser completes > passes model details to type-generator, endpoint groupings to sdk-developer53- type-generator completes > passes type import info to sdk-developer, factory data to test-engineer54- sdk-developer completes > passes public API list to test-engineer, usage examples to doc-writer55- test-engineer/doc-writer > requests fixes from sdk-developer if code/doc inconsistencies are found5657### Phase 3: Integration and Final Deliverables58591. Verify all files in `_workspace/`602. Final consistency check across code, types, tests, and documentation613. Report the final summary along with build/test execution commands6263## Execution Modes by Request Scope6465| User Request Pattern | Execution Mode | Agents Deployed |66|---------------------|---------------|----------------|67| "Generate full SDK", "full client" | **Full pipeline** | All 5 agents |68| "Just generate types" | **Type mode** | spec-parser + type-generator |69| "Client code only" | **Code mode** | spec-parser + type-generator + sdk-developer |70| "Write tests only" (existing SDK) | **Test mode** | test-engineer only |71| "Write docs only" (existing SDK) | **Doc mode** | doc-writer only |72| "Spec analysis only" | **Analysis mode** | spec-parser only |7374## Data Transfer Protocol7576| Strategy | Method | Purpose |77|----------|--------|---------|78| File-based | `_workspace/` directory | Code, types, tests, documentation |79| Message-based | SendMessage | Key information transfer, fix requests |8081## Error Handling8283| Error Type | Strategy |84|-----------|----------|85| Spec parsing failure | Report syntax error location; proceed with parseable portions only |86| Incomplete spec | Supplement with type inference; mark as "inferred" |87| Circular references | Auto-apply lazy reference pattern |88| Non-standard authentication | Provide custom interceptor extension points |89| Agent failure | Retry once; if still failing, proceed without that deliverable |90| Code-doc inconsistency | doc-writer/test-engineer requests fix from sdk-developer (up to 2 rounds) |9192## Test Scenarios9394### Normal Flow95**Prompt**: "Generate a TypeScript SDK from this OpenAPI 3.1 spec"96**Expected result**:97- Spec analysis: Endpoint groupings, model list, authentication method identification98- Types: TypeScript interfaces/types, enums, union types, serialization helpers99- SDK: Resource-based client classes, authentication, pagination, retry100- Tests: Per-resource unit tests, authentication integration tests, mock server101- Docs: README, quick start, API reference, code examples102103### Existing File Reuse Flow104**Prompt**: "Extract just Python types from this Swagger file"105**Expected result**:106- spec-parser analyzes the schema107- type-generator produces Python dataclass/Pydantic models108- sdk-developer, test-engineer, and doc-writer are not deployed109110### Error Flow111**Prompt**: "Create an SDK for this API" (incomplete spec, many undefined response types)112**Expected result**:113- spec-parser catalogs and reports the incomplete portions114- type-generator generates types within the inferrable scope, adds "inferred" comments115- sdk-developer adds a runtime type-check layer116- doc-writer records the undefined response list in a "Known Limitations" section117118119## Agent Extension Skills120121| Skill | Path | Enhanced Agent | Role |122|-------|------|---------------|------|123| openapi-spec-patterns | `.claude/skills/openapi-spec-patterns/skill.md` | spec-parser | Endpoint grouping, auth mapping, pagination/error patterns, GraphQL/gRPC |124| sdk-design-patterns | `.claude/skills/sdk-design-patterns/skill.md` | sdk-developer | Builder pattern, interceptor chain, retry, type safety, pagination wrapper |
revfactory