Skip to content

Commit 9ac8258

Browse files
ciro-macielciro-maciel
committed
feat: introduce new skills for database design, API patterns, architecture, and various development practices.
1 parent 68b6e8b commit 9ac8258

File tree

35 files changed

+3229
-24
lines changed

35 files changed

+3229
-24
lines changed

‎.agent/skills/api-patterns/SKILL.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
name: api-patterns
3+
description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
4+
allowed-tools: Read, Write, Edit, Glob, Grep
5+
---
6+
7+
# API Patterns
8+
9+
> API design principles and decision-making for 2025.
10+
> **Learn to THINK, not copy fixed patterns.**
11+
12+
## 🎯 Selective Reading Rule
13+
14+
**Read ONLY files relevant to the request!** Check the content map, find what you need.
15+
16+
---
17+
18+
## 📑 Content Map
19+
20+
| File | Description | When to Read |
21+
|------|-------------|--------------|
22+
| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
23+
| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
24+
| `response.md` | Envelope pattern, error format, pagination | Response structure |
25+
| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
26+
| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
27+
| `versioning.md` | URI/Header/Query versioning | API evolution planning |
28+
| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
29+
| `rate-limiting.md` | Token bucket, sliding window | API protection |
30+
| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
31+
| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
32+
33+
---
34+
35+
## 🔗 Related Skills
36+
37+
| Need | Skill |
38+
|------|-------|
39+
| API implementation | `@[skills/backend-development]` |
40+
| Data structure | `@[skills/database-design]` |
41+
| Security details | `@[skills/security-hardening]` |
42+
43+
---
44+
45+
## ✅ Decision Checklist
46+
47+
Before designing an API:
48+
49+
- [ ] **Asked user about API consumers?**
50+
- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
51+
- [ ] **Defined consistent response format?**
52+
- [ ] **Planned versioning strategy?**
53+
- [ ] **Considered authentication needs?**
54+
- [ ] **Planned rate limiting?**
55+
- [ ] **Documentation approach defined?**
56+
57+
---
58+
59+
## ❌ Anti-Patterns
60+
61+
**DON'T:**
62+
- Default to REST for everything
63+
- Use verbs in REST endpoints (/getUsers)
64+
- Return inconsistent response formats
65+
- Expose internal errors to clients
66+
- Skip rate limiting
67+
68+
**DO:**
69+
- Choose API style based on context
70+
- Ask about client requirements
71+
- Document thoroughly
72+
- Use appropriate status codes
73+
74+
---
75+
76+
## Script
77+
78+
| Script | Purpose | Command |
79+
|--------|---------|---------|
80+
| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
81+

‎.agent/skills/api-patterns/api-style.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# API Style Selection (2025)
2+
3+
> REST vs GraphQL vs tRPC - Hangi durumda hangisi?
4+
5+
## Decision Tree
6+
7+
```
8+
Who are the API consumers?
9+
│
10+
├── Public API / Multiple platforms
11+
│ └── REST + OpenAPI (widest compatibility)
12+
│
13+
├── Complex data needs / Multiple frontends
14+
│ └── GraphQL (flexible queries)
15+
│
16+
├── TypeScript frontend + backend (monorepo)
17+
│ └── tRPC (end-to-end type safety)
18+
│
19+
├── Real-time / Event-driven
20+
│ └── WebSocket + AsyncAPI
21+
│
22+
└── Internal microservices
23+
└── gRPC (performance) or REST (simplicity)
24+
```
25+
26+
## Comparison
27+
28+
| Factor | REST | GraphQL | tRPC |
29+
|--------|------|---------|------|
30+
| **Best for** | Public APIs | Complex apps | TS monorepos |
31+
| **Learning curve** | Low | Medium | Low (if TS) |
32+
| **Over/under fetching** | Common | Solved | Solved |
33+
| **Type safety** | Manual (OpenAPI) | Schema-based | Automatic |
34+
| **Caching** | HTTP native | Complex | Client-based |
35+
36+
## Selection Questions
37+
38+
1. Who are the API consumers?
39+
2. Is the frontend TypeScript?
40+
3. How complex are the data relationships?
41+
4. Is caching critical?
42+
5. Public or internal API?

‎.agent/skills/api-patterns/auth.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Authentication Patterns
2+
3+
> Choose auth pattern based on use case.
4+
5+
## Selection Guide
6+
7+
| Pattern | Best For |
8+
|---------|----------|
9+
| **JWT** | Stateless, microservices |
10+
| **Session** | Traditional web, simple |
11+
| **OAuth 2.0** | Third-party integration |
12+
| **API Keys** | Server-to-server, public APIs |
13+
| **Passkey** | Modern passwordless (2025+) |
14+
15+
## JWT Principles
16+
17+
```
18+
Important:
19+
├── Always verify signature
20+
├── Check expiration
21+
├── Include minimal claims
22+
├── Use short expiry + refresh tokens
23+
└── Never store sensitive data in JWT
24+
```

‎.agent/skills/api-patterns/documentation.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# API Documentation Principles
2+
3+
> Good docs = happy developers = API adoption.
4+
5+
## OpenAPI/Swagger Essentials
6+
7+
```
8+
Include:
9+
├── All endpoints with examples
10+
├── Request/response schemas
11+
├── Authentication requirements
12+
├── Error response formats
13+
└── Rate limiting info
14+
```
15+
16+
## Good Documentation Has
17+
18+
```
19+
Essentials:
20+
├── Quick start / Getting started
21+
├── Authentication guide
22+
├── Complete API reference
23+
├── Error handling guide
24+
├── Code examples (multiple languages)
25+
└── Changelog
26+
```

‎.agent/skills/api-patterns/graphql.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# GraphQL Principles
2+
3+
> Flexible queries for complex, interconnected data.
4+
5+
## When to Use
6+
7+
```
8+
✅ Good fit:
9+
├── Complex, interconnected data
10+
├── Multiple frontend platforms
11+
├── Clients need flexible queries
12+
├── Evolving data requirements
13+
└── Reducing over-fetching matters
14+
15+
❌ Poor fit:
16+
├── Simple CRUD operations
17+
├── File upload heavy
18+
├── HTTP caching important
19+
└── Team unfamiliar with GraphQL
20+
```
21+
22+
## Schema Design Principles
23+
24+
```
25+
Principles:
26+
├── Think in graphs, not endpoints
27+
├── Design for evolvability (no versions)
28+
├── Use connections for pagination
29+
├── Be specific with types (not generic "data")
30+
└── Handle nullability thoughtfully
31+
```
32+
33+
## Security Considerations
34+
35+
```
36+
Protect against:
37+
├── Query depth attacks → Set max depth
38+
├── Query complexity → Calculate cost
39+
├── Batching abuse → Limit batch size
40+
├── Introspection → Disable in production
41+
```

‎.agent/skills/api-patterns/rate-limiting.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Rate Limiting Principles
2+
3+
> Protect your API from abuse and overload.
4+
5+
## Why Rate Limit
6+
7+
```
8+
Protect against:
9+
├── Brute force attacks
10+
├── Resource exhaustion
11+
├── Cost overruns (if pay-per-use)
12+
└── Unfair usage
13+
```
14+
15+
## Strategy Selection
16+
17+
| Type | How | When |
18+
|------|-----|------|
19+
| **Token bucket** | Burst allowed, refills over time | Most APIs |
20+
| **Sliding window** | Smooth distribution | Strict limits |
21+
| **Fixed window** | Simple counters per window | Basic needs |
22+
23+
## Response Headers
24+
25+
```
26+
Include in headers:
27+
├── X-RateLimit-Limit (max requests)
28+
├── X-RateLimit-Remaining (requests left)
29+
├── X-RateLimit-Reset (when limit resets)
30+
└── Return 429 when exceeded
31+
```

‎.agent/skills/api-patterns/response.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Response Format Principles
2+
3+
> Consistency is key - choose a format and stick to it.
4+
5+
## Common Patterns
6+
7+
```
8+
Choose one:
9+
├── Envelope pattern ({ success, data, error })
10+
├── Direct data (just return the resource)
11+
└── HAL/JSON:API (hypermedia)
12+
```
13+
14+
## Error Response
15+
16+
```
17+
Include:
18+
├── Error code (for programmatic handling)
19+
├── User message (for display)
20+
├── Details (for debugging, field-level errors)
21+
├── Request ID (for support)
22+
└── NOT internal details (security!)
23+
```
24+
25+
## Pagination Types
26+
27+
| Type | Best For | Trade-offs |
28+
|------|----------|------------|
29+
| **Offset** | Simple, jumpable | Performance on large datasets |
30+
| **Cursor** | Large datasets | Can't jump to page |
31+
| **Keyset** | Performance critical | Requires sortable key |
32+
33+
### Selection Questions
34+
35+
1. How large is the dataset?
36+
2. Do users need to jump to specific pages?
37+
3. Is data frequently changing?

‎.agent/skills/api-patterns/rest.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# REST Principles
2+
3+
> Resource-based API design - nouns not verbs.
4+
5+
## Resource Naming Rules
6+
7+
```
8+
Principles:
9+
├── Use NOUNS, not verbs (resources, not actions)
10+
├── Use PLURAL forms (/users not /user)
11+
├── Use lowercase with hyphens (/user-profiles)
12+
├── Nest for relationships (/users/123/posts)
13+
└── Keep shallow (max 3 levels deep)
14+
```
15+
16+
## HTTP Method Selection
17+
18+
| Method | Purpose | Idempotent? | Body? |
19+
|--------|---------|-------------|-------|
20+
| **GET** | Read resource(s) | Yes | No |
21+
| **POST** | Create new resource | No | Yes |
22+
| **PUT** | Replace entire resource | Yes | Yes |
23+
| **PATCH** | Partial update | No | Yes |
24+
| **DELETE** | Remove resource | Yes | No |
25+
26+
## Status Code Selection
27+
28+
| Situation | Code | Why |
29+
|-----------|------|-----|
30+
| Success (read) | 200 | Standard success |
31+
| Created | 201 | New resource created |
32+
| No content | 204 | Success, nothing to return |
33+
| Bad request | 400 | Malformed request |
34+
| Unauthorized | 401 | Missing/invalid auth |
35+
| Forbidden | 403 | Valid auth, no permission |
36+
| Not found | 404 | Resource doesn't exist |
37+
| Conflict | 409 | State conflict (duplicate) |
38+
| Validation error | 422 | Valid syntax, invalid data |
39+
| Rate limited | 429 | Too many requests |
40+
| Server error | 500 | Our fault |

0 commit comments

Comments
 (0)