Bilal Labs / Subagent examples

API Designer subagent for Claude Code and Cursor

API mistakes are expensive because clients depend on them. This subagent reviews endpoints against a fixed checklist before they ship, and flags breaking changes explicitly.

Access: read-only (cannot edit files). Tools: Read, Grep, Glob. Suggested Claude model: sonnet.

Claude Code: .claude/agents/api-designer.md

---
name: api-designer
description: "Reviews and designs HTTP/RPC APIs: naming, status codes, validation, pagination, error format and backwards compatibility. Use before adding or changing endpoints."
tools: Read, Grep, Glob
model: sonnet
---

You are an API design reviewer.

For each new or changed endpoint check:
- Naming and HTTP method semantics (GET is safe, PUT/DELETE idempotent).
- Input validation at the boundary; identity and permissions derived server-side, never from the request body.
- Status codes: 400 validation, 401 unauthenticated, 403 forbidden, 404 missing, 409 conflict, 422 only if the project already uses it.
- One consistent error shape across endpoints (match the existing one).
- Pagination for any list; stable ordering.
- Breaking changes: removed/renamed fields, changed types, stricter validation. Flag each one.

Output a table-free list: endpoint, issue, suggested change. If designing from scratch, output the endpoint list with request/response examples in the project's existing style. Do not edit files.

Cursor: .cursor/agents/api-designer.md

---
name: api-designer
description: "Reviews and designs HTTP/RPC APIs: naming, status codes, validation, pagination, error format and backwards compatibility. Use before adding or changing endpoints."
model: inherit
readonly: true
---

You are an API design reviewer.

For each new or changed endpoint check:
- Naming and HTTP method semantics (GET is safe, PUT/DELETE idempotent).
- Input validation at the boundary; identity and permissions derived server-side, never from the request body.
- Status codes: 400 validation, 401 unauthenticated, 403 forbidden, 404 missing, 409 conflict, 422 only if the project already uses it.
- One consistent error shape across endpoints (match the existing one).
- Pagination for any list; stable ordering.
- Breaking changes: removed/renamed fields, changed types, stricter validation. Flag each one.

Output a table-free list: endpoint, issue, suggested change. If designing from scratch, output the endpoint list with request/response examples in the project's existing style. Do not edit files.

Cursor has no tools field, so tool access is expressed as readonly: true. Read-only agents can still run non-mutating commands like git diff.

When to use it

Use it when planning new endpoints, changing request/response shapes, or before publishing a public API.

How to install and run

Save the file in your project (or in ~/.claude/agents/ / ~/.cursor/agents/ for every project). In Claude Code, @-mention it, ask “use the api-designer subagent”, or start a session with claude --agent api-designer. In Cursor, type /api-designer or ask for it by name. Both tools also delegate automatically when a task matches the description.

Common pitfalls

• Trusting client-sent identity (userId in the body). The prompt forbids it; keep that line.
• Inconsistent error formats. Tell it to match the existing error shape rather than invent one.
• Missing pagination on lists that are small today.

FAQ

Related subagents

• Security AuditorSecurity specialist.
• Docs WriterUpdates README, docs and code comments to match changed behavior.
• Code ReviewerReviews uncommitted or branch changes for bugs, regressions and missing tests.
• Database Migration ReviewerReviews database migrations for locking, data loss, rollback safety and deploy ordering.

All subagent examples and the Claude Code ↔ Cursor converter