safe-action-middleware — Claude Code skill
A skill that walks your agent through writing next-safe-action middleware: auth, authorization, logging, rate limits and context extension.
npx skills add next-safe-action/skills --skill safe-action-middleware -a claude-codeWhat safe-action-middleware does
The skill covers both middleware types in next-safe-action. .use() runs before input validation, so it fits session checks, logging and rate limiting. .useValidated() runs after schema parsing and hands you a typed parsedInput, which is what you want when the check depends on the payload — confirming a user owns a record, for instance.
Each .use() call returns a fresh client, and context accumulates through next({ ctx }) with a deep merge. Execution goes top-to-bottom through the pre-validation stack, then schema parsing, then the post-validation stack, and finally your .action() code. Forget the return before next() and the action hangs.
Order matters for schemas too. Define .inputSchema() or .bindArgsSchemas() before .useValidated(); calling them afterwards, or adding .use() after .useValidated(), won't compile. Context added by .use() is always present in onError and onSettled callbacks. Context from .useValidated() may be missing, because that middleware never runs when validation fails.
What it helps with
- Check the session before an action body executes
- Cap how often a server action can be called
- Attach the current user's id to the action context
- Verify a record belongs to the signed-in user
- Log the parsed input rather than the raw payload
Example prompts for the agent
- Add a
.use()middleware that checks the session on my action client - Write a
.useValidated()middleware that confirms the post belongs to the user in context - Chain logging and rate-limit middleware in the right order
How to install safe-action-middleware
1Skills CLI (Vercel)
npx skills add next-safe-action/skills --skill safe-action-middleware -a claude-code2Manually: put the files in place
~/.claude/skills/safe-action-middleware/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/safe-action-middleware/
1Skills CLI (Vercel)
npx skills add next-safe-action/skills --skill safe-action-middleware -a codex2Manually: put the files in place
.agents/skills/safe-action-middleware/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add next-safe-action/skills --skill safe-action-middleware -a cursor2Manually: put the files in place
.cursor/skills/safe-action-middleware/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install next-safe-action/skills safe-action-middleware2Manually: put the files in place
.github/skills/safe-action-middleware/SKILL.md1Skills CLI (Vercel)
npx skills add next-safe-action/skills --skill safe-action-middleware -a gemini-cli2Platform CLI
gemini skills install https://github.com/next-safe-action/skills --path skills/safe-action-middlewareManually: put the files in place
.devin/skills/safe-action-middleware/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add next-safe-action/skills --skill safe-action-middleware -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about safe-action-middleware
How do I install safe-action-middleware in Claude Code?
Run npx skills add next-safe-action/skills --skill safe-action-middleware -a claude-code. The skill lands at ~/.claude/skills/safe-action-middleware/SKILL.md.
What does safe-action-middleware do?
It guides the agent through next-safe-action middleware: authentication, authorization, logging, rate limiting, error interception and context extension.
When should I use .useValidated() instead of .use()?
Only when the middleware logic needs validated input. .use() sees the raw clientInput and is the default choice for session checks and logging; .useValidated() gets the typed parsedInput for ownership checks.
