Orval skill for agents
Orval skill
The official Orval skill: the agent sets up generation of TypeScript clients, Query hooks, Zod schemas and MSW mocks from an OpenAPI spec
- 6,557 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The agent runs `npx orval`, which executes your `orval.config.ts` and hooks such as `prettier --write` after generation
- Generation creates and overwrites client, schema and mock files in the project, and `--clean` clears generated output
- A spec can be fetched from a URL, and the config sets authorization headers for it
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/orval-skillDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent runs `npx orval`, which executes your `orval.config.ts` and hooks such as `prettier --write` after generation
- Generation creates and overwrites client, schema and mock files in the project, and `--clean` clears generated output
- A spec can be fetched from a URL, and the config sets authorization headers for it
This is third-party code. Review the repository files before installing.
What it does
The `orval` skill from the Orval repository teaches an agent to set up the TypeScript code generator for an OpenAPI v3 or Swagger v2 spec. The main `SKILL.md` holds the install command `npm install orval -D`, a minimal `orval.config.ts` with `defineConfig`, a client selection table with 14 options (`react-query`, `vue-query`, `svelte-query`, `solid-query`, `solid-start`, `angular-query`, `angular`, `swr`, `fetch`, `axios`, `axios-functions`, `zod`, `hono`, `mcp`) and four file layout modes: `single`, `split`, `tags`, `tags-split`. The agent picks a client and a mode for the project's stack, sets the input and output, filters by tags and schemas, several specs in one config, and runs `npx orval` with the right flags, such as `--watch`, `--project` or `--clean`. Nine reference files load by topic: TanStack Query and SWR hooks, Angular, SolidStart, custom HTTP clients and authentication, Zod schemas, MSW mocks with Faker, Hono server handlers, advanced configuration, and the programmatic API, spec transformers, `afterAllFilesWrite` hooks and NDJSON streaming. For the spec itself the skill lists eight rules: a separate `operationId` per operation, shared schemas in `components/schemas`, tags, response types, required fields, `x-enumNames`, example values for mocks and the `application/x-ndjson` type for streams.
Who it is for. For TypeScript developers who have an API described in OpenAPI or Swagger and want clients, hooks, schemas and mocks generated from it through Claude Code or Cursor.
Good fit when
- The project has an OpenAPI spec and generation of React Query, Vue Query or SWR hooks has to be set up from scratch
- Requests must go through your own client: you need a custom mutator with a token or interceptors
- Tests need MSW mocks with Faker and values taken from the `example` fields of the spec
- You need Zod schemas or Hono server handlers with response validation generated from the spec
- You want to turn OpenAPI into an MCP server: the `mcp` client creates the handlers and the server setup
Not a fit when
- There is no OpenAPI spec and nowhere to get one: Orval works only from an OpenAPI v3 or Swagger v2 document in yaml or json
- The machine runs Node.js older than 22.18: the `orval` package declares `>=22.18.0` in `engines`
- The project already uses another generator: for Kubb the catalog has a plugin with the `/kubb:init` and `/kubb:generate` commands
- You need terminal commands built from a spec rather than application code: the catalog has OpenAPI to CLI for that
Example request
Set up Orval in this project: generate React Query hooks on fetch from openapi.yaml with the tags-split layout, MSW mocks and Prettier formattingLimitations
- The skill describes Orval version 8. The library's documentation says 8.0.0 brought many changes and gives a migration guide, so configuration examples may not fit a project on an older version.
- The `mcp` client works only in `single` mode, and typed NDJSON streaming is supported only by the `fetch` client.
- Generation writes files into the project, and the `--clean` flag clears generated output. The `afterAllFilesWrite` hooks run commands such as `prettier --write` or `eslint --fix` after every generation.
- For a remote spec behind authorization the skill's example shows headers with a token right in `orval.config.ts`.
- The skill connects as a Claude Code plugin, a Cursor rule or a package through `npx skills add`. MIT license.
How to disable. Remove the `orval` plugin through Claude Code's plugin manager, and delete the skill folder that `npx skills add` created from your agent's skills directory. Take the library out of the project's `devDependencies` with your package manager. Generated files stay in the project and have to be removed by hand.
FAQ
How do I install the Orval skill in my agent?
In Claude Code run `/plugin marketplace add orval-labs/orval`. For Cursor add a remote GitHub rule that points to this repository. For other agents `npx skills add orval-labs/orval` works. The skill is picked up automatically from context and does not appear in command menus.
Which client should I choose for Vue and Angular?
For Vue 3 the skill's table lists `vue-query` with `httpClient` set to `fetch` or `axios`. For Angular with signals use `angular-query` with `httpClient: 'angular'`, and for classic services on HttpClient there is the `angular` client.
How are files laid out for a large spec?
For a large API the skill recommends the `tags-split` mode: a folder per OpenAPI tag holding the request, schema and mock files. For small APIs `single` with one file is enough, and `split` fits medium ones, keeping schemas and mocks next to the requests.
Can I get an MCP server from a spec?
Yes, set `client: 'mcp'` in `single` mode. Orval creates types in `src/http-schemas/`, handlers in `src/handlers.ts`, the client `src/http-client.ts`, the server setup `src/server.ts` and Zod schemas for tool inputs. The skill suggests deploying the server with Docker and connecting it in the MCP client settings.
How do I generate mocks for tests?
The option `mocks: true` equals the `msw` and `faker` generators together and creates `.msw.ts` and `.faker.ts` files. `useExamples: true` takes values from the spec's `example` fields, and `delay` sets the handler's response delay.
Discussion
No questions or reviews yet.
Related
SkillsBuilder Skills
Skills for agents
A set of small skills from Builder.io for agent work habits: visual plans and diff recaps, docs-first checks, cross-agent review and clean status updates
Tech Leads Club Agent Skills
Agent Skills
A vetted skill registry with a CLI that installs into twenty-plus agents and an MCP server for on-demand skill lookup
Dimillian Skills
Skills
A set of 16 engineering skills for agents: Apple platform work, macOS packaging, React performance, code review and refactoring
The author's personal set: shared agent rules and dozens of skills for GitHub, the browser, macOS, messaging and releases, plus a sync script
Two skills for coding agents: wtf audits a project before shipping, better-codex keeps the agent disciplined while working on code
OpenClaw Agent Skills
openclaw-agent-skills
Shared skills for coding agents that work on OpenClaw projects: review and other workflows. A narrow topic for people who write OpenClaw code
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Orval skill for agents (this entry) | yes | 6,557 | |
| Kubb | yes | 1,825 | another OpenAPI generator: config `kubb.config.ts`, `@kubb` plugins, and the plugin has its own `/kubb:init` and `/kubb:generate` commands |
| OpenAPI to CLI (ocli) | no | 265 | turns an OpenAPI API into terminal commands without code generation |
README in short
The repository holds the generator's source: client packages in `packages/` (angular, axios, mcp and others), ready samples in `samples/` for React, Vue, Svelte, Solid, Angular, Hono, Next.js with fetch and MCP, the documentation site and tests. The skill sits in `skills/orval/`, the plugin manifest in `.claude-plugin/marketplace.json` and rules for contributing agents in `AGENTS.md`. The front page opens with a warning about version 8.0.0 and a migration guide, then lists the supported clients and links to the samples.
README badge
Original SKILL.md
---
name: orval
description: Generate type-safe API clients, TanStack Query/SWR hooks, Zod schemas, MSW mocks, Hono server handlers, MCP servers, and SolidStart actions from OpenAPI specs using Orval. Covers all clients (React/Vue/Svelte/Solid/Angular Query, Fetch, Axios), custom HTTP mutators, authentication patterns, NDJSON streaming, programmatic API, and advanced configuration.
---
# Orval - OpenAPI to TypeScript Code Generator
Orval generates type-safe TypeScript clients, hooks, schemas, mocks, and server handlers from OpenAPI v3/Swagger v2 specifications.
## Quick Start
### Installation
```bash
npm install orval -D
# or yarn add orval -D
# or pnpm add orval -D
# or bun add orval -D
```
### Minimal Configuration
```ts
import { defineConfig } from 'orval';
export default defineConfig({
petstore: {
input: {
target: './petstore.yaml',
},
output: {
target: './src/api/petstore.ts',
schemas: './src/api/model',
client: 'react-query',
},
},
});
```
### Run
```bash
npx orval
npx orval --config ./orval.config.ts
npx orval --project petstore