afrexai-api-architect
Design, build, test, document, and secure production-grade APIs. Covers the full lifecycle from schema design through deployment, monitoring, and versioning
Install / Use
npx skills add LeoYeAI/openclaw-master-skills --skill afrexai-api-architectInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
Our assessment of afrexai-api-architect
afrexai-api-architect scores 90/100 on our quality scale, 321st of 745 Operations skills we index (top 44%).
Its SKILL.md is 26 KB long, well organised into 94 sections with 23 code examples: a thorough specification that gives an agent plenty to work with.
With 2,149 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-10-30 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 98/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-30. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
afrexai-api-architect compared with similar skills
All 4 of these similar skills score higher than afrexai-api-architect; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| afrexai-api-architect (this skill)by LeoYeAI | 90 | 2.1k | 4mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
Frequently asked questions
- How do I install afrexai-api-architect?
- Run
npx skills add LeoYeAI/openclaw-master-skills --skill afrexai-api-architect. The install tabs above show the steps for each supported agent. - Which AI agents does afrexai-api-architect work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is afrexai-api-architect safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 98/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is afrexai-api-architect still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: afrexai-api-architect description: Design, build, test, document, and secure production-grade APIs. Covers the full lifecycle from schema design through deployment, monitoring, and versioning. Use when designing new APIs, reviewing existing ones, generating OpenAPI specs, building test suites, or debugging production issues. metadata: {"openclaw":{"os":["linux","darwin","win32"]}}
API Architect — Full Lifecycle API Development
Design, build, test, document, secure, and monitor production-grade APIs. Not just curl commands — a complete engineering methodology.
When to Use
- Designing a new API (REST, GraphQL, or gRPC)
- Reviewing an existing API for quality, consistency, or security
- Generating or validating OpenAPI/Swagger specs
- Building comprehensive test suites (unit, integration, contract, load)
- Debugging production API issues
- Planning API versioning and deprecation
- Setting up monitoring, rate limiting, and error handling
Phase 1: API Design
Design-First Approach
Always design before coding. The spec IS the contract.
Resource Modeling
Map your domain to resources using this template:
# api-design.yaml
service: order-management
base_path: /api/v1
resources:
- name: orders
path: /orders
description: Customer purchase orders
identifier: order_id (UUID)
parent: null
operations: [list, create, get, update, cancel]
sub_resources:
- name: line_items
path: /orders/{order_id}/items
operations: [list, add, update, remove]
- name: payments
path: /orders/{order_id}/payments
operations: [list, create, get, refund]
states: [draft, confirmed, processing, shipped, delivered, cancelled]
transitions:
- from: draft → to: confirmed (action: confirm)
- from: confirmed → to: processing (action: process)
- from: processing → to: shipped (action: ship)
- from: shipped → to: delivered (action: deliver)
- from: [draft, confirmed] → to: cancelled (action: cancel)
Naming Conventions Checklist
| Rule | Good | Bad |
|------|------|-----|
| Plural nouns for collections | /users | /user, /getUsers |
| Kebab-case for multi-word | /line-items | /lineItems, /line_items |
| No verbs in URLs | POST /orders | /createOrder |
| Nest for ownership | /users/123/orders | /orders?user=123 (for primary relationship) |
| Max 3 levels deep | /users/123/orders | /users/123/orders/456/items/789/options |
| Filter via query params | /orders?status=active | /active-orders |
| Actions as sub-resource | POST /orders/123/cancel | PATCH /orders/123 {cancelled:true} |
HTTP Methods — Decision Matrix
Need to... → Method Idempotent? Safe?
Get a resource or collection → GET Yes Yes
Create a new resource → POST No No
Full replace of a resource → PUT Yes No
Partial update of a resource → PATCH No* No
Remove a resource → DELETE Yes No
Check if resource exists → HEAD Yes Yes
List allowed methods → OPTIONS Yes Yes
* PATCH can be idempotent if using JSON Merge Patch
Status Code Decision Tree
Success?
├── Created something new? → 201 Created (Location header)
├── Accepted for async processing? → 202 Accepted (include status URL)
├── No body to return? → 204 No Content
└── Returning data? → 200 OK
Client error?
├── Malformed request syntax? → 400 Bad Request
├── No/invalid credentials? → 401 Unauthorized
├── Valid credentials but insufficient permissions? → 403 Forbidden
├── Resource doesn't exist? → 404 Not Found
├── Method not allowed on resource? → 405 Method Not Allowed
├── Conflict with current state? → 409 Conflict
├── Resource permanently gone? → 410 Gone
├── Validation failed? → 422 Unprocessable Entity
├── Too many requests? → 429 Too Many Requests (Retry-After header)
└── Precondition failed (etag mismatch)? → 412 Precondition Failed
Server error?
├── Unexpected failure? → 500 Internal Server Error
├── Upstream dependency failed? → 502 Bad Gateway
├── Temporarily overloaded? → 503 Service Unavailable (Retry-After)
└── Upstream timeout? → 504 Gateway Timeout
Request/Response Design
Standard Response Envelope
// Success (single resource)
{
"data": { "id": "ord_abc123", "status": "confirmed", ... },
"meta": { "request_id": "req_xyz789" }
}
// Success (collection)
{
"data": [ ... ],
"meta": { "request_id": "req_xyz789" },
"pagination": {
"total": 142,
"page": 2,
"per_page": 20,
"total_pages": 8,
"next": "/api/v1/orders?page=3&per_page=20",
"prev": "/api/v1/orders?page=1&per_page=20"
}
}
// Error
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Request validation failed",
"details": [
{ "field": "email", "message": "Must be a valid email address", "code": "INVALID_FORMAT" },
{ "field": "age", "message": "Must be at least 18", "code": "MIN_VALUE", "min": 18 }
]
},
"meta": { "request_id": "req_xyz789" }
}
Pagination Patterns — When to Use Which
| Pattern | Use When | Pros | Cons |
|---------|----------|------|------|
| Offset ?page=2&per_page=20 | Simple UI pagination, small datasets | Easy to implement, page jumping | Drift on inserts, slow on large offsets |
| Cursor ?after=eyJ...&limit=20 | Infinite scroll, real-time feeds, large datasets | Consistent, performant | No page jumping, opaque cursors |
| Keyset ?created_after=2024-01-01&limit=20 | Time-series data, logs | Fast, transparent | Requires sortable field, no count |
Filtering, Sorting, Field Selection
# Filtering
GET /orders?status=active&created_after=2024-01-01&total_min=100
# Sorting (prefix - for descending)
GET /orders?sort=-created_at,total
# Field selection (reduce payload)
GET /orders?fields=id,status,total,customer.name
# Search
GET /products?q=wireless+headphones
# Combined
GET /orders?status=active&sort=-created_at&fields=id,status,total&page=1&per_page=10
Phase 2: OpenAPI Specification
Generate OpenAPI 3.1 Spec
For each resource in your design, generate a complete spec:
openapi: 3.1.0
info:
title: Order Management API
version: 1.0.0
description: |
Order lifecycle management.
## Authentication
All endpoints require Bearer token authentication.
## Rate Limits
- Standard: 100 req/min
- Bulk operations: 10 req/min
contact:
name: API Support
email: api@example.com
license:
name: MIT
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
paths:
/orders:
get:
operationId: listOrders
summary: List orders
tags: [Orders]
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PerPageParam'
- name: status
in: query
schema:
$ref: '#/components/schemas/OrderStatus'
- name: created_after
in: query
schema:
type: string
format: date-time
responses:
'200':
description: Order list
content:
application/json:
schema:
$ref: '#/components/schemas/OrderListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createOrder
summary: Create an order
tags: [Orders]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
examples:
basic:
summary: Basic order
value:
customer_id: "cust_abc"
items:
- product_id: "prod_xyz"
quantity: 2
responses:
'201':
description: Order created
headers:
Location:
schema:
type: string
description: URL of created order
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'422':
$ref: '#/components/responses/ValidationError'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
parameters:
PageParam:
name: page
in: query
schema: { type: integer, minimum: 1, default: 1 }
PerPageParam:
name: per_page
in: query
schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
responses:
Unauthorized:
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ValidationError:
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- BearerAuth: []
Spec Quality Checklist (score each 0-2)
| # | Check | Score | |---|-------|-------| | 1 | Every endpoint has operationId | /2 | | 2 | All parameters documented with types + constraints | /2 | | 3 | Request bodies have examples | /2 | | 4 | All error responses documented (400, 401, 403, 404, 422, 429, 500) | /2 | | 5 | Shared schemas use $ref (DRY) | /2 | | 6 | Pagination parameters standardized | /2 | | 7 | Security scheme defined + applied globally | /2 | | 8 | Description includes auth, rate limits, versioning info | /2 | | 9 | Response headers documented (Location, Retry-After, ETag) | /2 | | 10 | Enums used for fixed value sets | /2 |
Score: ___/20 (Target: 16+)
Phase 3: Implementation Patterns
Request Validation Layer
Every endpoint MUST validate before processing:
Validation Order:
1. Content-Type header (reject non-JSON early)
2. Authentication (401 before wasting cycles)
3. Authorization (403 - does this user have access?)
4. Path parameters (404 - does the resource exist?)
5. Query parameters (400 - valid types/ranges?)
6. Request body schema (422 - valid structure?)
7. Business rules (422 - valid state transition?)
Error Handling — Standard Error Codes
Define a consistent error code enum for your API:
# Authentication & Authorization
AUTH_REQUIRED — No credentials provided
AUTH_INVALID — Invalid/expired credentials
AUTH_INSUFFICIENT — Valid credentials, wrong permissions
AUTH_RATE_LIMITED — Too many auth attempts
# Validation
VALIDATION_FAILED — Generic validation error (see details array)
INVALID_FORMAT — Field format wrong (email, UUID, etc.)
REQUIRED_FIELD — Required field missing
OUT_OF_RANGE — Value outside allowed range
INVALID_ENUM — Value not in allowed set
# Resource
NOT_FOUND — Resource doesn't exist
ALREADY_EXISTS — Duplicate (unique constraint)
CONFLICT — State conflict (e.g., already cancelled)
GONE — Resource permanently deleted
# Business Logic
INSUFFICIENT_FUNDS — Payment-related
QUOTA_EXCEEDED — Usage limit reached
FEATURE_DISABLED — Feature flag off
DEPENDENCY_FAILED — Upstream service error
# System
INTERNAL_ERROR — Unexpected server error
SERVICE_UNAVAILABLE — Temporarily down
TIMEOUT — Request took too long
Idempotency
For non-idempotent operations (POST), require an idempotency key:
Request:
POST /orders
Idempotency-Key: ord_req_abc123
Server behavior:
1. Check if Idempotency-Key was seen before
2. If yes → return cached response (same status, same body)
3. If no → process request, cache response for 24h
4. Key format: client-generated UUID or
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
