ai-developer-skill-os 1.8.1 → 2.0.0

package/docs/HUONG_DAN_SU_DUNG.md

@@ -1,152 +1,120 @@
-# Hướng Dẫn Sử Dụng — AI Developer Skill OS
-
-**Tác giả:** Quang Khánh  
-**Phiên bản:** v1.0.1  
-
-Chào mừng bạn đến với **AI Developer Skill OS**, bộ khung quản lý kỹ năng (Skill Framework) biến các trợ lý AI (Gemini, Antigravity, Claude Code, Cursor, Windsurf) từ một "cỗ máy sinh code" thành một Senior Software Engineer thực thụ.
-
----
-
-## 1. Cơ chế hoạt động (Tại sao lại cần Skin/Skill này?)
-
-Thông thường, khi bạn yêu cầu AI "Làm cho tôi tính năng X", AI sẽ nhảy ngay vào viết code. Điều này ở các dự án lớn thường dẫn đến: phá vỡ kiến trúc, tạo ra code rác, và không tuân thủ các component dùng chung.
-
-Với hệ điều hành kỹ năng (Skill OS) này:
-1. Bạn đưa ra yêu cầu.
-2. Skill **agent-orchestrator** sẽ tiếp nhận, phân tích và lên kế hoạch (Plan only).
-3. Nó gọi **context-manager** để đọc đúng những file cần thiết (chống tràn ngữ cảnh).
-4. Nó gọi các skill chuyên biệt (`ui-builder`, `api-integration`, `database-engineer`...) để thực thi từng bước.
-5. AI luôn bị ép phải dùng tiếng Anh để viết code/định nghĩa biến, nhưng sẽ dùng tiếng Việt để giao tiếp và báo cáo với bạn.
-
----
-
-## 2. Hướng dẫn cài đặt qua NPM (Khuyên dùng)
-
-Bộ Skin này rất linh hoạt và được phân phối qua NPM để bạn có thể cài vào bất kỳ dự án nào cực kỳ nhanh chóng.
-
-Mở terminal tại gốc dự án của bạn và chạy lệnh cài đặt tương ứng với công cụ AI bạn đang dùng:
-
-### Dành cho Gemini IDE / Antigravity
-### 1. Cài đặt (Installation)
-> Khuyên dùng cách cài đặt qua NPM để luôn nhận được cấu trúc mới nhất và tận dụng tính năng Auto-Config.
-
-Mở terminal tại thư mục gốc dự án của bạn và chạy lệnh sau:
-```bash
-npx ai-developer-skill-os init
-```
-Quá trình cài đặt sẽ hỏi bạn 2 câu quan trọng:
-
-**Câu 1: Bạn đang dùng IDE nào?**
-Hệ thống sẽ tự động tạo file cấu hình tương ứng (ví dụ `.cursorrules`, `.windsurfrules`, `.clinerules`) và bơm sẵn System Prompt vào để AI tự nhận diện các skill.
-
-**Câu 2: Phạm vi cài đặt?**
-- **(1) Local:** Cài vào thư mục ẩn `.qk-ai-skill-os/` (hoặc `.agents/` cho Gemini) ngay trong dự án. Rất phù hợp nếu dự án có nhiều người làm chung, bạn có thể commit thư mục này lên Git để ai cũng có skill.
-- **(2) Global:** Cài thẳng vào ổ đĩa máy tính (Home Directory). Nếu bạn code một mình, hãy chọn tuỳ chọn này! Nó giúp bạn tiết kiệm dung lượng, và chỉ cần cài 1 lần là BẤT KỲ DỰ ÁN NÀO bạn mở lên, AI cũng tự động có đủ 23 kỹ năng (Đặc biệt siêu mượt với Antigravity/Gemini).
-
-> 💡 **Tính năng Tự động Dọn dẹp (Auto-Cleanup):** Mỗi khi cài đặt lại, hệ thống sẽ tự động quét và xóa sạch các kỹ năng phiên bản cũ để tối ưu dung lượng và tránh xung đột cho máy tính của bạn. Mọi thứ hoàn toàn tự động!
-
-### Cho Gemini IDE / Antigravity
-**Không cần cấu hình gì thêm!** Gemini/Antigravity sẽ tự động nhận diện các file trong `.agents/skills/` và sẵn sàng làm việc ngay.
-
-### Cho Cursor / Windsurf (AI Code Editors)
-Tạo file `.cursorrules` (nếu dùng Cursor) hoặc `.windsurfrules` (nếu dùng Windsurf) ở gốc dự án và dán đoạn sau vào:
-```md
-# AI Developer Skill OS by Quang Khánh
-
-When answering or generating code, you MUST act as an expert engineer using the skills defined in `./.qk-ai-skill-os/skills.json`.
-Bất cứ khi nào người dùng gõ lệnh `./qk [tên-skill]`, bạn BẮT BUỘC phải đọc file `SKILL.md` tương ứng trong thư mục `./.qk-ai-skill-os/skills/` trước khi thực hiện.
-Speak to me in Vietnamese, but write all code in English.
-```
-
-### Cho Claude Code / Kilo Code (CLI Agents)
-#### Cách 1: Cài đặt Native (Khuyên dùng cho Kilo Code)
-Chạy `npx ai-developer-skill-os init` và chọn **(6) Kilo Code**.
-Hệ thống sẽ tự động:
-- Copy toàn bộ skills vào `.kilo/skills/` (Local) hoặc `~/.kilo/skills/` (Global)
-- Cấu hình `kilo.json` hoặc `~/.config/kilo/kilo.json` để Kilo nhận diện
-- Tạo file `CLAUDE.md` như hướng dẫn bổ sung
-
-Sau đó mở Kilo Code, dùng `<leader>t` hoặc `/themes` để kiểm tra skills đã được cài.
-
-#### Cách 2: Thủ công
-Tạo file `CLAUDE.md` (hoặc `KILO.md`) ở gốc dự án và dán đoạn sau vào:
-```md
-# System Instructions
-Bạn đang chạy bằng **AI Developer Skill OS** (Tác giả: Quang Khánh).
-
-Vui lòng tìm đọc danh sách kỹ năng tại file `./.qk-ai-skill-os/skills.json`.
-ĐẶC BIỆT LƯU Ý: Bất cứ khi nào người dùng gõ lệnh bắt đầu bằng `./qk [tên-skill]`, bạn BẮT BUỘC phải gọi và đọc nội dung file `SKILL.md` tương ứng trong thư mục `./.qk-ai-skill-os/skills/` trước khi phân tích hoặc viết code.
-Luôn giao tiếp bằng tiếng Việt nhưng viết code, đặt tên biến, comment trong code bằng tiếng Anh.
-```
-
-### Cho Cline / Roo Code (VS Code Extensions)
-Tạo file `.clinerules` hoặc `.roorules` ở gốc dự án và dán nội dung:
-```md
-Bạn đang chạy bằng **AI Developer Skill OS** (Tác giả: Quang Khánh).
-Vui lòng tìm đọc danh sách kỹ năng tại file `./.qk-ai-skill-os/skills.json`.
-Bất cứ khi nào người dùng gõ lệnh `./qk [tên-skill]`, bạn BẮT BUỘC phải đọc file `SKILL.md` tương ứng trong thư mục `./.qk-ai-skill-os/skills/`.
-Luôn giao tiếp bằng tiếng Việt nhưng viết code bằng tiếng Anh.
-```
-
-### Cho GitHub Copilot
-Tạo file `.github/copilot-instructions.md` và dán đoạn prompt tương tự như trên vào file này để Copilot học được các kỹ năng.
-
----
-
-## 4. Cách kiểm tra cài đặt thành công
-
-Để biết AI của bạn đã thực sự "nhập môn" bộ Skill OS này chưa, hãy mở khung chat AI trong dự án và gõ cú pháp lệnh chuyên nghiệp sau:
-> **`./qk-project-audit`** Hãy cho tôi biết bạn sẽ làm những gì.
-
-✅ **Thành công:** Nếu AI trả lời bằng tiếng Việt, liệt kê đúng các bước khám bệnh (Phase 1, Phase 2, Phase 3...) theo đúng như trong file `SKILL.md` của `qk-project-audit`.  
-❌ **Thất bại:** Nếu AI trả lời chung chung hoặc bảo không biết skill này là gì, bạn cần kiểm tra lại đường dẫn file cấu hình ở bước trên.
-
----
-
-## 5. Cách gọi lệnh Skill chuyên nghiệp (Usage)
-
-AI sẽ tự động nhận diện skill qua ngữ cảnh, nhưng cách chuyên nghiệp và tiết kiệm thời gian gõ prompt nhất là bạn sử dụng cú pháp lệnh độc quyền: **`./qk-[tên-skill]`**
-
-Dưới đây là các câu lệnh (prompt) mẫu cực kỳ hiệu quả mà bạn nên dùng:
-
-### 🎯 Ví dụ 1: Nhờ AI lên kế hoạch (Planning)
-> **`./qk-agent-orchestrator`** Hãy lên kế hoạch làm tính năng Đăng nhập này cho tôi. Nhớ gọi thêm **`./qk-context-manager`** để kiểm tra thư mục hiện tại có những file gì trước nhé.
-
-### 🎯 Ví dụ 2: Fix lỗi cứng đầu (Bug Fix)
-> **`./qk-frontend-debug`** & **`./qk-bug-fix`** Code đang bị crash với lỗi `Hydration error`. Hãy tìm hiểu nguyên nhân gốc rễ và sửa nó giúp tôi.
-
-### 🎯 Ví dụ 3: Review Codebase (Audit)
-> **`./qk-project-audit`** Hãy kiểm tra nhanh cho tôi thư mục `src/components/` xem có bị vấn đề về hiệu năng hay code smell không.
-
-### 🎯 Ví dụ 4: Xây dựng Giao diện Frontend (UI)
-> **`./qk-ui-builder`** & **`./qk-design-system`** Hãy tạo cho tôi một màn hình Danh sách User. Chú ý dùng chuẩn components của thư mục `src/components/ui/` nhé.
-
-### 🎯 Ví dụ 5: Làm việc với API (Backend & Integration)
-> **`./qk-api-integration`** Tích hợp cái swagger login này vào frontend giúp. Nhớ dùng React Query như chuẩn của project.
-
-### 🎯 Ví dụ 6: Database & Backend
-> **`./qk-database-engineer`** Hãy viết cho tôi schema Prisma cho bảng Product và User có quan hệ 1-N. Làm theo đúng chuẩn kiến trúc trong skill.
-
----
-
-## 6. 💡 Mẹo & Workflow Thực Chiến (Best Practices)
-
-Để khai thác tối đa sức mạnh của 23 kỹ năng, bí quyết là **kết hợp (chaining) nhiều skill** lại với nhau trong cùng một luồng công việc.
-
-### 🌟 Workflow Bắt đầu một New Chat (Bắt buộc)
-Khi mở một New Chat, AI hoàn toàn chưa biết gì về dự án. Đừng bắt nó code ngay!
-* **Bước 1:** `> Dùng ./qk-context-manager để đọc cấu trúc toàn bộ dự án này.`
-* **Bước 2:** `> Dùng ./qk-agent-orchestrator để phân tích yêu cầu sau đây và lên kế hoạch: [Yêu cầu của bạn]`
-
-### 🌟 Workflow Làm tính năng mới (VD: Tích hợp API)
-Muốn tạo một màn hình hiển thị danh sách từ API trả về? Hãy gõ 1 lượt các lệnh:
-* `> Hãy dùng ./qk-api-integration để tạo file gọi API fetch danh sách Users.`
-* `> Tiếp theo dùng ./qk-state-management để lưu data này vào Zustand/Redux.`
-* `> Cuối cùng dùng ./qk-ui-builder để vẽ màn hình Table hiển thị data đó.`
-
-### 🌟 Workflow Chống "Phá Code" (Safe Refactor)
-Trước khi đổi một cấu trúc lớn, hãy bắt AI dò mìn:
-* `> Hãy chạy ./qk-project-audit để dò xem việc đổi tên biến X có ảnh hưởng đến các component khác không.`
-* `> OK, giờ hãy dùng ./qk-refactor để sửa lại một cách an toàn.`
-
-👉 Chúc bạn tận hưởng cảm giác code như một Tech Lead thực thụ!
+# Hướng Dẫn Sử Dụng — AI Developer Skill OS
+
+**Tác giả:** Quang Khánh  
+**Phiên bản:** v2.0.0 (Master OS Architecture)
+
+Chào mừng bạn đến với **AI Developer Skill OS**, hệ điều hành kỹ năng (Skill Framework) biến các trợ lý AI (Gemini, Antigravity, Claude Code, Cursor, Windsurf) từ một "cỗ máy sinh code" thành một **Senior Software Engineer / Chief Architect** thực thụ với khả năng tự học, tự kiểm toán và tự viết tài liệu.
+
+---
+
+## 1. Cơ chế hoạt động (Tại sao lại cần Skin/Skill này?)
+
+Thông thường, khi bạn yêu cầu AI "Làm cho tôi tính năng X", AI sẽ nhảy ngay vào viết code. Điều này ở các dự án lớn thường dẫn đến: phá vỡ kiến trúc, tạo ra code rác, và không tuân thủ các component dùng chung.
+
+Với hệ điều hành 22 Master Skills này:
+1. Bạn đưa ra yêu cầu thông qua **`qk-orchestrator`**.
+2. Hệ thống sẽ tự động gọi **`qk-context-loader`** để gom đúng file (tránh tràn ngữ cảnh) và **`qk-policy-engine`** để kiểm tra quyền.
+3. Kế tiếp, **`qk-engineering-standard`** sẽ gắn các "luật thép" (rules) của dự án vào ngữ cảnh.
+4. AI kích hoạt kỹ năng thực thi E2E như **`qk-feature-delivery`** để code và test trọn vẹn.
+5. Cuối cùng, **`qk-validation-gate`** chặn lại kiểm tra lỗi, trước khi giao cho **`qk-docs`** và **`qk-documentation-system`** tự động cập nhật tài liệu và bộ nhớ hệ thống.
+
+---
+
+## 2. Hướng dẫn cài đặt qua NPM (Khuyên dùng)
+
+Bộ Skin này rất linh hoạt và được phân phối qua NPM để bạn có thể cài vào bất kỳ dự án nào cực kỳ nhanh chóng.
+
+Mở terminal tại gốc dự án của bạn và chạy lệnh cài đặt tương ứng với công cụ AI bạn đang dùng:
+
+```bash
+npx ai-developer-skill-os init
+```
+
+Quá trình cài đặt sẽ hỏi bạn 2 câu quan trọng:
+
+**Câu 1: Bạn đang dùng IDE nào?**
+Hệ thống sẽ tự động tạo file cấu hình tương ứng (ví dụ `.cursorrules`, `.windsurfrules`, `.clinerules`) và bơm sẵn System Prompt vào để AI tự nhận diện các skill.
+
+**Câu 2: Phạm vi cài đặt?**
+- **(1) Local:** Cài vào thư mục `skills/` (hoặc `.agents/` cho Gemini) ngay trong dự án. Thích hợp cho làm việc nhóm.
+- **(2) Global:** Cài thẳng vào ổ đĩa máy tính (Home Directory). Chỉ cài 1 lần, áp dụng cho mọi dự án.
+
+> 💡 **Tính năng Tự động Dọn dẹp (Auto-Cleanup):** Mỗi khi cài đặt lại, hệ thống sẽ tự động quét và xóa sạch các kỹ năng phiên bản cũ để tối ưu dung lượng và tránh xung đột cho máy tính của bạn. Mọi thứ hoàn toàn tự động!
+
+### Cấu hình thủ công (Dành cho IDE / CLI cụ thể)
+
+#### Cho Gemini IDE / Antigravity
+**Không cần cấu hình gì thêm!** Hệ thống tự nhận diện các file trong `.agents/` hoặc thư mục cấu hình toàn cục.
+
+#### Cho Cursor / Windsurf (AI Code Editors)
+Tạo file `.cursorrules` hoặc `.windsurfrules` ở gốc dự án:
+```md
+# AI Developer Skill OS by Quang Khánh
+
+When answering or generating code, you MUST act as an expert engineer using the skills defined in `./skills.json`.
+Bất cứ khi nào người dùng gõ lệnh `./qk-[tên-skill]`, bạn BẮT BUỘC phải đọc file `SKILL.md` tương ứng trong thư mục `./skills/` trước khi thực hiện.
+Speak to me in Vietnamese, but write all code in English.
+```
+
+#### Cho Claude Code / Kilo Code (CLI Agents)
+Tạo file `CLAUDE.md` (hoặc `KILO.md`) ở gốc dự án và dán đoạn sau vào:
+```md
+# System Instructions
+Bạn đang chạy bằng **AI Developer Skill OS** (Tác giả: Quang Khánh).
+
+Vui lòng tìm đọc danh sách kỹ năng tại file `./skills.json`.
+ĐẶC BIỆT LƯU Ý: Bất cứ khi nào người dùng gõ lệnh bắt đầu bằng `./qk-[tên-skill]`, bạn BẮT BUỘC phải gọi và đọc nội dung file `SKILL.md` tương ứng trong thư mục `./skills/` trước khi phân tích hoặc viết code.
+```
+
+---
+
+## 3. Cách kiểm tra cài đặt thành công
+
+Để biết AI của bạn đã thực sự "nhập môn" bộ AI-OS này chưa, hãy mở khung chat AI trong dự án và gõ cú pháp lệnh:
+> **`./qk-help`** Hãy liệt kê cho tôi các khối kỹ năng của hệ thống.
+
+✅ **Thành công:** Nếu AI trả lời bằng tiếng Việt, liệt kê đúng mô hình 7 Lớp (Foundation, UI, Development, Quality, Evolution, Operation, AI, Knowledge).
+❌ **Thất bại:** Nếu AI trả lời chung chung, bạn cần kiểm tra lại đường dẫn file cấu hình ở bước trên.
+
+---
+
+## 4. Cách gọi lệnh Skill chuyên nghiệp (Usage)
+
+AI sẽ tự động nhận diện skill qua ngữ cảnh, nhưng cách chuyên nghiệp và tiết kiệm thời gian nhất là bạn sử dụng cú pháp: **`./qk-[tên-skill]`**
+
+Dưới đây là các câu lệnh (prompt) mẫu cực kỳ hiệu quả mà bạn nên dùng:
+
+### 🎯 Ví dụ 1: Giao phó tổng thể (Orchestrator)
+> **`./qk-orchestrator`** Tôi muốn thêm tính năng Đăng nhập bằng Google. Hãy lên kế hoạch và gọi các skill cần thiết để thực hiện từ A-Z.
+
+### 🎯 Ví dụ 2: Phát triển Tính năng E2E (Feature Delivery)
+> **`./qk-feature-delivery`** Hãy tạo màn hình Dashboard thống kê doanh thu. Lưu ý cập nhật Database, tạo API và dùng UI Component có sẵn.
+
+### 🎯 Ví dụ 3: Fix lỗi cứng đầu (Bug Resolution)
+> **`./qk-bug-resolution`** Code đang bị crash với lỗi `Hydration error`. Hãy tìm Root Cause, sửa an toàn và đảm bảo viết Regression Test để chống hồi quy.
+
+### 🎯 Ví dụ 4: Xây dựng Giao diện (UI System Builder)
+> **`./qk-ui-system-builder`** Hãy tạo cho tôi một Data Table Component có hỗ trợ phân trang và filter, sử dụng Design Token của dự án. Không viết inline CSS rác.
+
+### 🎯 Ví dụ 5: Audit & Tối ưu (Project Health)
+> **`./qk-project-health`** Hãy kiểm tra nhanh cho tôi thư mục `src/components/` xem có bị Code Smell hoặc vi phạm Architecture không.
+
+---
+
+## 💡 5. Mẹo & Workflow Thực Chiến (Best Practices)
+
+Để khai thác tối đa sức mạnh của 22 kỹ năng, bí quyết là **tin tưởng vào chuỗi Handoff tự động** của hệ thống thay vì phải gọi từng lệnh nhỏ lẻ.
+
+### 🌟 Bắt đầu một tính năng hoàn toàn mới
+Thay vì bảo AI tạo từng file, hãy yêu cầu một lần:
+* `> Hãy dùng ./qk-feature-delivery để tạo chức năng Giỏ hàng (Cart).`
+Hệ thống sẽ tự động đi từ DB -> API -> UI và đẩy sang `qk-validation-gate` để kiểm tra lỗi.
+
+### 🌟 Khi dự án bắt đầu lộn xộn
+* `> Hãy chạy ./qk-project-health để kiểm tra toàn bộ nợ kỹ thuật (Tech Debt). Sau đó hãy dùng ./qk-docs để cập nhật lại cấu trúc thư mục mới nhất vào README.`
+
+### 🌟 Chống "Phá Code" (Safe Refactor)
+Trước khi đổi một cấu trúc lớn, hãy bắt AI dò mìn:
+* `> Hãy dùng ./qk-system-evolution để phân tích tầm ảnh hưởng (Impact Analysis) nếu tôi cập nhật Next.js lên phiên bản 15.`
+
+👉 Chúc bạn tận hưởng cảm giác code như một Chief Architect thực thụ!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-developer-skill-os",
-  "version": "1.8.1",
+  "version": "2.0.0",
   "description": "Multi-agent skill package cho AI coding agents (Claude, Cursor, Windsurf, Antigravity) với 23 skills chuyên nghiệp.",
   "main": "bin/install.js",
   "bin": {

package/skills/{qk-accessibility-audit → _archive_old_skills/qk-accessibility-audit}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-accessibility-audit
+name: qk-accessibility-audit
 description: >-
   Kiểm tra và sửa lỗi khả năng tiếp cận (a11y/WCAG). Đảm bảo hỗ trợ phím, screen reader và semantic HTML.
 version: 1.0.0

package/skills/{qk-agent-orchestrator → _archive_old_skills/qk-agent-orchestrator}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-agent-orchestrator
+name: qk-agent-orchestrator
 description: >-
   Phân tích yêu cầu, lên kế hoạch thực thi chi tiết và điều phối các tác vụ cho đúng skill. Không tự viết code.
 version: 1.0.0

package/skills/{qk-bug-fix → _archive_old_skills/qk-bug-fix}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-bug-fix
+name: qk-bug-fix
 description: >-
   Chẩn đoán và sửa lỗi an toàn. Tái hiện lỗi, tìm nguyên nhân gốc rễ và áp dụng bản sửa lỗi tối thiểu, có kiểm chứng.
 version: 2.0.0

package/skills/{qk-component-generator → _archive_old_skills/qk-component-generator}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-component-generator
+name: qk-component-generator
 description: >-
   Tạo các UI Component độc lập, tái sử dụng được, có type an toàn và tuân thủ chuẩn design system.
 version: 1.0.0

package/skills/{qk-database-engineer → _archive_old_skills/qk-database-engineer}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-database-engineer
+name: qk-database-engineer
 description: >-
   Thiết kế database schema, viết script migration và tối ưu truy vấn cho SQL/NoSQL bằng ORM (Prisma, Drizzle...).
 version: 1.0.0

package/skills/{qk-design-system → _archive_old_skills/qk-design-system}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-design-system
+name: qk-design-system
 description: >-
   Ép buộc sử dụng design system, component library và token hiện có, ngăn chặn việc viết HTML/CSS rác.
 version: 1.0.0

package/skills/{qk-form-builder → _archive_old_skills/qk-form-builder}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-form-builder
+name: qk-form-builder
 description: >-
   Xây dựng Form chuẩn xác với quản lý trạng thái, validate dữ liệu (Zod, Yup) và xử lý hiển thị lỗi.
 version: 1.0.0

package/skills/{qk-frontend-architecture → _archive_old_skills/qk-frontend-architecture}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-frontend-architecture
+name: qk-frontend-architecture
 description: >-
   Phân tích cấu trúc thư mục frontend và quyết định vị trí đặt file chuẩn xác theo kiến trúc hiện tại.
 version: 1.0.0

package/skills/{qk-frontend-debug → _archive_old_skills/qk-frontend-debug}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-frontend-debug
+name: qk-frontend-debug
 description: >-
   Chẩn đoán và sửa các lỗi đặc thù frontend như Hydration error, infinite re-render, stale closure và vỡ CSS.
 version: 1.0.0

package/skills/{qk-frontend-performance → _archive_old_skills/qk-frontend-performance}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-frontend-performance
+name: qk-frontend-performance
 description: >-
   Tối ưu hóa hiệu năng frontend: giảm kích thước bundle, chặn re-render thừa, lazy load và cải thiện Web Vitals.
 version: 1.0.0

package/skills/{qk-git-engineer → _archive_old_skills/qk-git-engineer}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-git-engineer
+name: qk-git-engineer
 description: >-
   Viết commit message chuẩn Conventional Commits, mô tả Pull Request, Changelog và Release Notes chuyên nghiệp.
 version: 1.0.0

package/skills/_archive_old_skills/qk-help/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: qk-help
+description: >-
+  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.
+version: 1.0.0
+category: engineering
+tags: [help, list, tips, guide, manual]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# 📚 Cẩm nang AI Developer Skill OS
+
+> **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".
+
+---
+
+## 🎯 1. Danh sách Kỹ năng (Skills Directory)
+
+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]`:
+
+### 🎨 Frontend (Giao diện)
+- **`qk-ui-builder`**: Xây dựng UI, Layout, Component, Modal phức tạp.
+- **`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.
+- **`qk-form-builder`**: Chuyên làm Form nhập liệu, validate (Zod/Yup).
+- **`qk-component-generator`**: Tạo Component độc lập, tái sử dụng (Button, Input, Card).
+- **`qk-state-management`**: Xử lý Redux, Zustand, React Query.
+- **`qk-frontend-debug`**: Bắt bệnh vỡ layout, infinite re-render, lỗi Hydration.
+- **`qk-frontend-performance`**: Tối ưu tốc độ, chống re-render thừa.
+- **`qk-frontend-architecture`**: Tư vấn kiến trúc thư mục Frontend.
+- **`qk-frontend-testing`**: Viết Unit Test / E2E Test cho Frontend.
+- **`qk-accessibility-audit`**: Sửa lỗi a11y, hỗ trợ Screen reader.
+
+### ⚙️ Engineering & Integration (Tích hợp)
+- **`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.
+- **`qk-refactor`**: Tối ưu, dọn dẹp mã nguồn sạch sẽ.
+- **`qk-bug-fix`**: Chẩn đoán lỗi sâu và sửa an toàn.
+- **`qk-project-audit`**: Quét toàn bộ dự án tìm nợ kỹ thuật.
+- **`qk-git-engineer`**: Viết Commit / PR chuẩn Conventional.
+- **`qk-migration`**: Nâng cấp version framework / thư viện.
+- **`qk-agent-orchestrator`**: Kiến trúc sư, lên plan phân rã task lớn.
+- **`qk-context-manager`**: Tóm tắt kiến trúc dự án.
+
+### 🗄️ Backend (Máy chủ)
+- **`qk-database-engineer`**: Thiết kế Schema, ORM (Prisma/Drizzle), Migration.
+- **`qk-backend-architecture`**: Setup kiến trúc Backend (Node/Nest/Python).
+- **`qk-auth-security`**: Phân quyền RBAC, JWT, OAuth.
+- **`qk-deployment`**: Viết Dockerfile, CI/CD Pipeline.
+
+---
+
+## 💡 2. Mẹo sử dụng Nâng cao (Pro-Tips)
+
+### Mẹo 1: Kết hợp Kỹ năng (Skill Chaining) 🔗
+Đừng bắt AI làm từ A-Z bằng 1 câu prompt. Hãy gọi liên hoàn:
+> *"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 đó."*
+
+### Mẹo 2: Chế độ "Một phát ăn ngay" (End-to-End) 🚀
+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:
+> *"./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ở."*
+
+### Mẹo 3: Truyền tham số ép buộc (Arguments) 🎯
+Bạn có thể ép AI dùng công nghệ bạn muốn bằng cách thêm \`--tham_số\`:
+> *"./qk-ui-builder --fw=react --css=tailwind Hãy vẽ màn hình Đăng nhập."*
+
+### Mẹo 4: Nhờ "Kiến trúc sư" phân việc 🧠
+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:
+> *"./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/{qk-state-management → _archive_old_skills/qk-state-management}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-state-management
+name: qk-state-management
 description: >-
   Xác định và triển khai chiến lược quản lý state phù hợp (Zustand, Redux, React Query, Local State).
 version: 1.0.0

package/skills/{qk-table-crud-generator → _archive_old_skills/qk-table-crud-generator}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: qk-table-crud-generator
+name: qk-table-crud-generator
 description: >-
   Tạo các bảng dữ liệu admin với đầy đủ tính năng phân trang, sắp xếp, lọc và thao tác thêm/sửa/xóa (CRUD).
 version: 1.0.0

package/skills/qk-access-policy/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: qk-access-policy
+purpose: Quản lý chính sách bảo mật, phân quyền RBAC và ranh giới truy cập.
+mode_supported: [enterprise]
+input: [Access rules]
+output: [Access policies]
+workflow: [1. Rà soát Roles -> 2. Kiểm tra Permissions -> 3. Cập nhật rule]
+allowed_tools: [read_file, write_to_file]
+handoff_to: [qk-engineering-standard]
+---
+
+# 🛠️ qk-access-policy - Quy Trình Vận Hành Chuẩn (SOP)
+
+> **Mô tả:** Quản lý chính sách bảo mật, phân quyền RBAC và ranh giới truy cập.
+
+## 🎯 1. Mục Tiêu (Goal)
+- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
+- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
+
+## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
+*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
+1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
+2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
+3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
+4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
+
+## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
+- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
+- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
+
+## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
+- Đích đến: `qk-engineering-standard`
+- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.
+
+## 📚 5. Kiến Thức Chuyên Sâu (Deep Knowledge)
+
+*(Nền tảng kiến thức và quy tắc chi tiết kế thừa từ kỹ sư)*
+
+---
+
+
+
+# Auth & Security Engineer
+
+> **Language rule:**
+> Use English for: code, identifiers, file names, architecture terms, technical decisions.
+> Use the user's language for: explanations, questions, summaries, and feedback.
+> The user may write in any language — detect and match it automatically.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User asks to "add login", "protect this route", or "implement OAuth"
+- Defining user roles and permissions (Admin vs User)
+- Project audit flags security vulnerabilities (P0/P1)
+- Handling sensitive data (passwords, PII, API keys)
+
+---
+
+## Scope
+
+- ✅ **Authentication:** JWT, Session Cookies, OAuth2 (Google, GitHub, etc.), Magic Links.
+- ✅ **Authorization:** Role-Based Access Control (RBAC), Middleware guards.
+- ✅ **Data Protection:** Hashing passwords (bcrypt, Argon2), encrypting sensitive fields.
+- ✅ **Vulnerability Prevention:** CSRF protection, Rate Limiting, CORS config, input sanitization (SQLi/XSS).
+
+---
+
+## Non-goals
+
+- ❌ Do NOT store passwords in plain text. Ever.
+- ❌ Do NOT hardcode secrets or private keys in the code (use `.env`).
+- ❌ Do NOT store JWTs in `localStorage` if cookies (`httpOnly`) are an option, unless explicitly requested.
+
+---
+
+## Workflow
+
+### Phase 1 — Strategy Selection
+
+Determine the auth mechanism:
+1. **Stateless (JWT):** Good for mobile/SPAs, distributed systems.
+2. **Stateful (Sessions):** Good for traditional web apps, easier revocation.
+3. **Third-party (OAuth / Auth0 / NextAuth / Supabase):** Offload auth complexity.
+
+### Phase 2 — Implementation
+
+**For JWT + Cookies (Recommended Web Pattern):**
+1. Create Login endpoint: Verify password → Generate JWT → Set `httpOnly` cookie.
+2. Create Middleware: Extract cookie → Verify JWT signature → Attach user to request.
+3. Create Logout endpoint: Clear the cookie.
+
+**For Authorization:**
+1. Define roles (e.g., `enum Role { ADMIN, USER }`).
+2. Create Role Middleware: Check `req.user.role`.
+
+### Phase 3 — Security Audit
+
+Verify:
+- Passwords are hashed with a salt (e.g., `bcrypt.hash(password, 10)`).
+- Cookies are `httpOnly`, `Secure` (in prod), and `SameSite`.
+- CORS is configured to only allow trusted origins.
+
+---
+
+## Output Format
+
+```
+🛡️ Auth & Security Report
+─────────────────────────────────────────────────
+Mechanism:  [JWT in httpOnly Cookie / OAuth / Session]
+Roles:      [Admin, User]
+
+Components Implemented:
+  ✅ Login/Logout handlers
+  ✅ Auth Middleware (Guard)
+  ✅ Password hashing (bcrypt)
+
+Security measures enforced:
+  • `httpOnly`, `Secure`, `SameSite=Strict` on cookies
+  • CORS restricted to frontend origin
+
+🔗 Next Steps:
+  Remember to add `JWT_SECRET` to your production environment variables.
+```

package/skills/qk-ai-builder/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: qk-ai-builder
+purpose: Thiết kế hệ thống AI App (RAG, Agent, Prompt, Logic AI).
+mode_supported: [enterprise]
+input: [AI Requirement]
+output: [AI Architecture, Agents]
+workflow: [1. Architecture -> 2. Agent -> 3. Memory -> 4. Evaluation -> 5. Monitoring]
+allowed_tools: [write_to_file]
+handoff_to: [qk-validation-gate]
+---
+
+# 🛠️ qk-ai-builder - Quy Trình Vận Hành Chuẩn (SOP)
+
+> **Mô tả:** Thiết kế hệ thống AI App (RAG, Agent, Prompt, Logic AI).
+
+## 🎯 1. Mục Tiêu (Goal)
+- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
+- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
+
+## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
+*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
+1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
+2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
+3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
+4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
+
+## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
+- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
+- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
+
+## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
+- Đích đến: `qk-validation-gate`
+- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.