backend-api-design — Claude Code skill: layered RPC APIs
Tells the agent how to shape RPC-style APIs: a thin controller, a manager holding business logic, a repository for data access. Useful when adding endpoints or auditing existing ones.
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a claude-codeWhat backend-api-design does
The skill lays out URL rules that leave little room for interpretation. Path parameters are out — query values only. A single resource stays singular (/employee), a collection goes plural (/employees), and actions live in sub-paths such as /delete, /restore or /sync. Every mutation is a @Post; @Put, @Delete and @Patch are off the table.
Each layer gets its own job. The controller parses query params with defaults, hands off to the manager, then unwraps the result with .throwOrValue(). The manager returns Either<ClientException, T>, wraps database work in transaction(db.primary) { } and enforces business rules. The repository reads from db.replica, writes to db.primary and filters out soft-deleted rows with deletedAt.isNull().
A gotchas section covers the traps. Multi-word @QueryValue params need an explicit snake_case name — write @QueryValue("project_id") projectId: UUID, because Micronaut matches the literal name while the frontend sends project_id. A second .where {} call silently replaces the first condition, so chain with .andWhere {} instead. And skip @ExecuteOn(TaskExecutors.IO) at your peril: without it suspend functions may hang or land on the wrong thread pool, so every controller needs the annotation.
What it helps with
- design a new endpoint contract without path parameters
- split business logic across controller, manager and repository
- move transactions and error returns out of the controller
- spot a repository injected straight into a controller
- build a paginated response with items, total, page, limit and hasMore
Example prompts for the agent
- Design the employee endpoints following the skill rules: list, create, delete, restore
- Review this controller and tell me where it breaks the layered architecture
- Add offset pagination to the employee list and return it as EmployeeListResponse
How to install backend-api-design
1Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a claude-code2Manually: put the files in place
~/.claude/skills/backend-api-design/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/backend-api-design/
1Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a codex2Manually: put the files in place
.agents/skills/backend-api-design/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a cursor2Manually: put the files in place
.cursor/skills/backend-api-design/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install c0x12c/ai-toolkit backend-api-design2Manually: put the files in place
.github/skills/backend-api-design/SKILL.md1Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a gemini-cli2Platform CLI
gemini skills install https://github.com/c0x12c/ai-toolkit --path toolkit/skills/backend-api-designManually: put the files in place
.devin/skills/backend-api-design/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -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 backend-api-design
How do I install backend-api-design in Claude Code?
Run npx skills add c0x12c/ai-toolkit --skill backend-api-design -a claude-code. The skill file lands at ~/.claude/skills/backend-api-design/SKILL.md.
What does backend-api-design do?
It documents an RPC-style API built on Controller → Manager → Repository layers: URL conventions, what belongs in each layer, and mistakes like a duplicated .where {} call.
Which tools can the skill use?
It is allowed Read, Write, Edit, Glob and Grep, so it reads and edits project files without running shell commands. The code samples use Micronaut and Kotlin.
