菜单
Conçoit des APIs REST/GraphQL avec OpenAPI spec, versioning, et documentation. Utiliser pour les projets API-first, quand on définit des endpoints, ou quand l'utilisateur dit "API", "endpoints", "REST", "GraphQL". Peut être déclenché après PRD ou Architecture.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/majiayu000/claude-skill-registry --skill api-designer命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
LLM token logprobs and calibration. Per-decision confidence, ECE, Brier, reliability diagrams, low-confidence triage.
Analyze LLM token logprobs and calibration. Use for per-decision confidence, ECE, Brier scores, reliability diagrams, and low-confidence triage.
回顾最近 N 天的 Claude Code 使用记录——扫描原始会话数据，按主题分组汇总"我都做了什么"，并从个人操作系统视角输出模式、风险与增删建议。当用户说 /recap、"看看我这几天做了什么"、"回顾一下我最近的会话"、"这两天我用 claude 干了啥"、"活动回顾" 时使用。
基于 SOC 职业分类
正在显示 SKILL.md
| name | api-designer |
| description | Conçoit des APIs REST/GraphQL avec OpenAPI spec, versioning, et documentation. Utiliser pour les projets API-first, quand on définit des endpoints, ou quand l'utilisateur dit "API", "endpoints", "REST", "GraphQL". Peut être déclenché après PRD ou Architecture. |
| model | opus |
| context | fork |
| agent | Plan |
| allowed-tools | ["Read","Glob","Grep","Write","Edit","Bash","Task","TaskCreate","TaskUpdate","TaskList","TaskGet","mcp__github__get_issue","mcp__github__list_issues"] |
| argument-hint | <api-name-or-prd-reference> |
| user-invocable | true |
| hooks | {"post_tool_call":[{"tool":"Write","match":"openapi*.yaml","run":"npx @redocly/cli lint $file 2>/dev/null || true"}]} |
| knowledge | {"core":[".claude/knowledge/workflows/api-design-template.md"],"advanced":[".claude/knowledge/workflows/api-versioning.md",".claude/knowledge/workflows/api-security.md"]} |
Je vais concevoir une API complète avec spécification OpenAPI, documentation et patterns.
Au démarrage, rassembler le contexte pour concevoir l'API.
| Contexte | Pattern/Action | Priorité |
|---|---|---|
| PRD existant | Glob: docs/planning/prd/*.md | Optionnel |
| Architecture | Glob: docs/planning/architecture/*.md | Optionnel |
| APIs existantes | Glob: openapi*.yaml openapi*.json swagger*.yaml | Optionnel |
| Routes existantes | Glob: **/api/**/*.ts | Optionnel |
| Framework backend | Grep: package.json pour express/fastify/hono/next/nestjs | Requis |
Avant de commencer, je vérifie :
Rôle : Architecte API qui conçoit des interfaces robustes, documentées et évolutives.
Principes :
Règles :
Input requis : PRD, user stories, ou description fonctionnelle
Je détermine :
| Aspect | Questions |
|---|---|
| Consommateurs | Web app? Mobile? Third-party? |
| Volume | Requests/sec attendus? |
| Auth | Public? API Key? OAuth? JWT? |
| Format | JSON? XML? Multipart? |
⏸️ STOP - Valider les besoins avant de continuer
Pour chaque ressource, je définis :
Resource: [Name]
Description: [What it represents]
Attributes:
- id: uuid (read-only)
- name: string (required)
- created_at: datetime (read-only)
Relations:
- belongs_to: [Parent]
- has_many: [Children]
| Type | Convention | Exemple |
|---|---|---|
| Resources | Pluriel, kebab-case | /api/v1/user-profiles |
| Query params | snake_case | ?page_size=20 |
| Body fields | camelCase | { "firstName": "John" } |
| Headers | Title-Case | X-Request-Id |
⏸️ STOP - Valider les ressources avant les endpoints
Pour chaque endpoint :
Endpoint: GET /api/v1/resources
Summary: List all resources
Auth: Bearer token
Query params:
- page: integer (default: 1)
- page_size: integer (default: 20, max: 100)
- sort: string (default: -created_at)
- filter[status]: string
Response 200:
- data: Resource[]
- meta: { total, page, page_size }
- links: { self, next, prev }
Response 401: Unauthorized
Response 403: Forbidden
| Action | Method | Endpoint | Success | Errors |
|---|---|---|---|---|
| List | GET | /resources | 200 | 401, 403 |
| Create | POST | /resources | 201 | 400, 401, 403, 422 |
| Read | GET | /resources/:id | 200 | 401, 403, 404 |
| Update | PATCH | /resources/:id | 200 | 400, 401, 403, 404, 422 |
| Replace | PUT | /resources/:id | 200 | 400, 401, 403, 404, 422 |
| Delete | DELETE | /resources/:id | 204 | 401, 403, 404 |
⏸️ STOP - Valider les endpoints avant la spec OpenAPI
Je génère une spec OpenAPI 3.1 complète :
openapi: 3.1.0
info:
title: [API Name]
version: 1.0.0
description: [Description]
servers:
- url: https://api.example.com/v1
description: Production
- url: https://api.staging.example.com/v1
description: Staging
security:
- bearerAuth: []
paths:
/resources:
get:
summary: List resources
operationId: listResources
tags: [Resources]
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PageSizeParam'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceList'
example:
data:
- id: "123e4567-e89b-12d3-a456-426614174000"
name: "Example"
meta:
total: 100
page: 1
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
Resource:
type: object
required: [name]
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
minLength: 1
maxLength: 255
parameters:
PageParam:
name: page
in: query
schema:
type: integer
minimum: 1
default: 1
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request body is invalid",
"details": [
{
"field": "email",
"code": "INVALID_FORMAT",
"message": "Must be a valid email address"
}
],
"request_id": "req_abc123"
}
}
| HTTP | Code | Usage |
|---|---|---|
| 400 | BAD_REQUEST | Requête malformée |
| 401 | UNAUTHORIZED | Auth manquante/invalide |
| 403 | FORBIDDEN | Pas les permissions |
| 404 | NOT_FOUND | Ressource inexistante |
| 409 | CONFLICT | Conflit (duplicate) |
| 422 | VALIDATION_ERROR | Validation échouée |
| 429 | RATE_LIMITED | Trop de requêtes |
| 500 | INTERNAL_ERROR | Erreur serveur |
| Stratégie | Exemple | Quand utiliser |
|---|---|---|
| URL Path | /api/v1/users | API publique, breaking changes fréquents |
| Header | X-API-Version: 2 | API interne, flexibilité |
| Query | ?version=2 | Transition temporaire |
Recommandation : URL Path pour la clarté
Deprecation Policy:
- Announce: 6 months before removal
- Sunset header: Sunset: Sat, 31 Dec 2024 23:59:59 GMT
- Deprecation header: Deprecation: true
- Documentation: Clear migration guide
Rate Limits:
Default:
requests: 1000
window: 1 hour
Authenticated:
requests: 10000
window: 1 hour
Headers:
- X-RateLimit-Limit: 1000
- X-RateLimit-Remaining: 999
- X-RateLimit-Reset: 1640995200
Je génère aussi :
# API Design: [Name]
## Overview
| Aspect | Value |
|--------|-------|
| **Type** | REST / GraphQL |
| **Base URL** | `https://api.example.com/v1` |
| **Auth** | Bearer JWT |
| **Format** | JSON |
## Resources
### [Resource 1]
[Description]
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | uuid | read-only | Unique identifier |
## Endpoints
### [Resource 1]
#### List [Resources]
`GET /api/v1/resources`
[Details...]
## OpenAPI Spec
See: `docs/api/openapi.yaml`
## Error Codes
[Table...]
## Rate Limits
[Details...]
## Changelog
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | YYYY-MM-DD | Initial release |
Fichier : docs/api/API-{slug}.md
OpenAPI : docs/api/openapi-{slug}.yaml
| Critère | Status |
|---|---|
| Ressources identifiées et documentées | ✅/❌ |
| Endpoints CRUD complets | ✅/❌ |
| OpenAPI spec valide (lint pass) | ✅/❌ |
| Erreurs documentées | ✅/❌ |
| Auth/Security définis | ✅/❌ |
| Exemples inclus | ✅/❌ |
| Versioning strategy définie | ✅/❌ |
Score minimum : 6/7
## 🔗 Prochaine étape
✅ API Design terminé et sauvegardé.
→ 🏗️ **Lancer `/architect`** pour intégrer l'API dans l'architecture globale ?
→ 📝 **Lancer `/pm-stories`** pour créer les stories d'implémentation ?
---
**[A] Architecture** | **[S] Stories** | **[P] Pause**
/api-designer user-management
/api-designer docs/planning/prd/PRD-saas-dashboard.md
/api-designer --type graphql e-commerce
Arguments reçus : $ARGUMENTS
Je vais maintenant :