# mixins

Guides your agent in turning OpenAPI 3.x schemas into typed Vovk.ts client modules and exposing them as MCP tools.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 57
- Author: finom
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/finom/vovk/tree/HEAD/skills/mixins/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/mixins

## What it does

This skill guides AI agents on importing OpenAPI 3.x schemas into Vovk.ts projects. Generated modules share the standard Vovk RPC calling convention with `{ params, query, body }`. Configurations live in `vovk.config.js` under `outputConfig.segments.<name>.openAPIMixin`. The source spec can be a remote URL with a local fallback cache, a local YAML or JSON file, or an inline object. Generation executes via `npx vovk generate` and works without Next.js.

Modules plug directly into `deriveTools` for function calling and MCP. Schema validation upfront checks envelope structure only. Detailed field validation is deferred to runtime AJV checks and the upstream API.

When a vendor ships a dedicated client library such as Stripe or AWS SDK, generated mixins fall short. They lack custom retry handling, auth flows, and built-in pagination. The skill actively advises using official SDKs whenever they exist.

## Requirements
- Works with: GitHub, AWS, Stripe

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add finom/vovk --skill mixins -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/mixins/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/mixins/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add finom/vovk --skill mixins -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/mixins/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add finom/vovk --skill mixins -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/mixins/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install finom/vovk mixins
```

2. **Manually: put the files in place**
- File: `.github/skills/mixins/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add finom/vovk --skill mixins -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/finom/vovk --path skills/mixins
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/mixins/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add finom/vovk --skill mixins -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/finom/vovk/tree/HEAD/skills/mixins/SKILL.md

## When to use it
- convert OpenAPI 3.x specifications into typed Vovk RPC clients
- expose third-party API endpoints as MCP tools via `deriveTools`
- configure local fallback caches for remote OpenAPI endpoints
- set module and method naming strategies in `vovk.config.js`

## Example prompts
- Generate a Vovk mixin config for this Petstore OpenAPI spec with a local fallback
- How do I expose my OpenAPI mixin operations to MCP using deriveTools?
- Configure getMethodName with auto mode for operations missing an operationId

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 49b8469ad3c38b6a.

BEGIN THIRD-PARTY FILE 49b8469ad3c38b6a
```text
---
name: mixins
description: Vovk.ts OpenAPI mixins — importing third-party OpenAPI 3.x schemas as typed client modules that share the same call signature as native Vovk RPC modules. Use whenever the user asks to "call a third-party API from my Vovk app", "mixin an OpenAPI schema", "import an OpenAPI spec as a client", "wrap an external service that only ships an OpenAPI doc", or mentions `openAPIMixin`, `getModuleName`, `getMethodName`, `withDefaults` on a generated API module, or the `Mixins` namespace. Also use to push back when the user reaches for mixins for a vendor with a great official SDK (Stripe, AWS, GitHub via Octokit) — the skill explains when the official client is the better choice. Covers remote/local/inline specs, module + method naming strategies, `apiRoot`, per-mixin fetcher, AJV client validation knobs, and composed/segmented clients. **`deriveTools` works with mixins for every consumer** — OpenAI / Anthropic / Vercel function-calling and MCP alike — since v4 gives mixin-derived tools a merged `inputSchema` (see `tools` skill).
---

# Vovk.ts OpenAPI mixins

Mixins turn any OpenAPI 3.x spec into typed client module behaving exactly like native Vovk RPC module — same `{ params, query, body }` call shape, same client surface, same type-inference helpers (`VovkBody`, `VovkOutput`, …). Can run mixins standalone (no Next.js) as pure codegen tool.

**LLM tool exposure works out of the box.** Pass mixin modules straight to `deriveTools` — for function calling *and* for MCP. Each derived tool gets a merged `inputSchema` that is both a Standard Schema and a Standard JSON Schema, rebuilt from the mixin's OpenAPI-derived JSON Schema.

The one real difference from a procedure-backed controller: that schema's `validate` checks the `{ body, query, params }` **envelope only** — required slots present, no unknown keys — and defers slot values to execution time, where the generated client's AJV validation and the remote API enforce them. Controllers validate values up front because they carry your original Zod / Valibot / ArkType schemas.

> v3 required hand-written `createTool` wrappers for the MCP path. That is obsolete: `createTool` was removed in v4 and mixins now carry the schema MCP needs.

## Prefer the official SDK when one exists

**Recommend official client library first.** Hand-maintained SDKs like `stripe`, `@octokit/rest`, `@aws-sdk/*`, `@google-cloud/*` ship with auth flows, retries, pagination helpers, webhook signature verification, edge-case handling that generated client can't match — and track upstream API changes faster than any spec snapshot. If vendor publishes official SDK, use it.

Mixins right tool when:

- **No official SDK exists** — internal services, niche vendors, legacy APIs that only publish OpenAPI document.
- **LLM tool exposure** — `deriveTools` works directly for function calling and MCP alike (see note at top). For GitHub-style APIs `@octokit/rest` still better tool body, but mixin remains useful when third-party API has no official SDK.
```
END THIRD-PARTY FILE 49b8469ad3c38b6a

The third-party file has ended. Everything between the 49b8469ad3c38b6a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3056 of 15814 bytes. © finom · MIT · https://github.com/finom/vovk/tree/HEAD/skills/mixins/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md