ai-developer-skill-os 1.7.1 → 1.9.1

package/docs/CHI_TIET_SKILLS.md

@@ -1,117 +1,125 @@
-# Chi Tiết 23 Skills — AI Developer Skill OS
+# Từ Điển Chi Tiết 22 Siêu Kỹ Năng (Master Skills)
 
-**Tác giả:** Quang Khánh  
-**Phiên bản:** v1.0.1
-
-Tài liệu này giải thích chi tiết chức năng của từng Skill trong bộ Skill OS.
-AI sẽ đọc mô tả (description) bằng tiếng Anh để nhận diện, nhưng bạn có thể đọc tài liệu tiếng Việt này để hiểu AI có thể làm được gì.
+Dưới đây là danh sách chi tiết và giải thích cụ thể cho toàn bộ 22 Kỹ năng thuộc Kiến trúc AI Developer Skill OS. Các kỹ năng được phân chia khép kín theo 7 lớp kiến trúc tiêu chuẩn cấp doanh nghiệp (Enterprise Architecture).
 
 ---
 
-## 🛠️ Nhóm 1: Engineering Core (Kỹ thuật Cốt lõi)
+## 🏗️ Lớp 0: Foundation Layer (Nền Tảng Cốt Lõi)
+*Lớp này đóng vai trò như "Não bộ trung ương", chuyên nhận lệnh, cấp quyền, cung cấp luật lệ và chuẩn bị môi trường trước khi bất kỳ dòng code nào được viết ra.*
+
+### 1. `qk-orchestrator` (Trợ Lý Điều Phối)
+- **Mô tả:** Nhận lệnh chung chung từ người dùng, tự động phân tích ý đồ và định hướng luồng công việc (chọn gọi các kỹ năng nào tiếp theo).
+- **Khi nào dùng:** Khi bạn có một yêu cầu lớn và không biết bắt đầu từ đâu.
+
+### 2. `qk-context-loader` (Nạp Ngữ Cảnh)
+- **Mô tả:** Có khả năng đọc lướt dự án để gom chính xác các file liên quan đến task hiện tại (chống tràn bộ nhớ token của AI).
+- **Khi nào dùng:** Khi code dự án quá lớn, cần khoanh vùng các file cần sửa.
 
-Đây là các kỹ năng chung quản lý toàn bộ dự án, kiến trúc và mã nguồn.
+### 3. `qk-policy-engine` (Động Cơ Chính Sách)
+- **Mô tả:** Xét duyệt xem yêu cầu của người dùng hoặc hành động của AI có vi phạm các nguyên tắc cốt lõi của dự án không.
+- **Khi nào dùng:** Được AI tự động gọi trước khi thực thi để đảm bảo tính hợp lệ.
 
-### 1. `agent-orchestrator` (Người Điều Phối)
-- **Mô tả:** AI không tự viết code mà đóng vai trò như một Project Manager. Phân tích yêu cầu phức tạp của bạn, chia nhỏ thành các tác vụ (Task) và quyết định gọi các Skill nào theo thứ tự nào.
-- **Khi nào dùng:** Khi bạn giao một việc lớn ("Làm cho tôi tính năng thanh toán") mà không biết bắt đầu từ đâu.
+### 4. `qk-access-policy` (Kiểm Soát Phân Quyền)
+- **Mô tả:** Xử lý và cung cấp các quy tắc về bảo mật (Security), phân quyền (RBAC), Authentication (JWT/OAuth).
+- **Khi nào dùng:** Khi tính năng liên quan đến việc bảo mật, ai được quyền truy cập vào đâu.
 
-### 2. `context-manager` (Quản Lý Ngữ Cảnh)
-- **Mô tả:** Xác định file nào cần đọc, đọc cấu trúc thư mục, ghi nhớ kiến trúc hệ thống để AI không bị "quên" hoặc đọc tràn ngập các file không cần thiết.
-- **Khi nào dùng:** Khi bắt đầu một dự án mới tinh, hoặc khi AI cần nắm bắt bức tranh tổng thể.
+### 5. `qk-project-memory` (Trí Nhớ Dự Án)
+- **Mô tả:** Lưu trữ DNA của dự án, các quyết định kiến trúc, UI pattern và các convention đã được thống nhất từ trước.
+- **Khi nào dùng:** Khi muốn AI làm theo đúng style đã có sẵn trong dự án.
 
-### 3. `project-audit` (Kiểm Toán Dự Án)
-- **Mô tả:** Quét toàn bộ mã nguồn hoặc các file bạn vừa thay đổi để tìm kiếm bug tiềm ẩn, code smell, lỗ hổng bảo mật hoặc nợ kỹ thuật. AI sẽ xuất ra một báo cáo khám bệnh chi tiết.
-- **Khi nào dùng:** Trước khi refactor lớn, trước khi release, hoặc muốn kiểm tra code mình viết có sạch không.
+### 6. `qk-engineering-standard` (Bộ Luật Thiết Kế)
+- **Mô tả:** Bơm các "luật thép" (về Frontend, Backend, Database) vào ngữ cảnh để bắt AI tuân thủ cấu trúc thư mục và naming.
+- **Khi nào dùng:** Tự động gọi để ép AI viết code không bị rác.
 
-### 4. `bug-fix` (Chuyên Gia Sửa Lỗi)
-- **Mô tả:** Dò tìm nguyên nhân gốc rễ (root cause) của một lỗi dựa trên stack trace hoặc mô tả của bạn. Không chữa cháy tạm thời, cung cấp bản fix tối thiểu và an toàn nhất.
-- **Khi nào dùng:** Khi app bị crash, test fail, màn hình trắng.
+### 7. `qk-project-bootstrap` (Khởi Tạo Dự Án)
+- **Mô tả:** Setup toàn bộ khung sườn của một dự án mới tinh từ con số 0 (Cấu hình lint, format, folder structure).
+- **Khi nào dùng:** Lúc bắt đầu dự án mới.
+
+---
 
-### 5. `refactor` (Tái Cấu Trúc Code)
-- **Mô tả:** Làm sạch code, tách hàm, tách component, xóa code thừa, dọn dẹp biến mà **không làm thay đổi logic hoạt động**.
-- **Khi nào dùng:** Khi code quá rối rắm (spaghetti code), cần dọn dẹp cho dễ bảo trì.
+## 🎨 Lớp 1: UI System Layer (Hệ Thống Giao Diện)
+*Nhóm chuyên biệt về vẽ giao diện và quản lý hệ thống thành phần (Components).*
 
-### 6. `api-integration` (Kỹ Sư Tích Hợp API)
-- **Mô tả:** Nhận bất kỳ input nào (curl, swagger, postman, backend controller) và sinh ra một lớp gọi API hoàn chỉnh cho Frontend (Type chuẩn, xử lý lỗi, call Axios/Fetch/React Query).
-- **Khi nào dùng:** Khi Backend vừa làm xong API và bạn cần nối nó vào Frontend.
+### 8. `qk-ui-system-builder` (Kỹ Sư Hệ Thống UI)
+- **Mô tả:** Quản lý Design Token, tạo ra các Component có thể tái sử dụng (Button, Table, Form) đảm bảo tính nhất quán toàn dự án.
+- **Khi nào dùng:** Xây dựng thư viện giao diện, tránh viết CSS lộn xộn.
 
-### 7. `migration` (Nâng Cấp Hệ Thống)
-- **Mô tả:** Nâng cấp an toàn các thư viện cũ (như React 17 lên 19), chuyển đổi thư viện (Moment sang Date-fns) theo mô hình tăng dần, có kế hoạch Rollback.
-- **Khi nào dùng:** Khi cần update package có lỗ hổng bảo mật hoặc chuyển framework.
+### 9. `qk-design-to-code` (Chuyển Đổi Thiết Kế)
+- **Mô tả:** Đọc hiểu hình ảnh/Figma để tự động chuyển thành mã nguồn giao diện (React, Tailwind, v.v.).
+- **Khi nào dùng:** Bóc tách UI từ bản thiết kế.
 
-### 8. `git-engineer` (Quản Lý Git & Release)
-- **Mô tả:** Viết commit message cực chuẩn theo Conventional Commits, viết mô tả Pull Request, sinh Changelog và Release Notes cho sếp/khách hàng đọc.
-- **Khi nào dùng:** Khi code xong và cần đẩy code lên hoặc chuẩn bị release version mới.
+### 10. `qk-ui-audit` (Kiểm Toán Giao Diện)
+- **Mô tả:** Kiểm tra độ nhất quán UI/UX, hỗ trợ Responsive trên điện thoại và tối ưu khả năng tiếp cận (Accessibility - a11y).
+- **Khi nào dùng:** Kiểm tra lỗi UI sau khi hoàn thiện giao diện.
 
 ---
 
-## 🎨 Nhóm 2: Frontend (Giao Diện)
+## 💻 Lớp 2: Development Layer (Phát Triển E2E)
+*Khối thực thi mạnh mẽ nhất, đi từ A-Z một tính năng cụ thể.*
 
-Nhóm chuyên biệt cho việc xây dựng giao diện người dùng (UI/UX).
+### 11. `qk-feature-delivery` (Chuyển Giao Tính Năng)
+- **Mô tả:** Kỹ năng toàn năng, tự động phân tích thiết kế Database -> Viết API -> Xây UI -> Viết Unit Test cho một tính năng trọn vẹn.
+- **Khi nào dùng:** Xây dựng tính năng hoàn chỉnh (Ví dụ: Chức năng Thanh Toán).
 
-### 9. `frontend-architecture` (Kiến Trúc Frontend)
-- **Mô tả:** Đọc hiểu và ép AI phải tuân thủ việc đặt file ở đâu cho đúng chuẩn của project (Features-based, Layer-based, DDD...).
-- **Khi nào dùng:** Khi không biết nên tạo file component mới ở thư mục nào.
+### 12. `qk-api-lifecycle` (Vòng Đời API)
+- **Mô tả:** Chuyên biệt cho Backend: Viết spec, tạo Service, định nghĩa Type, viết Test và sinh tài liệu cho API.
+- **Khi nào dùng:** Xây dựng các Endpoint API.
 
-### 10. `design-system` (Hệ Thống Thiết Kế)
-- **Mô tả:** Ép AI phải dùng thư viện UI có sẵn (MUI, Shadcn, Tailwind...) thay vì tự viết HTML chay hay CSS inline lộn xộn.
-- **Khi nào dùng:** Đi kèm khi xây dựng UI để giữ tính nhất quán.
+### 13. `qk-data-lifecycle` (Vòng Đời Dữ Liệu)
+- **Mô tả:** Quản lý Schema, tạo file Migration, tối ưu câu lệnh truy vấn (SQL, Prisma, v.v.).
+- **Khi nào dùng:** Thay đổi cấu trúc cơ sở dữ liệu.
 
-### 11. `ui-builder` (Xây Dựng Giao Diện)
-- **Mô tả:** Lắp ráp các component nhỏ thành một màn hình/trang hoàn chỉnh, xử lý layout (Grid/Flexbox) và responsive (di động/máy tính).
-- **Khi nào dùng:** Khi bạn đưa wireframe/mockup và bảo "Làm cho tôi màn hình Dashboard".
+---
 
-### 12. `component-generator` (Tạo Component Đơn Lẻ)
-- **Mô tả:** Sinh ra các mảnh ghép UI nhỏ, tái sử dụng được (như Button, Card, Dropdown) với Props Type an toàn.
-- **Khi nào dùng:** Khi cần tạo một UI Component dùng chung.
+## 🛡️ Lớp 3: Quality Assurance Layer (Đảm Bảo Chất Lượng)
+*Kiểm tra độ sạch của code và diệt bug.*
 
-### 13. `state-management` (Quản Lý Trạng Thái)
-- **Mô tả:** Phân tích dữ liệu và quyết định nên dùng React Query, Redux, Zustand hay chỉ là useState local. Setup các store hoàn chỉnh.
-- **Khi nào dùng:** Khi phải truyền Props quá sâu, hoặc cần lưu cache dữ liệu.
+### 14. `qk-project-health` (Kiểm Toán Dự Án)
+- **Mô tả:** Quét toàn bộ dự án để tìm Code Smell, Nợ kỹ thuật (Tech Debt), và các vi phạm kiến trúc.
+- **Khi nào dùng:** Định kỳ kiểm tra chất lượng mã nguồn hoặc tối ưu hiệu năng.
 
-### 14. `form-builder` (Chuyên Gia Làm Form)
-- **Mô tả:** Sinh ra các Form phức tạp với validate đầu vào (Zod, Yup) kết hợp React Hook Form. Hiển thị báo lỗi chuẩn mực.
-- **Khi nào dùng:** Làm màn hình Đăng ký, Đăng nhập, Tạo mới dữ liệu.
+### 15. `qk-bug-resolution` (Giải Quyết Bug Triệt Để)
+- **Mô tả:** Tái hiện lỗi, đào sâu tìm Root Cause, cung cấp giải pháp an toàn và viết Regression Test để chống lỗi lặp lại.
+- **Khi nào dùng:** Sửa các lỗi đứt gãy hoặc logic nghiêm trọng.
 
-### 15. `table-crud-generator` (Làm Bảng Dữ Liệu)
-- **Mô tả:** Sinh ra bảng Data Grid hoàn chỉnh có phân trang (pagination), lọc, sắp xếp và các nút hành động (Thêm/Sửa/Xóa).
-- **Khi nào dùng:** Làm trang Admin quản trị.
+### 16. `qk-validation-gate` (Cổng Kiểm Định)
+- **Mô tả:** Kỹ năng chặn cửa. Bắt buộc chạy Test, Linting và Scan Security. Chỉ khi "PASS" mới cho phép kết thúc task.
+- **Khi nào dùng:** Nằm cuối quy trình code của bất kỳ tính năng nào.
 
-### 16. `frontend-debug` (Sửa Lỗi Frontend)
-- **Mô tả:** Chuyên trị các lỗi khó chịu của UI như: Hydration Error (Next.js), Infinite Re-render (lặp vô tận), lỗi vỡ CSS layout.
-- **Khi nào dùng:** Lỗi vỡ giao diện hoặc lỗi render của React.
+---
 
-### 17. `frontend-testing` (Kiểm Thử UI)
-- **Mô tả:** Viết Unit Test, Component Test (React Testing Library) hay E2E Test (Cypress/Playwright) giả lập hành vi người dùng thật.
-- **Khi nào dùng:** Khi sếp yêu cầu tăng Test Coverage hoặc bọc test cho tính năng quan trọng.
+## 🚀 Lớp 4 & 5: Evolution & Operation (Vận Hành & Tiến Hóa)
+*Triển khai dự án lên Production và nâng cấp phiên bản lớn.*
 
-### 18. `accessibility-audit` (Kiểm Tra Tiếp Cận)
-- **Mô tả:** Đảm bảo trang web chuẩn WCAG, dùng đúng thẻ Semantic HTML, có thể dùng phím Tab để điều hướng và hỗ trợ phần mềm đọc màn hình cho người khiếm thị.
-- **Khi nào dùng:** Làm các project chuẩn quốc tế, nhà nước, hoặc tối ưu SEO nâng cao.
+### 17. `qk-system-evolution` (Tiến Hóa Hệ Thống)
+- **Mô tả:** Nâng cấp dependency (VD: Next 14 lên 15), phân tích rủi ro ảnh hưởng và thực thi nâng cấp an toàn không downtime.
+- **Khi nào dùng:** Update version framework/thư viện.
 
-### 19. `frontend-performance` (Tối Ưu Hiệu Năng)
-- **Mô tả:** Chữa bệnh web chạy chậm. Tối ưu ảnh, chẻ nhỏ file JS (Code splitting, Lazy load), thêm `useMemo/useCallback` để tránh giật lag.
-- **Khi nào dùng:** Điểm Google Lighthouse thấp, web bị khựng khi cuộn.
+### 18. `qk-production-release` (Triển Khai Môi Trường)
+- **Mô tả:** Viết Dockerfile, cấu hình CI/CD Pipelines (Github Actions), Deploy lên Cloud (AWS, Vercel).
+- **Khi nào dùng:** Release sản phẩm cho người dùng cuối.
 
 ---
 
-## ⚙️ Nhóm 3: Backend (Máy Chủ)
+## 🤖 Lớp 6: AI Builder Layer (Tích hợp AI)
 
-Nhóm chuyên biệt cho việc xây dựng và quản lý API, máy chủ.
+### 19. `qk-ai-builder` (Xây Dựng AI App)
+- **Mô tả:** Chuyên thiết kế và code các ứng dụng AI như RAG (Retrieval-Augmented Generation), Agent logic và Prompt Engineering.
+- **Khi nào dùng:** Tích hợp LLM vào trong phần mềm của bạn.
+
+---
 
-### 20. `backend-architecture` (Kiến Trúc Backend)
-- **Mô tả:** Phân chia rạch ròi đâu là Controller (xử lý HTTP), đâu là Service (Xử lý nghiệp vụ), đâu là Repository (Gọi Database) để code không bị thành một đống bùi nhùi.
-- **Khi nào dùng:** Cấu trúc file cho backend mới hoặc thêm module mới.
+## 📚 Lớp 7: Knowledge Layer (Tri Thức & Tài Liệu)
+*Hệ thống tự học và viết tài liệu vĩ đại của OS.*
 
-### 21. `database-engineer` (Kỹ Sư Cơ Sở Dữ Liệu)
-- **Mô tả:** Thiết kế schema, vẽ quan hệ bảng, sinh script Migration, tối ưu hóa câu lệnh truy vấn (SQL, Prisma, Drizzle, MongoDB).
-- **Khi nào dùng:** Cần thêm bảng mới vào DB hoặc API truy vấn DB quá chậm.
+### 20. `qk-docs` (Kỹ Sư Tài Liệu)
+- **Mô tả:** Tự động sinh hoặc cập nhật tài liệu cho con người đọc: `README.md`, `CHANGELOG.md`, `API Docs`.
+- **Khi nào dùng:** Nằm ở cuối quy trình sau khi hoàn thành tính năng.
 
-### 22. `auth-security` (Bảo Mật & Phân Quyền)
-- **Mô tả:** Triển khai đăng nhập JWT, OAuth, thiết lập phân quyền (Admin vs User), phòng chống hacker tấn công bằng các cấu hình bảo mật chuẩn OWASP.
-- **Khi nào dùng:** Làm tính năng đăng nhập, bảo vệ API nhạy cảm.
+### 21. `qk-documentation-system` (Hệ Thống Trí Nhớ)
+- **Mô tả:** Quản trị Tri thức máy. Tự động rút trích các Quyết định Kỹ thuật (ADR) hoặc Pattern mới xuất hiện trong code, và nạp ngược lại vào `qk-project-memory`.
+- **Khi nào dùng:** Hệ thống "tự học" để Agent trở nên thông minh hơn qua từng ngày.
 
-### 23. `deployment` (Triển Khai DevOps)
-- **Mô tả:** Viết Dockerfile, cấu hình CI/CD bằng GitHub Actions, thiết lập luồng tự động build và deploy lên Vercel, AWS hoặc VPS.
-- **Khi nào dùng:** Lúc cần đưa code lên môi trường production cho khách hàng xem.
+### 22. `qk-help` (Tra Cứu Nhanh)
+- **Mô tả:** Cuốn từ điển sống. Cung cấp thông tin và hướng dẫn chi tiết (Pro-tips) về cách sử dụng toàn bộ hệ thống.
+- **Khi nào dùng:** Bất kỳ khi nào người dùng cần hỗ trợ sử dụng hệ điều hành.

package/docs/HUONG_DAN_SU_DUNG.md

@@ -1,9 +1,9 @@
 # Hướng Dẫn Sử Dụng — AI Developer Skill OS
 
 **Tác giả:** Quang Khánh  
-**Phiên bản:** v1.0.1  
+**Phiên bản:** v2.0.0 (Master OS Architecture)
 
-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ụ.
+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.
 
 ---
 
@@ -11,12 +11,12 @@ Chào mừng bạn đến với **AI Developer Skill OS**, bộ khung quản lý
 
 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.
+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.
 
 ---
 
@@ -26,117 +26,95 @@ Bộ Skin này rất linh hoạt và được phân phối qua NPM để bạn c
 
 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
+npx rules-skill-ai 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).
+- **(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!
 
-### 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.
+### 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` (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:
+#### 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 `./.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.
+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)
+#### 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 `./.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.
+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.
 ```
 
-### 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
+## 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ộ 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ì.
+Để 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 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.
+✅ **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.
 
 ---
 
-## 5. Cách gọi lệnh Skill chuyên nghiệp (Usage)
+## 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 gõ prompt nhất là bạn sử dụng cú pháp lệnh độc quyền: **`./qk-[tên-skill]`**
+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: 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ụ 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ụ 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ụ 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ụ 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ụ 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ụ 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ụ 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ụ 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.
+### 🎯 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.
 
 ---
 
-## 6. 💡 Mẹo & Workflow Thực Chiến (Best Practices)
+## 💡 5. 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.
+Để 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ẻ.
 
-### 🌟 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]`
+### 🌟 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.
 
-### 🌟 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 đó.`
+### 🌟 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.`
 
-### 🌟 Workflow Chống "Phá Code" (Safe Refactor)
+### 🌟 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.`
+* `> 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 Tech Lead thực thụ!
+👉 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.7.1",
+  "version": "1.9.1",
   "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