Borrowing it
Nothing to install: this file belongs to KbWen/agentic-os. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.
curl -O https://raw.githubusercontent.com/KbWen/agentic-os/main/.agents/skills/api-design/SKILL.mdgit clone --depth 1 https://github.com/KbWen/agentic-osWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/kbwen/agentic-os/api-design)<a href="https://agentmods.dev/skills/kbwen/agentic-os/api-design"><img src="https://agentmods.dev/badge/skills/kbwen/agentic-os/api-design/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/kbwen/agentic-os/api-design"><img src="https://agentmods.dev/badge/skills/kbwen/agentic-os/api-design.svg" alt="Reviewed on agentmods" width="80" height="20"></a>- NVIDIA SkillSpector pass
What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00017 | $0.01024 |
| Opus 5.5 | $0.00007 | $0.00410 |
| Sonnet 5.5 | $0.00003 | $0.00205 |
| Haiku 4.5 | $0.00002 | $0.00102 |
Grade A, and why
api-design scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 13d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
Copies of this mod
2 near-identical copies found in the catalogue:
- api-design — 100% identical, 2 lines differ
- KbWen__agentic-os — 91% identical, 11 lines differ
How it starts
The opening of the file, as written. The whole thing — 127 lines — stays where its author put it; the contents beside it link to each section on GitHub.
API Design
When to Apply
- Classification: feature, architecture-change, hotfix (if touching API endpoints)
- Phase: /implement (design & build), /review (compliance check), /test (contract verification)
- Trigger: Task involves creating, modifying, or deprecating API endpoints
Conventions
Customize after /app-init: Replace these generic conventions with your project's ADR decisions.
Endpoint Naming
- Use nouns for resources, not verbs:
GET /usersnotGET /getUsers - Plural resource names:
/users,/orders,/products - Nested resources for relationships:
/users/:id/orders - Use kebab-case for multi-word paths:
/order-items
HTTP Methods
| Action | Method | Success Status | Idempotent |
|---|---|---|---|
| List | GET | 200 | Yes |
| Get one | GET | 200 | Yes |
| Create | POST | 201 | No |
| Full update | PUT | 200 | Yes |
| Partial update | PATCH | 200 | No |
| Delete | DELETE | 204 | Yes |
Error Response Format
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Email is required",
"details": {
"field": "email",
"constraint": "required"
}
}
}
Standard Error Codes
| HTTP Status | When | Error Code Pattern |
|---|---|---|
| 400 | Invalid input | VALIDATION_ERROR, INVALID_FORMAT |
| 401 | Not authenticated | UNAUTHORIZED |
| 403 | Not permitted | FORBIDDEN |
| 404 | Resource not found | NOT_FOUND |
| 409 | Conflict (duplicate) | CONFLICT, DUPLICATE |
| 422 | Business rule violation | UNPROCESSABLE |
| 429 | Rate limited | RATE_LIMITED |
| 500 | Server error | INTERNAL_ERROR |
Pagination
{
"data": [...],
"pagination": {
"total": 100,
"page": 1,
"per_page": 20,
"has_next": true
}
}
Versioning
- URL path versioning:
/api/v1/users - Breaking changes require new version
- Deprecation: add
Sunsetheader with date, keep old version for N months
Input Validation
- Validate at the controller/route level BEFORE business logic
- Return ALL validation errors at once (batch), not one at a time
- Sanitize strings: trim whitespace, escape HTML where applicable
- Enforce max lengths on all string fields
What ships with it
1 file beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 13d ago Changed d1f9e506a8b5
- 1mo ago First seen · 127 lines · 17 tokens per session scan A 3bb02b810098
api-design is a skill published in the GitHub repository KbWen/agentic-os (220 stars, last pushed yesterday), licensed MIT. It adds 17 tokens to every session and 1,024 once invoked, about $0.0001 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
muster-frappe-metadata
Design, generate, review, apply, and roll back Frappe or ERPNext metadata changes through Muster. Use for DocTypes, child tables, custom fields, property setters, workflows, roles, permissions, reports, print formats, web pages, workspaces, fixtures, patches, or installed-app compatibility.
new
Create a new project to start development quickly.
workflow-ai-coding
Edit, validate, debug, publish, and inspect ReachAI Workflow drafts through the Workflow AI Coding REST API. Use when asked to create or modify a workflow graph, add/update/delete nodes or edges, validate GraphSpec, dry-run or debug-run a workflow, inspect trace/run output, check release readiness, publish a validated…
agenticx-tool-creator
Guide for creating custom tools in AgenticX including function decorator tools, MCP tool integration, tool registries, and remote tool access. Use when the user wants to create tools for agents, integrate external APIs as tools, build MCP servers, or extend agent capabilities with custom functions.
channel-manager
Configure IM platform channels (Feishu, WeCom, Weixin, Discord, Telegram, DingTalk, QQ) for openclacky. Uses browser automation for navigation; guides the user to paste credentials and perform UI steps. Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "setup discord", "setup…
notion-tool
A Notion integration tool. It performs page and database search, retrieval, creation, and updates via the API. Use when: Use when: you need to edit Notion pages, add database rows, or search and retrieve workspace content.