ai-developer-skill-os 8.3.0 → 9.0.0

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

@@ -1,12 +1,12 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-ai-builder
-version: 8.2.0
+version: 9.0.0
 status: stable
 description: "Thiết kế Governed AI Agent & RAG pipelines theo chuẩn V8.2 — Đóng gói bằng capability.yaml, data discipline 4-folder và Eval Pipeline."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
-# ── V8: Classification ─────────────────────────────────────
+# ── V9: Classification ─────────────────────────────────────
 type: capability
 
 intent:
@@ -87,6 +87,136 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 ---
 
+## Memory Workflow
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture
+  - Hard Bug
+  - Convention
+  - Pattern
+  - Tech Debt Pattern
+  - 👉 *Domain Focus:* Architecture/Pattern (vd: cấu hình provider LLM, chuẩn RAG pipeline, prompt template).
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
+  Không được xem Memory là Source of Truth.
+  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Pattern hoặc Convention mới (vd: quy chuẩn JSON schema cho prompt, scorecard định lượng).
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Các thao tác tinh chỉnh từ ngữ prompt tạm thời cho 1 task đơn lẻ.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Pattern hoặc Convention mới (vd: quy chuẩn JSON schema cho prompt, scorecard định lượng).
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Các thao tác tinh chỉnh từ ngữ prompt tạm thời cho 1 task đơn lẻ.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+---
+---
+
 ## Preconditions
 - [ ] AI task is defined: what input → what output
 - [ ] LLM provider is specified (OpenAI, Anthropic, Gemini, local)

package/.agents/skills/qk-ai-builder/capability.yaml

@@ -0,0 +1,23 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-ai-builder"
+version: "9.0.0"
+description: "Thiết kế Governed AI Agent & RAG pipelines theo chuẩn V8.2 — Đóng gói bằng capability.yaml, data discipline 4-folder và Eval Pipeline."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "agent-architecture"
+    - "skill-generation"
+  references:
+    - "architecture"
+    - "security"
+    - "anti-patterns"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "qk-ai-builder"
+  does_not_own: []
+  conflicts_with: []

package/.agents/skills/qk-ai-builder/evals/scorecard.yaml

@@ -0,0 +1,30 @@
+name: qk-ai-builder-eval
+description: Đánh giá chất lượng thiết kế Agent & RAG Pipeline
+version: 9.0.0
+threshold: 90 # Yêu cầu rất cao vì liên quan đến an ninh (injection) và cấu trúc V8
+
+metrics:
+  - id: prompt_design
+    name: Thiết kế System Prompt
+    description: Prompt có tuân thủ đúng cấu trúc chuẩn và giới hạn an toàn không?
+    weight: 30
+    criteria:
+      - Có cấu trúc rõ ràng (ROLE, TASK, CONSTRAINTS) (10đ)
+      - Có định dạng đầu ra (OUTPUT FORMAT) bằng JSON Schema chuẩn (10đ)
+      - Có Examples (few-shot) để hướng dẫn LLM (10đ)
+
+  - id: security_anti_injection
+    name: Bảo mật Anti-Injection (R-SEC-04)
+    description: Các biện pháp phòng ngừa Prompt Injection có được áp dụng không?
+    weight: 40
+    criteria:
+      - Input của user được bọc trong thẻ XML `<user_input>...</user_input>` (20đ)
+      - Output có chứa trường `confidence` để fallback/human review nếu kết quả có vấn đề (20đ)
+
+  - id: v8_packaging
+    name: Đóng gói chuẩn V8.2
+    description: Kiến trúc 4-folder và file định nghĩa có đầy đủ không?
+    weight: 30
+    criteria:
+      - Khởi tạo đúng cấu trúc 4 thư mục: prompts/, data/, agents/, evals/ (15đ)
+      - Tự động sinh ra `capability.yaml` và `scorecard.yaml` cho skill mới (15đ)

package/.agents/skills/qk-api-lifecycle/SKILL.md

@@ -1,12 +1,12 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-api-lifecycle
-version: 8.0.0
+version: 9.0.0
 status: stable
 description: "Thiết kế, triển khai API endpoints với Zero-Trust — contract trước, code sau."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
-# ── V8: Classification ─────────────────────────────────────
+# ── V9: Classification ─────────────────────────────────────
 type: capability
 
 intent:
@@ -86,6 +86,136 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 ---
 
+## Memory Workflow
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture
+  - Hard Bug
+  - Convention
+  - Pattern
+  - Tech Debt Pattern
+  - 👉 *Domain Focus:* Convention/Pattern (vd: cấu trúc wrapper { status, data, error }, pagination format).
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
+  Không được xem Memory là Source of Truth.
+  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Pattern hoặc Convention mới của dự án (vd: chuẩn xử lý lỗi API mới, rate limiting).
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Thao tác thêm 1 CRUD endpoint thông thường theo Hợp đồng sẵn có.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Pattern hoặc Convention mới của dự án (vd: chuẩn xử lý lỗi API mới, rate limiting).
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Thao tác thêm 1 CRUD endpoint thông thường theo Hợp đồng sẵn có.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+---
+---
+
 ## Preconditions
 - [ ] API purpose and resource name are defined
 - [ ] Request/response shape is specified (or sample JSON provided)

package/.agents/skills/qk-api-lifecycle/capability.yaml

@@ -0,0 +1,23 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-api-lifecycle"
+version: "9.0.0"
+description: "Thiết kế, triển khai API endpoints với Zero-Trust — contract trước, code sau."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "api-contracts"
+    - "endpoints"
+  references:
+    - "architecture"
+    - "security"
+    - "anti-patterns"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "qk-api-lifecycle"
+  does_not_own: []
+  conflicts_with: []

package/.agents/skills/qk-api-lifecycle/evals/scorecard.yaml

@@ -0,0 +1,29 @@
+name: qk-api-lifecycle-eval
+description: Đánh giá chất lượng thiết kế và triển khai API
+version: 9.0.0
+threshold: 90 # Tiêu chuẩn cao vì liên quan đến hợp đồng dữ liệu và bảo mật cổng vào
+
+metrics:
+  - id: contract_first_design
+    name: Thiết kế theo hợp đồng (Contract-first)
+    description: Agent có định nghĩa Types/Interfaces rõ ràng trước khi code logic không?
+    weight: 30
+    criteria:
+      - Định nghĩa rõ ràng Request & Response structure bằng TypeScript interface / DTO (15đ)
+      - Khai báo đầy đủ HTTP method, route path và các HTTP status codes có thể trả về (15đ)
+
+  - id: zero_trust_validation
+    name: Tuân thủ Zero-Trust (R-SEC-04)
+    description: Mọi API Endpoint có được bảo vệ và validate dữ liệu ở cổng vào không?
+    weight: 40
+    criteria:
+      - Áp dụng thư viện validation (zod/yup/class-validator) cho toàn bộ input payload (20đ)
+      - Không rò rỉ dữ liệu nhạy cảm ở response cổng ra (sanitize/mask data) (20đ)
+
+  - id: error_handling_and_compat
+    name: Xử lý lỗi và Tương thích ngược
+    description: API có xử lý mượt mà các tình huống lỗi và giữ tính backward compatibility không?
+    weight: 30
+    criteria:
+      - Trả về đúng HTTP status code (400, 401, 403, 404, 422, 500) thay vì trả 500 cho mọi lỗi (15đ)
+      - Không làm hỏng (breaking changes) các trường dữ liệu của contract cũ mà không tăng version (15đ)

package/.agents/skills/qk-bug-resolution/SKILL.md

@@ -1,12 +1,12 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-bug-resolution
-version: 8.0.0
+version: 9.0.0
 status: stable
 description: "Sửa lỗi (bugs) bằng chu trình khép kín: Quan sát → Giả thuyết → Bằng chứng → Sửa."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
-# ── V8: Classification ─────────────────────────────────────
+# ── V9: Classification ─────────────────────────────────────
 type: capability
 
 intent:
@@ -91,6 +91,136 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 ---
 
+## Memory Workflow
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture
+  - Hard Bug
+  - Convention
+  - Pattern
+  - Tech Debt Pattern
+  - 👉 *Domain Focus:* Hard Bug (vd: lỗi memory leak, race condition, lỗi thư viện tương tự từng gặp).
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
+  Không được xem Memory là Source of Truth.
+  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Hard Bug mới có khả năng tái diễn (vd: nguyên nhân sâu xa của crash/leak để phòng ngừa).
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Lỗi nhỏ chỉ xảy ra một lần (vd: typo, quên import, thiếu ngoặc đơn giản).
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Hard Bug mới có khả năng tái diễn (vd: nguyên nhân sâu xa của crash/leak để phòng ngừa).
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Lỗi nhỏ chỉ xảy ra một lần (vd: typo, quên import, thiếu ngoặc đơn giản).
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+---
+---
+
 ## Preconditions
 - [ ] A specific symptom is provided (error message, wrong behavior, crash)
 - [ ] The affected file or feature area is identifiable

package/.agents/skills/qk-bug-resolution/capability.yaml

@@ -0,0 +1,25 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-bug-resolution"
+version: "9.0.0"
+description: "Sửa lỗi (bugs) bằng chu trình khép kín: Quan sát → Giả thuyết → Bằng chứng → Sửa."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "bug-diagnosis"
+    - "fix-strategies"
+    - "root-cause-analysis"
+  references:
+    - "testing"
+    - "language-specific-features"
+    - "security"
+    - "anti-patterns"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "qk-bug-resolution"
+  does_not_own: []
+  conflicts_with: []

package/.agents/skills/qk-bug-resolution/evals/scorecard.yaml

@@ -0,0 +1,30 @@
+name: qk-bug-resolution-eval
+description: Đánh giá chất lượng quy trình sửa lỗi (Bug Resolution)
+version: 9.0.0
+threshold: 85 # Quy trình sửa lỗi cần bằng chứng rõ ràng và sửa đúng trọng tâm
+
+metrics:
+  - id: evidence_based_diagnosis
+    name: Chẩn đoán dựa trên bằng chứng
+    description: Agent có tìm ra chính xác dòng code gây lỗi trước khi sửa không?
+    weight: 40
+    criteria:
+      - Xác định được chính xác file và dòng gây lỗi (file:line) dựa vào stack trace/log thay vì đoán mò (20đ)
+      - Phân tích đúng Root Cause (nguyên nhân gốc rễ) trước khi đưa ra giải pháp (20đ)
+
+  - id: minimal_targeted_patch
+    name: Sửa lỗi tối giản và đúng trọng tâm
+    description: Bản vá lỗi có gọn gàng và không ảnh hưởng đến logic khác không?
+    weight: 35
+    criteria:
+      - Sửa trực tiếp vào source code, thay đổi mã nguồn ít nhất có thể (minimal diff) (15đ)
+      - Không refactor lan man ra ngoài phạm vi gây lỗi (10đ)
+      - Giải quyết triệt để nguyên nhân, không dùng mẹo che giấu lỗi (vd: không lạm dụng `?` hoặc `!` chỉ để ép kiểu) (10đ)
+
+  - id: verification_and_safety
+    name: Kiểm chứng và an toàn
+    description: Agent có kiểm tra lại sau khi sửa và tuân thủ ranh giới không?
+    weight: 25
+    criteria:
+      - Re-read (đọc lại) code sau khi sửa để xác nhận logic đã chuẩn xác (Static Verification) (15đ)
+      - Không phá vỡ ranh giới bảo mật (Zero-Trust) chỉ để code chạy được (10đ)