SkillAgentSearch skills...

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-architect

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

90/100

Category

Operations

Supported Platforms

Universal

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.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
14/20
Freshness
11/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
afrexai-api-architect (this skill)by LeoYeAI902.1k4mo agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.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.

name: 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

View on GitHub
GitHub Stars2.1k
CategoryOperations
Updated3mo ago
Forks325

Languages

Python

Trust signals

98/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info