api-design

Name: api-design
Author: tranhieutt

69stars41forks

How to install api-design?

tranhieutt/software_development_department/api-design

$npx -y skills add tranhieutt/software_development_department --skill api-design

Installs into the current project.

Summary

Defines REST and GraphQL API contracts including endpoints, request/response schemas, auth flows, and versioning strategy. Use when designing a new API, reviewing an API spec, or when the user mentions API design, OpenAPI, or endpoint contracts.

Files · 1

View on GitHub

SKILL.md

1	When this skill is invoked:
2
3	1. Read the target API spec or route files in full.
4
5	For API design in an existing domain, SHOULD also inspect
6	`docs/technical/API.md`, related `design/specs/*`, related
7	`design/contracts/*` if present, and recent relevant ledger entries via
8	`/trace-history`. This is advisory unless the change is an ADR,
9	coordination-rule change, high-risk retry, or protocol removal.
10
11	2. Identify the API type (REST, GraphQL, WebSocket) and apply appropriate standards.
12
13	3. Evaluate REST design quality (if REST):
14	- [ ] Resources use nouns, not verbs (`/users`, not `/getUsers`)
15	- [ ] Correct HTTP methods (GET=read, POST=create, PUT/PATCH=update, DELETE=remove)
16	- [ ] Consistent plural resource naming (`/users`, `/orders`)
17	- [ ] Nested resources have max 2-3 levels of depth
18	- [ ] Query parameters used for filtering, sorting, pagination (not in path)
19
20	4. Evaluate request/response schemas:
21	- [ ] All inputs are validated and typed
22	- [ ] Responses are consistent in structure (envelope format if used)
23	- [ ] Pagination is consistent (cursor or page-based, not mixed)
24	- [ ] Timestamps in ISO 8601 (UTC)
25	- [ ] Money values in smallest currency unit (cents), not floats
26
27	5. Evaluate authentication & authorization:
28	- [ ] Every endpoint has explicit auth requirement documented
29	- [ ] Authorization is checked server-side, not just on the client
30	- [ ] Sensitive data not leaked in error messages
31
32	6. Evaluate error responses:
33	- [ ] Consistent error format (RFC 7807 Problem Details recommended)
34	- [ ] HTTP status codes used correctly (400 for client errors, 500 for server)
35	- [ ] Error messages are user-safe (no stack traces, SQL errors)
36
37	7. Evaluate versioning & backward compatibility:
38	- [ ] Breaking changes require a version bump
39	- [ ] Deprecation policy documented
40	- [ ] Clients can negotiate API version
41
42	8. Output the review:
43
44	```
45	## API Design Review: [API/Endpoint Name]
46
47	### REST Design: [CLEAN / ISSUES FOUND]
48	[List specific issues with examples]
49
50	### Schema Quality: [CLEAN / ISSUES FOUND]
51	[List schema inconsistencies or problems]
52
53	### Auth & Security: [SECURE / ISSUES FOUND]
54	[List authentication and authorization issues]
55
56	### Error Handling: [CONSISTENT / ISSUES FOUND]
57	[List error response problems]
58
59	### Versioning: [HANDLED / UNADDRESSED]
60	[Notes on breaking change risk]
61
62	### Positive Observations
63	[What is well-designed]
64
65	### Required Changes
66	[Must-fix items before shipping]
67
68	### Suggestions
69	[Nice-to-have improvements]
70
71	### Verdict: [APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED]
72	```
73
74	## Protocol
75
76	- Question: Auto-starts from argument (path to API spec or route files); no clarification needed
77	- Options: Skip — single review path
78	- Decision: Skip — verdict is advisory
79	- Draft: Full review report shown in conversation only
80	- Approval: Skip — read-only; no files written
81
82	## Output
83
84	Deliver exactly:
85
86	- Endpoint compliance score (X/Y checks passing across naming, methods, validation, errors)
87	- Security issues with severity — CRITICAL / HIGH / MEDIUM (or "None")
88	- Required changes — must fix before shipping (or "None")
89	- Verdict: `APPROVED` / `APPROVED WITH SUGGESTIONS` / `CHANGES REQUIRED`

People who liked this also viewed

6 picks

Type

api-design

69stars41forks

View on GitHub

How to install api-design?

tranhieutt/software_development_department/api-design

$npx -y skills add tranhieutt/software_development_department --skill api-design

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	When this skill is invoked:
2
3	1. Read the target API spec or route files in full.
4
5	For API design in an existing domain, SHOULD also inspect
6	`docs/technical/API.md`, related `design/specs/*`, related
7	`design/contracts/*` if present, and recent relevant ledger entries via
8	`/trace-history`. This is advisory unless the change is an ADR,
9	coordination-rule change, high-risk retry, or protocol removal.
10
11	2. Identify the API type (REST, GraphQL, WebSocket) and apply appropriate standards.
12
13	3. Evaluate REST design quality (if REST):
14	- [ ] Resources use nouns, not verbs (`/users`, not `/getUsers`)
15	- [ ] Correct HTTP methods (GET=read, POST=create, PUT/PATCH=update, DELETE=remove)
16	- [ ] Consistent plural resource naming (`/users`, `/orders`)
17	- [ ] Nested resources have max 2-3 levels of depth
18	- [ ] Query parameters used for filtering, sorting, pagination (not in path)
19
20	4. Evaluate request/response schemas:
21	- [ ] All inputs are validated and typed
22	- [ ] Responses are consistent in structure (envelope format if used)
23	- [ ] Pagination is consistent (cursor or page-based, not mixed)
24	- [ ] Timestamps in ISO 8601 (UTC)
25	- [ ] Money values in smallest currency unit (cents), not floats
26
27	5. Evaluate authentication & authorization:
28	- [ ] Every endpoint has explicit auth requirement documented
29	- [ ] Authorization is checked server-side, not just on the client
30	- [ ] Sensitive data not leaked in error messages
31
32	6. Evaluate error responses:
33	- [ ] Consistent error format (RFC 7807 Problem Details recommended)
34	- [ ] HTTP status codes used correctly (400 for client errors, 500 for server)
35	- [ ] Error messages are user-safe (no stack traces, SQL errors)
36
37	7. Evaluate versioning & backward compatibility:
38	- [ ] Breaking changes require a version bump
39	- [ ] Deprecation policy documented
40	- [ ] Clients can negotiate API version
41
42	8. Output the review:
43
44	```
45	## API Design Review: [API/Endpoint Name]
46
47	### REST Design: [CLEAN / ISSUES FOUND]
48	[List specific issues with examples]
49
50	### Schema Quality: [CLEAN / ISSUES FOUND]
51	[List schema inconsistencies or problems]
52
53	### Auth & Security: [SECURE / ISSUES FOUND]
54	[List authentication and authorization issues]
55
56	### Error Handling: [CONSISTENT / ISSUES FOUND]
57	[List error response problems]
58
59	### Versioning: [HANDLED / UNADDRESSED]
60	[Notes on breaking change risk]
61
62	### Positive Observations
63	[What is well-designed]
64
65	### Required Changes
66	[Must-fix items before shipping]
67
68	### Suggestions
69	[Nice-to-have improvements]
70
71	### Verdict: [APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED]
72	```
73
74	## Protocol
75
76	- Question: Auto-starts from argument (path to API spec or route files); no clarification needed
77	- Options: Skip — single review path
78	- Decision: Skip — verdict is advisory
79	- Draft: Full review report shown in conversation only
80	- Approval: Skip — read-only; no files written
81
82	## Output
83
84	Deliver exactly:
85
86	- Endpoint compliance score (X/Y checks passing across naming, methods, validation, errors)
87	- Security issues with severity — CRITICAL / HIGH / MEDIUM (or "None")
88	- Required changes — must fix before shipping (or "None")
89	- Verdict: `APPROVED` / `APPROVED WITH SUGGESTIONS` / `CHANGES REQUIRED`

People who liked this also viewed

6 picks

Type