# safe-action-client

Guides agents in configuring next-safe-action clients and defining type-safe Next.js server actions with input schemas and structured error returns.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1200 installs · ★ 1
- Author: next-safe-action
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/next-safe-action/skills/tree/HEAD/skills/safe-action-client/SKILL.md
- Updated: 2026-09-03
- HTML: https://affpapa.org/en/nevibecode/skills/safe-action-client

## What it does

This skill guides coding assistants through setting up `createSafeActionClient` and building server actions with Standard Schema validators like Zod or Valibot. It enforces the immutable chaining order, sequencing middleware, schema definitions, and action handlers properly.

The model stops omitting the `"use server"` declaration at the top of action modules. If `defineMetadataSchema` is configured on the client, skipping `.metadata()` before `.action()` triggers a TypeScript compiler error immediately.

It also clarifies server error mechanics. Instead of returning plain objects, the assistant uses `returnValidationErrors` for form fields and `returnServerError` for anticipated domain issues.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add next-safe-action/skills --skill safe-action-client -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add next-safe-action/skills --skill safe-action-client -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add next-safe-action/skills --skill safe-action-client -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install next-safe-action/skills safe-action-client
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add next-safe-action/skills --skill safe-action-client -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/next-safe-action/skills --path skills/safe-action-client
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add next-safe-action/skills --skill safe-action-client -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/next-safe-action/skills/tree/HEAD/skills/safe-action-client/SKILL.md

## When to use it
- configure `createSafeActionClient` with input and output schemas
- attach pre-validation and post-validation middleware to the client chain
- return typed field-level validation errors using `returnValidationErrors`
- define stateful actions for optimistic UI updates via `stateAction`

## Example prompts
- Set up a `createSafeActionClient` instance in `src/lib/safe-action.ts` with custom metadata validation.
- Create a Next.js server action validating email input with Zod and returning `returnValidationErrors` if already taken.
- Build a state action using `stateAction` to manage an optimistic counter.

## Similar
- [mcp-builder](https://affpapa.org/en/nevibecode/skills/mcp-builder.md) — skill · 130949 installs
- [claude-api](https://affpapa.org/en/nevibecode/skills/claude-api.md) — skill · 74198 installs
- [lark-im](https://affpapa.org/en/nevibecode/skills/lark-im.md) — skill · 472900 installs
- [lark-event](https://affpapa.org/en/nevibecode/skills/lark-event.md) — skill · 466800 installs
- [caveman-discover](https://affpapa.org/en/nevibecode/skills/caveman-discover.md) — skill · 104400 installs
- [migration](https://affpapa.org/en/nevibecode/skills/migration.md) — skill · 103900 installs

From the same set: [next-safe-action/skills](https://affpapa.org/en/nevibecode/by/next-safe-action/skills.md) — 9 cards

---
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