菜单
Use when designing, building, or reviewing REST/GraphQL APIs — covers endpoint design, error handling, versioning, authentication, and documentation
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Use when containerizing applications, writing Dockerfiles, creating docker-compose configs, or setting up CI/CD deployment pipelines
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
Use when you have an implementation plan to execute, or when facing 2+ independent tasks/bugs — supports sequential execution, parallel dispatch (if available), and single-agent fallback
Use when reviewing code for security issues, handling secrets, setting up authentication, auditing dependencies, or before deploying to production
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
基于 SOC 职业分类
| name | api-design |
| description | Use when designing, building, or reviewing REST/GraphQL APIs — covers endpoint design, error handling, versioning, authentication, and documentation |
Good APIs are consistent, predictable, and hard to misuse.
Core principle: Design the API from the consumer's perspective first, then implement.
GET /api/v1/users # List
POST /api/v1/users # Create
GET /api/v1/users/:id # Read
PUT /api/v1/users/:id # Replace
PATCH /api/v1/users/:id # Partial update
DELETE /api/v1/users/:id # Delete
Rules:
/users not /getUsers)/users not /user)/users/:id/posts)/user-profiles not /userProfiles)| Method | Success | Common Errors |
|---|---|---|
| GET | 200 | 404 not found |
| POST | 201 + Location header | 400 validation, 409 conflict |
| PUT/PATCH | 200 | 400 validation, 404 not found |
| DELETE | 204 (no body) | 404 not found |
Always use consistent error shape:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable description",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
}
}
Rules:
code (UPPER_SNAKE_CASE)messagedetails array for field-level errorsGET /api/v1/users?page=2&limit=20
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 156,
"totalPages": 8
}
}
For large datasets, prefer cursor-based:
GET /api/v1/events?cursor=abc123&limit=50
GET /api/v1/users?status=active&role=admin # Filter
GET /api/v1/users?sort=-created_at,name # Sort (- = desc)
GET /api/v1/users?fields=id,name,email # Sparse fields
Use URL versioning (/api/v1/) for simplicity:
Deprecation flow:
Sunset header with dateWarning header| Method | When to Use |
|---|---|
| Bearer Token (JWT) | SPAs, mobile apps |
| API Key | Server-to-server, third-party integrations |
| OAuth 2.0 | Third-party access delegation |
| Session Cookie | Traditional web apps |
Security checklist:
Every API endpoint needs:
# Example: OpenAPI / Swagger format
paths:
/users:
get:
summary: List users
parameters:
- name: status
in: query
schema:
type: string
enum: [active, inactive]
responses:
200:
description: Success
401:
description: Unauthorized
Document: