ai-developer-skill-os 1.6.0 → 1.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -3
- package/package.json +1 -1
- package/skills/qk-api-integration/SKILL.md +243 -1
- package/skills/qk-help/SKILL.md +67 -0
- package/skills.json +24 -0
package/README.md
CHANGED
|
@@ -133,10 +133,15 @@ Trước khi đổi một cấu trúc lớn, hãy bắt AI dò mìn:
|
|
|
133
133
|
|
|
134
134
|
---
|
|
135
135
|
|
|
136
|
-
## 💎 Danh sách
|
|
136
|
+
## 💎 **Danh sách đầy đủ các Kỹ năng đang có trong Skill OS:**
|
|
137
|
+
*(Bạn có thể gọi trực tiếp trên Terminal hoặc Chat)*
|
|
137
138
|
|
|
138
|
-
|
|
139
|
-
|
|
139
|
+
> 💡 **Mẹo (Pro-Tip):** Bất cứ khi nào bạn quên mất danh sách kỹ năng hoặc cách dùng, chỉ cần gõ lệnh `./qk-help` (hoặc `@qk-help`), hệ thống sẽ xuất ra toàn bộ cẩm nang sử dụng và bí kíp kết hợp Kỹ năng (Skill Chaining) ngay lập tức!
|
|
140
|
+
|
|
141
|
+
| Kỹ năng (Skill) | Nhiệm vụ chuyên môn |
|
|
142
|
+
|-----------------|---------------------|
|
|
143
|
+
| 🧠 **`qk-help`** | **[MỚI] Sách hướng dẫn tra cứu nhanh danh sách Skill và Bí kíp kết hợp** |
|
|
144
|
+
| 🧑💻 **`qk-ui-builder`** | Xây dựng UI, vẽ Màn hình, chia Layout, tạo Modal cực đẹp |
|
|
140
145
|
| 🏗️ **Engineering** | `qk-project-audit`, `qk-agent-orchestrator` | Kiểm toán dự án, lập kế hoạch, quản lý Git, Refactor code. |
|
|
141
146
|
| 🎨 **Frontend** | `qk-ui-builder`, `qk-frontend-performance` | Dựng UI, tối ưu tốc độ, test component, quản lý State. |
|
|
142
147
|
| ⚙️ **Backend** | `qk-database-engineer`, `qk-auth-security` | Thiết kế DB Schema, bảo mật JWT/OAuth, cấu hình CI/CD. |
|
package/package.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: qk-api-integration
|
|
2
|
+
name: qk-api-integration
|
|
3
3
|
description: >-
|
|
4
4
|
Chuyển đổi tài liệu API (curl, swagger...) thành code tích hợp frontend chuẩn xác, có type an toàn và xử lý lỗi.
|
|
5
5
|
version: 2.0.0
|
|
@@ -37,6 +37,248 @@ Activate this skill when the user provides any of:
|
|
|
37
37
|
- ✅ Generate typed service/client, hooks/queries, and TypeScript types
|
|
38
38
|
- ✅ Follow and extend existing architecture — never duplicate it
|
|
39
39
|
- ✅ Handle special cases: file upload, file download, pagination, auth, WebSocket
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Non-goals
|
|
44
|
+
|
|
45
|
+
- ❌ Do NOT create a new HTTP client if one already exists
|
|
46
|
+
- ❌ Do NOT introduce a new state system if one is already in use
|
|
47
|
+
- ❌ Do NOT hardcode URLs, tokens, or secrets
|
|
48
|
+
- ❌ Do NOT use `any` when types can be inferred
|
|
49
|
+
- ❌ Do NOT overwrite existing files without explicit user approval
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Severity Levels
|
|
54
|
+
|
|
55
|
+
| Level | Meaning |
|
|
56
|
+
|-------|---------|
|
|
57
|
+
| P0 | Conflict with existing endpoint or type — must resolve before generating |
|
|
58
|
+
| P1 | Missing critical info (auth, response schema) — ask before proceeding |
|
|
59
|
+
| P2 | Naming or structure inconsistency — warn and apply best guess |
|
|
60
|
+
| P3 | Missing optional fields — document assumption and proceed |
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Workflow
|
|
65
|
+
|
|
66
|
+
### Phase 1 — Input Validation
|
|
67
|
+
|
|
68
|
+
Before parsing, verify:
|
|
69
|
+
- URL is valid and method is correct (GET/POST/PUT/PATCH/DELETE)
|
|
70
|
+
- Auth format is identifiable (Bearer, API Key, OAuth2, Basic, Cookie)
|
|
71
|
+
- Request info is present (path params, query params, body)
|
|
72
|
+
- Response structure is clear (JSON, binary, stream, paginated)
|
|
73
|
+
- Error cases are documented
|
|
74
|
+
|
|
75
|
+
If critical info is missing → **stop and ask**. Do not guess.
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"validation": {
|
|
80
|
+
"status": "VALID | INVALID | INCOMPLETE",
|
|
81
|
+
"confidence": 0.95,
|
|
82
|
+
"errors": [],
|
|
83
|
+
"warnings": [],
|
|
84
|
+
"input_type": "curl | openapi | postman | docs | code"
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
### Phase 2 — API Contract Extraction
|
|
92
|
+
|
|
93
|
+
Extract the full contract:
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
metadata:
|
|
97
|
+
name, domain, endpoint, method, version, description
|
|
98
|
+
|
|
99
|
+
request:
|
|
100
|
+
pathParams: { name, type, required }
|
|
101
|
+
queryParams: { name, type, required, default }
|
|
102
|
+
headers: { name, value, required }
|
|
103
|
+
body: { contentType, schema { field, type, required, nullable } }
|
|
104
|
+
auth: { type, location, name }
|
|
105
|
+
|
|
106
|
+
response:
|
|
107
|
+
success: { statusCode, contentType, schema, pagination? }
|
|
108
|
+
errors: [ { statusCode, message, businessCode? } ]
|
|
109
|
+
|
|
110
|
+
special:
|
|
111
|
+
rateLimit, timeout, retryable, streaming
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Map each field: `type`, `required`, `nullable`, `enum`, `example`.
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
### Phase 3 — Project Profile Detection
|
|
119
|
+
|
|
120
|
+
1. Check for `.api-config.json` at project root → use if present
|
|
121
|
+
2. Otherwise infer from:
|
|
122
|
+
- Framework: `package.json`, config files, imports
|
|
123
|
+
- HTTP client: existing axios instance, fetch wrapper, custom client
|
|
124
|
+
- State management: React Query, Redux, Zustand, Pinia, Apollo, Vuex
|
|
125
|
+
- Type system: `tsconfig.json`, JSDoc, plain JS
|
|
126
|
+
- Folder conventions: `services/`, `hooks/`, `api/`, `types/`, `adapters/`
|
|
127
|
+
- Naming: camelCase, PascalCase, snake_case, file patterns
|
|
128
|
+
3. Read 1-2 existing API files to capture exact patterns for imports, typing, error handling, naming
|
|
129
|
+
|
|
130
|
+
If project context is ambiguous → use conservative defaults and document all assumptions.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
### Phase 4 — Conflict Detection
|
|
135
|
+
|
|
136
|
+
Before generating code, check for:
|
|
137
|
+
|
|
138
|
+
| Conflict | Action |
|
|
139
|
+
|----------|--------|
|
|
140
|
+
| `ENDPOINT_DUPLICATE` — endpoint already exists | Reuse if same, warn if different |
|
|
141
|
+
| `FUNCTION_DUPLICATE` — function name conflicts | Warn, propose new name |
|
|
142
|
+
| `TYPE_DUPLICATE` — type already defined | Extend or reuse existing |
|
|
143
|
+
| `LOGIC_OVERLAP` — logic exists in another service | Consolidate, don't duplicate |
|
|
144
|
+
| `IMPORT_CONFLICT` — import path conflicts | Resolve before generating |
|
|
145
|
+
|
|
146
|
+
**P0 conflict → stop, report, wait for user decision before proceeding.**
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
### Phase 5 — Code Generation
|
|
151
|
+
|
|
152
|
+
Generate the minimum necessary set for the task:
|
|
153
|
+
|
|
154
|
+
#### TypeScript Types
|
|
155
|
+
```typescript
|
|
156
|
+
// Request types
|
|
157
|
+
export interface CreateUserRequest {
|
|
158
|
+
name: string;
|
|
159
|
+
email: string;
|
|
160
|
+
role?: UserRole;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// Response types
|
|
164
|
+
export interface CreateUserResponse {
|
|
165
|
+
id: string;
|
|
166
|
+
name: string;
|
|
167
|
+
email: string;
|
|
168
|
+
createdAt: string;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// Error types
|
|
172
|
+
export interface ApiError {
|
|
173
|
+
code: string;
|
|
174
|
+
message: string;
|
|
175
|
+
details?: Record<string, unknown>;
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
#### Service / API Layer
|
|
180
|
+
```typescript
|
|
181
|
+
// Thin layer: HTTP + mapping only. No UI, no business logic.
|
|
182
|
+
export const createUser = async (
|
|
183
|
+
data: CreateUserRequest
|
|
184
|
+
): Promise<CreateUserResponse> => {
|
|
185
|
+
const response = await apiClient.post<CreateUserResponse>('/users', data);
|
|
186
|
+
return response.data;
|
|
187
|
+
};
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
#### Hook / Query (if project uses React Query)
|
|
191
|
+
```typescript
|
|
192
|
+
export const useCreateUser = () => {
|
|
193
|
+
return useMutation<CreateUserResponse, ApiError, CreateUserRequest>({
|
|
194
|
+
mutationFn: createUser,
|
|
195
|
+
onSuccess: () => {
|
|
196
|
+
queryClient.invalidateQueries({ queryKey: ['users'] });
|
|
197
|
+
},
|
|
198
|
+
});
|
|
199
|
+
};
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
**If project uses Redux** → follow existing slice/thunk pattern.
|
|
203
|
+
**If project uses Zustand** → follow existing store pattern.
|
|
204
|
+
**If project uses Pinia/Vuex** → follow existing composable/action pattern.
|
|
205
|
+
|
|
206
|
+
Do NOT mix patterns.
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
### Phase 6 — Special Case Handling
|
|
211
|
+
|
|
212
|
+
#### File Upload (`multipart/form-data`)
|
|
213
|
+
```typescript
|
|
214
|
+
// Always use FormData — never send File object in JSON
|
|
215
|
+
const formData = new FormData();
|
|
216
|
+
formData.append('file', file);
|
|
217
|
+
formData.append('name', name);
|
|
218
|
+
await apiClient.post('/upload', formData, {
|
|
219
|
+
headers: { 'Content-Type': 'multipart/form-data' },
|
|
220
|
+
});
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
#### File Download (binary response)
|
|
224
|
+
```typescript
|
|
225
|
+
const response = await apiClient.get('/export', { responseType: 'blob' });
|
|
226
|
+
const url = URL.createObjectURL(response.data);
|
|
227
|
+
const a = document.createElement('a');
|
|
228
|
+
a.href = url;
|
|
229
|
+
a.download = filename;
|
|
230
|
+
a.click();
|
|
231
|
+
URL.revokeObjectURL(url);
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
#### Pagination
|
|
235
|
+
```typescript
|
|
236
|
+
interface PaginatedResponse<T> {
|
|
237
|
+
items: T[];
|
|
238
|
+
total: number;
|
|
239
|
+
page: number;
|
|
240
|
+
limit: number;
|
|
241
|
+
}
|
|
242
|
+
// Implement consistently with existing project pagination pattern
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
#### Authentication
|
|
246
|
+
- Follow existing auth mechanism (interceptor, header injection, cookie)
|
|
247
|
+
- Never hardcode tokens or credentials
|
|
248
|
+
- Refresh token logic belongs in the existing interceptor
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
### Phase 7 — Quality Validation
|
|
253
|
+
|
|
254
|
+
Before marking as ready:
|
|
255
|
+
|
|
256
|
+
- [ ] TypeScript strict — compiles clean, no `any` without justification
|
|
257
|
+
- [ ] All functions/params have explicit types and return types
|
|
258
|
+
- [ ] No unused imports, no debug code
|
|
259
|
+
- [ ] Error handling complete (try/catch, `.catch`, fallback)
|
|
260
|
+
- [ ] No hardcoded URLs, tokens, or secrets — use env vars
|
|
261
|
+
- [ ] Naming matches project conventions
|
|
262
|
+
- [ ] Reuses existing HTTP client, interceptors, and query client
|
|
263
|
+
- [ ] JSDoc added for public API if project convention requires it
|
|
264
|
+
- [ ] React: dependency arrays correct, cleanup present, no race conditions
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
### Phase 8 — End-to-End UI Integration (Optional / On-Demand)
|
|
269
|
+
|
|
270
|
+
If the user explicitly requests to integrate the API directly into the UI (End-to-End):
|
|
271
|
+
1. **Find Target Component:** Identify the UI component where the API should be called.
|
|
272
|
+
2. **Wire State:** Inject the generated Hook/Query/Service into the component.
|
|
273
|
+
3. **Handle States:** Implement Loading (spinners, skeletons), Error (toast, alert), and Success (redirect, form reset, table refetch) states in the UI.
|
|
274
|
+
4. **Data Binding:** Bind the API response data to the UI elements (Table rows, Dropdowns, etc.) and bind UI inputs to the API request payload.
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Decision Tree
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
Is required info complete?
|
|
40
282
|
├── No → Ask for missing info (auth, response schema, base URL)
|
|
41
283
|
└── Yes → Check for conflicts
|
|
42
284
|
├── P0 conflict → Stop, report, wait for user decision
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: qk-help
|
|
3
|
+
description: >-
|
|
4
|
+
Tra cứu danh sách toàn bộ kỹ năng (skills) hiện có và đọc các mẹo (pro-tips) kết hợp kỹ năng để tăng tốc độ code.
|
|
5
|
+
version: 1.0.0
|
|
6
|
+
category: engineering
|
|
7
|
+
tags: [help, list, tips, guide, manual]
|
|
8
|
+
platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# 📚 Cẩm nang AI Developer Skill OS
|
|
12
|
+
|
|
13
|
+
> **Nhiệm vụ của bạn (AI):** Khi người dùng gọi lệnh `./qk-help`, hãy xuất ra màn hình (bằng tiếng Việt) danh sách các kỹ năng phân theo nhóm và các Mẹo sử dụng (Pro-tips) dưới đây một cách sinh động, dễ đọc (dùng markdown, in đậm, emoji). Không cần phân tích code, chỉ đóng vai trò là "Sách hướng dẫn sử dụng".
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 🎯 1. Danh sách Kỹ năng (Skills Directory)
|
|
18
|
+
|
|
19
|
+
Dưới đây là các kỹ năng chính bạn có thể gọi bằng cách gõ `./qk-[tên-kỹ-năng]`:
|
|
20
|
+
|
|
21
|
+
### 🎨 Frontend (Giao diện)
|
|
22
|
+
- **`qk-ui-builder`**: Xây dựng UI, Layout, Component, Modal phức tạp.
|
|
23
|
+
- **`qk-table-crud-generator`**: Chuyên vẽ bảng danh sách (Table), phân trang, lọc và form Thêm/Sửa/Xóa.
|
|
24
|
+
- **`qk-form-builder`**: Chuyên làm Form nhập liệu, validate (Zod/Yup).
|
|
25
|
+
- **`qk-component-generator`**: Tạo Component độc lập, tái sử dụng (Button, Input, Card).
|
|
26
|
+
- **`qk-state-management`**: Xử lý Redux, Zustand, React Query.
|
|
27
|
+
- **`qk-frontend-debug`**: Bắt bệnh vỡ layout, infinite re-render, lỗi Hydration.
|
|
28
|
+
- **`qk-frontend-performance`**: Tối ưu tốc độ, chống re-render thừa.
|
|
29
|
+
- **`qk-frontend-architecture`**: Tư vấn kiến trúc thư mục Frontend.
|
|
30
|
+
- **`qk-frontend-testing`**: Viết Unit Test / E2E Test cho Frontend.
|
|
31
|
+
- **`qk-accessibility-audit`**: Sửa lỗi a11y, hỗ trợ Screen reader.
|
|
32
|
+
|
|
33
|
+
### ⚙️ Engineering & Integration (Tích hợp)
|
|
34
|
+
- **`qk-api-integration`**: [Cực mạnh] Bóc tách tài liệu API (Curl, Postman) -> Gen Type, Service, Hook -> (Tùy chọn) Ốp thẳng vào UI.
|
|
35
|
+
- **`qk-refactor`**: Tối ưu, dọn dẹp mã nguồn sạch sẽ.
|
|
36
|
+
- **`qk-bug-fix`**: Chẩn đoán lỗi sâu và sửa an toàn.
|
|
37
|
+
- **`qk-project-audit`**: Quét toàn bộ dự án tìm nợ kỹ thuật.
|
|
38
|
+
- **`qk-git-engineer`**: Viết Commit / PR chuẩn Conventional.
|
|
39
|
+
- **`qk-migration`**: Nâng cấp version framework / thư viện.
|
|
40
|
+
- **`qk-agent-orchestrator`**: Kiến trúc sư, lên plan phân rã task lớn.
|
|
41
|
+
- **`qk-context-manager`**: Tóm tắt kiến trúc dự án.
|
|
42
|
+
|
|
43
|
+
### 🗄️ Backend (Máy chủ)
|
|
44
|
+
- **`qk-database-engineer`**: Thiết kế Schema, ORM (Prisma/Drizzle), Migration.
|
|
45
|
+
- **`qk-backend-architecture`**: Setup kiến trúc Backend (Node/Nest/Python).
|
|
46
|
+
- **`qk-auth-security`**: Phân quyền RBAC, JWT, OAuth.
|
|
47
|
+
- **`qk-deployment`**: Viết Dockerfile, CI/CD Pipeline.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 💡 2. Mẹo sử dụng Nâng cao (Pro-Tips)
|
|
52
|
+
|
|
53
|
+
### Mẹo 1: Kết hợp Kỹ năng (Skill Chaining) 🔗
|
|
54
|
+
Đừng bắt AI làm từ A-Z bằng 1 câu prompt. Hãy gọi liên hoàn:
|
|
55
|
+
> *"Hãy dùng `./qk-api-integration` để bóc tách API này thành hook React Query. Sau đó dùng `./qk-table-crud-generator` vẽ cái Bảng hiển thị danh sách tích hợp hook đó."*
|
|
56
|
+
|
|
57
|
+
### Mẹo 2: Chế độ "Một phát ăn ngay" (End-to-End) 🚀
|
|
58
|
+
Nếu bạn đã có sẵn 1 màn hình UI (chỉ thiếu data), hãy ép `qk-api-integration` làm End-to-End:
|
|
59
|
+
> *"./qk-api-integration Dưới đây là API Get Profile. Hãy khai báo Type, viết Hook và TÍCH HỢP THẲNG LUÔN vào file \`Profile.tsx\` đang mở."*
|
|
60
|
+
|
|
61
|
+
### Mẹo 3: Truyền tham số ép buộc (Arguments) 🎯
|
|
62
|
+
Bạn có thể ép AI dùng công nghệ bạn muốn bằng cách thêm \`--tham_số\`:
|
|
63
|
+
> *"./qk-ui-builder --fw=react --css=tailwind Hãy vẽ màn hình Đăng nhập."*
|
|
64
|
+
|
|
65
|
+
### Mẹo 4: Nhờ "Kiến trúc sư" phân việc 🧠
|
|
66
|
+
Nếu bạn có một tính năng quá lớn (ví dụ: Làm tính năng Giỏ Hàng), đừng tự chia việc, hãy gọi:
|
|
67
|
+
> *"./qk-agent-orchestrator Tôi muốn làm tính năng Giỏ hàng. Hãy phân tích và lên kế hoạch gọi các skill \`qk-\` nào cho phù hợp."*
|
package/skills.json
CHANGED
|
@@ -6,6 +6,30 @@
|
|
|
6
6
|
"author": "Quang Khánh",
|
|
7
7
|
"homepage": "https://github.com/phamquangkhanh2999/ai-developer-skill-os.git",
|
|
8
8
|
"skills": [
|
|
9
|
+
{
|
|
10
|
+
"name": "qk-help",
|
|
11
|
+
"path": "skills/qk-help/SKILL.md",
|
|
12
|
+
"version": "1.0.0",
|
|
13
|
+
"category": "engineering",
|
|
14
|
+
"priority": "P0",
|
|
15
|
+
"trigger": [
|
|
16
|
+
"help",
|
|
17
|
+
"list skills",
|
|
18
|
+
"show tips",
|
|
19
|
+
"danh sách skill"
|
|
20
|
+
],
|
|
21
|
+
"dependencies": [],
|
|
22
|
+
"conflicts": [],
|
|
23
|
+
"platforms": [
|
|
24
|
+
"antigravity",
|
|
25
|
+
"claude-code",
|
|
26
|
+
"kilo-code",
|
|
27
|
+
"cursor",
|
|
28
|
+
"windsurf"
|
|
29
|
+
],
|
|
30
|
+
"status": "planned",
|
|
31
|
+
"description": "Tra cứu danh sách toàn bộ kỹ năng (skills) hiện có và đọc các mẹo kết hợp để code hiệu quả."
|
|
32
|
+
},
|
|
9
33
|
{
|
|
10
34
|
"name": "qk-agent-orchestrator",
|
|
11
35
|
"path": "skills/qk-agent-orchestrator/SKILL.md",
|