ai-developer-skill-os 3.1.0 → 3.1.1

package/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI / Spec Compliance & Registry Validation
+
+on:
+  pull_request:
+    paths:
+      - 'skills/**'
+      - 'skills.json'
+      - 'docs/SPEC.md'
+      - 'bin/install.js'
+  push:
+    branches: [ main ]
+    paths:
+      - 'skills/**'
+      - 'skills.json'
+      - 'docs/SPEC.md'
+      - 'bin/install.js'
+
+jobs:
+  lint-and-validate:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Validate Skills Registry vs Filesystem
+        run: npm run test:registry
+
+      - name: Validate SKILL.md Spec Compliance
+        run: npm run test
+
+  snapshot:
+    runs-on: windows-latest
+    needs: lint-and-validate
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Generate Registry Snapshot
+        run: node bin/install.js --ide=7 --scope=2

package/CHANGELOG.md

@@ -1,50 +1,53 @@
-# Changelog
-
-All notable changes to the **AI Developer Skill OS** project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [3.0.1] - 2026-07-02
-
-### Changed
-- Updated skills.json version từ 1.0.1 → 3.0.1 để phản án version skills chính
-- Thay đổi status các skill từ `planned` → `ready` 
-- Cập nhật `qk-bug-fix` → `qk-bug-resolution` với version 3.0.0
-
-### Added
-- Thêm `knowledge/backend/nodejs.md` - tài liệu kiến trúc backend Node.js
-- Thêm categories registry cho dễ phân loại skills
-
-### Fixed
-- Sửa lỗi `qk-projects-bootstrap` → `qk-project-bootstrap` typo trong categories
-
-## [1.0.1] - 2026-07-01
-### Fixed
-- Standardized Language rule across all 23 SKILL.md files for consistency.
-- Updated registry version to match package.json.
-
-## [1.0.0] - 2026-07-01
-
-### Added
-- Released the complete AI Developer Skill OS with 23 targeted skills for coding agents.
-- **Engineering Core (8 skills):**
-  - `agent-orchestrator` for planning and delegating tasks.
-  - `context-manager` for project context and file selection.
-  - `project-audit` for 3-mode health checks.
-  - `bug-fix` with root cause analysis.
-  - `refactor` for safe, behavior-preserving code restructuring.
-  - `migration` for dependency updates and library swapping.
-  - `api-integration` for robust API connections.
-  - `git-engineer` for commit messages and PR documentation.
-- **Frontend Core (11 skills):**
-  - `frontend-architecture`, `design-system`, `ui-builder`, `component-generator`.
-  - `state-management`, `form-builder`, `table-crud-generator`.
-  - `frontend-debug`, `frontend-testing`, `accessibility-audit`, `frontend-performance`.
-- **Backend Core (4 skills):**
-  - `backend-architecture`, `database-engineer`, `auth-security`, `deployment`.
-- Added comprehensive `skills.json` registry with dependencies and trigger keywords.
-- Added bilingual `README.md` (English/Vietnamese).
-- Added detailed user documentation in `docs/HUONG_DAN_SU_DUNG.md` and `docs/CHI_TIET_SKILLS.md`.
-- Translated all skill frontmatter descriptions to Vietnamese for better UX in agent terminals.
-- Included generic English and Vietnamese usage examples in `_template/examples/`.
+# Changelog
+
+All notable changes to the **AI Developer Skill OS** project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [4.0.0] - 2026-07-02
+
+### Changed (Major Architecture Upgrade)
+- **Intent-Based Agent Architecture:** Replaced rule-based individual skill exceptions with global behavioral group classifications (Static Analysis, Development, Validation, Maintenance).
+- **OS Kernel Refactor:** Completely rewrote `AGENTS.md` (the "OS Kernel") into a strictly organized, lightweight structure under 100 lines.
+- **Progressive Evidence Collection:** Agents now enforce an 80% Confidence Threshold and incremental Context Budget (`1 file` → `3 files`) to prevent over-fetching and hallucination loops.
+- **Cost & Escalation Policies:** Introduced strict cost-optimization logic, Stopping Criteria, and Escalation protocols to prevent infinite `run_command` retries.
+- **Risk-based Verification:** Dynamic test execution based on the risk level of changes (Levels 0-3).
+
+### Added
+- **Registry Validation Suite:** Full Vitest test suite enforcing SKILL.md frontmatter compliance against `docs/SPEC.md`.
+- **GitHub Actions CI:** Automated validation on every PR and push to main.
+- **Idempotent Installer:** `bin/install.js` now detects and updates existing rule blocks instead of duplicating them.
+- **Kilo Code Native Support:** First-class support for `CLAUDE.md` + `kilo.json` config generation.
+- **Governance Docs:** `docs/GOVERNANCE.md`, ADRs, and skill classification policy for enterprise maintainability.
+- **Engineering Standards:** `qk-engineering-standard` and `qk-validation-gate` skills enforce SOLID, DRY, Clean Code, and mandatory quality gates.
+
+## [1.0.1] - 2026-07-01
+### Fixed
+- Standardized Language rule across all 23 SKILL.md files for consistency.
+- Updated registry version to match package.json.
+
+## [1.0.0] - 2026-07-01
+
+### Added
+- Released the complete AI Developer Skill OS with 23 targeted skills for coding agents.
+- **Engineering Core (8 skills):**
+  - `agent-orchestrator` for planning and delegating tasks.
+  - `context-manager` for project context and file selection.
+  - `project-audit` for 3-mode health checks.
+  - `bug-fix` with root cause analysis.
+  - `refactor` for safe, behavior-preserving code restructuring.
+  - `migration` for dependency updates and library swapping.
+  - `api-integration` for robust API connections.
+  - `git-engineer` for commit messages and PR documentation.
+- **Frontend Core (11 skills):**
+  - `frontend-architecture`, `design-system`, `ui-builder`, `component-generator`.
+  - `state-management`, `form-builder`, `table-crud-generator`.
+  - `frontend-debug`, `frontend-testing`, `accessibility-audit`, `frontend-performance`.
+- **Backend Core (4 skills):**
+  - `backend-architecture`, `database-engineer`, `auth-security`, `deployment`.
+- Added comprehensive `skills.json` registry with dependencies and trigger keywords.
+- Added bilingual `README.md` (English/Vietnamese).
+- Added detailed user documentation in `docs/HUONG_DAN_SU_DUNG.md` and `docs/CHI_TIET_SKILLS.md`.
+- Translated all skill frontmatter descriptions to Vietnamese for better UX in agent terminals.
+- Included generic English and Vietnamese usage examples in `_template/examples/`.

package/README.md

@@ -1,84 +1,97 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v3.0
-
-> Một hệ điều hành (AI-OS) và Nền tảng Kiến trúc Kỹ thuật (Engineering Platform) tối thượng dành cho AI Coding Agents (Claude Code, Cursor, Windsurf, Gemini, Kilo).
-
-Thay vì cung cấp các "công cụ rời rạc" (Toolbox) hoặc những prompt cồng kềnh, **AI Developer Skill OS v3.0** được thiết kế lại hoàn toàn theo chuẩn **Enterprise-ready Agentic Framework**. Nó biến Agent của bạn thành một **Senior Engineer / Chief Architect** thực thụ với khả năng tự suy luận bằng Tiếng Anh, nhưng lại báo cáo thân thiện bằng Tiếng Việt.
-
----
-
-## ✨ Tính năng chính
-- **23 Skills chuẩn Enterprise** cho Frontend, Backend, Engineering
-- **Kiến trúc 5 tầng** giúp tối ưu Context Window
-- **Pipeline tự động**: analyze → implement → validate → complete
-- **Decision Tree** cho từng skill, đưa ra quyết định chuẩn xác
-- **Knowledge RAG on-demand** - chỉ tải kiến thức khi cần thiết
-
-## 🏗️ Kiến Trúc 5 Tầng (The 5-Tier Architecture)
-
-Hệ thống được thiết kế decoupled (phân tách) hoàn hảo để chống tràn Context Window và tối ưu khả năng suy luận của LLM:
-
-### 1. OS Kernel (`.agents/AGENTS.md`)
-The core of the system is a lightweight, heavily optimized OS Kernel that dictates agent behavior across all tasks.
-- **Intent-Based Policies:** Skills are classified into 4 groups (Static Analysis, Development, Validation, Maintenance) rather than micromanaged with individual exceptions.
-- **Progressive Evidence Collection:** Agents collect context incrementally (1 file → 3 files) and stop at a 80% Confidence Threshold, eliminating "hallucination loops".
-- **Risk-based Verification:** Tests and builds are only run based on the risk level of the change, strictly guided by the Cost and Escalation policies.
-
-### 2. Core Templates (`templates/`)
-Chứa các format báo cáo chuẩn (như `bug-report.md`, `feature-report.md`, `review-report.md`). AI không cần "học lại" cách viết báo cáo, giúp đầu ra luôn nhất quán 100%.
-
-### 3. Skill Definition (`skills/`)
-Bộ 20+ kỹ năng (Skills) cốt lõi được cấu trúc siêu chuẩn xác với **Metadata 12 trường** (Version, Category, Pipeline, Allowed Tools...). Toàn bộ SOP (Standard Operating Procedure), Decision Tree và Constraints được viết 100% bằng Tiếng Anh để tối ưu hóa khả năng hiểu kỹ thuật của AI.
-
-### 4. Knowledge Library (`knowledge/`)
-Tri thức chuyên sâu được tách rời hoàn toàn khỏi Prompt. Ví dụ: Kiến thức về React (`knowledge/frontend/react.md`) chỉ được gọi (On-demand RAG) khi AI thực sự làm việc với React.
-
-### 5. Output Format (Vietnamese Report)
-Toàn bộ kết quả trả về cho bạn đều tuân thủ Output Policy: Báo cáo bằng Tiếng Việt, chia mục rõ ràng (Summary, Changes, Root Cause, Risks, Next Actions).
-
----
-
-## 🧩 Danh sách 20+ Master Skills
-
-Các skill được chia thành các nhóm (Category) rõ ràng:
-- **Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-policy-engine`, `qk-access-policy`
-- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-design-to-code`, `qk-ui-system-builder`
-- **Validation & Standards:** `qk-validation-gate`, `qk-engineering-standard`, `qk-ui-audit`, `qk-project-health`, `qk-bug-resolution`
-- **Ops & AI:** `qk-system-evolution`, `qk-production-release`, `qk-ai-builder`, `qk-project-bootstrap`
-- **Docs & Utils:** `qk-docs`, `qk-documentation-system`, `qk-project-memory`, `qk-help`
-
----
-
-## 🔄 Luồng Handoff Pipeline Khép Kín
-
-Bất cứ một tính năng hay lỗi nào cũng được đi qua một đường ống khép kín (Abstract Pipeline):
-```text
-analyze 
-  ↓
-implement 
-  ↓
-engineering-standard (Ép chuẩn Code, Naming, SOLID)
-  ↓
-validate (Chạy Linter, Tests, Security Check)
-  ↓
-complete (Tạo báo cáo bằng tiếng Việt)
-```
-
----
-
-## 💻 Cách Cài Đặt (Installation)
-
-Sử dụng npm:
-```bash
-npm i -g ai-developer-skill-os
-```
-Hoặc sử dụng qua `npx`:
-```bash
-npx ai-developer-skill-os init
-```
-
-## 🚀 Tra Cứu (Help)
-
-Để tra cứu danh sách toàn bộ 20+ Kỹ năng và các mẹo sử dụng, hãy gọi:
-```bash
-./qk-help "Hiển thị tất cả các skill"
-```
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v4.0
+
+> Một hệ điều hành (AI-OS) và Nền tảng Kiến trúc Kỹ thuật (Engineering Platform) tối thượng dành cho AI Coding Agents (Claude Code, Cursor, Windsurf, Gemini, Kilo).
+
+Thay vì cung cấp các "công cụ rời rạc" (Toolbox) hoặc những prompt cồng kềnh, **AI Developer Skill OS v4.0** được thiết kế lại hoàn toàn theo chuẩn **Enterprise-ready Agentic Framework**. Nó biến Agent của bạn thành một **Senior Engineer / Chief Architect** thực thụ với khả năng tự suy luận bằng Tiếng Anh, nhưng lại báo cáo thân thiện bằng Tiếng Việt.
+
+---
+
+## 🏗️ Kiến Trúc 5 Tầng (The 5-Tier Architecture)
+
+Hệ thống được thiết kế decoupled (phân tách) hoàn hảo để chống tràn Context Window và tối ưu khả năng suy luận của LLM:
+
+### 1. OS Kernel (`.agents/AGENTS.md`)
+The core of the system is a lightweight, heavily optimized OS Kernel that dictates agent behavior across all tasks.
+- **Intent-Based Policies:** Skills are classified into 4 groups (Static Analysis, Development, Validation, Maintenance) rather than micromanaged with individual exceptions.
+- **Progressive Evidence Collection:** Agents collect context incrementally (1 file → 3 files) and stop at a 80% Confidence Threshold, eliminating "hallucination loops".
+- **Risk-based Verification:** Tests and builds are only run based on the risk level of the change, strictly guided by the Cost and Escalation policies.
+
+### 2. Core Templates (`templates/`)
+Chứa các format báo cáo chuẩn (như `bug-report.md`, `feature-report.md`, `review-report.md`). AI không cần "học lại" cách viết báo cáo, giúp đầu ra luôn nhất quán 100%.
+
+### 3. Skill Definition (`skills/`)
+Bộ 20+ kỹ năng (Skills) cốt lõi được cấu trúc siêu chuẩn xác với **Metadata 12 trường** (Version, Category, Pipeline, Allowed Tools...). Toàn bộ SOP (Standard Operating Procedure), Decision Tree và Constraints được viết 100% bằng Tiếng Anh để tối ưu hóa khả năng hiểu kỹ thuật của AI.
+
+### 4. Knowledge Library (`knowledge/`)
+Tri thức chuyên sâu được tách rời hoàn toàn khỏi Prompt. Ví dụ: Kiến thức về React (`knowledge/frontend/react.md`) chỉ được gọi (On-demand RAG) khi AI thực sự làm việc với React.
+
+### 5. Output Format (Vietnamese Report)
+Toàn bộ kết quả trả về cho bạn đều tuân thủ Output Policy: Báo cáo bằng Tiếng Việt, chia mục rõ ràng (Summary, Changes, Root Cause, Risks, Next Actions).
+
+---
+
+## 🧩 Danh sách 20+ Master Skills
+
+Các skill được chia thành các nhóm (Category) rõ ràng:
+- **Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-policy-engine`, `qk-access-policy`
+- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-design-to-code`, `qk-ui-system-builder`
+- **Validation & Standards:** `qk-validation-gate`, `qk-engineering-standard`, `qk-ui-audit`, `qk-project-health`, `qk-bug-resolution`
+- **Ops & AI:** `qk-system-evolution`, `qk-production-release`, `qk-ai-builder`, `qk-project-bootstrap`
+- **Docs & Utils:** `qk-docs`, `qk-documentation-system`, `qk-project-memory`, `qk-help`
+
+---
+
+## 🔄 Luồng Handoff Pipeline Khép Kín
+
+Bất cứ một tính năng hay lỗi nào cũng được đi qua một đường ống khép kín (Abstract Pipeline):
+```text
+analyze 
+  ↓
+implement 
+  ↓
+engineering-standard (Ép chuẩn Code, Naming, SOLID)
+  ↓
+validate (Chạy Linter, Tests, Security Check)
+  ↓
+complete (Tạo báo cáo bằng tiếng Việt)
+```
+
+---
+
+## 💻 Cách Cài Đặt (Installation)
+
+Sử dụng npm:
+```bash
+npm i -g ai-developer-skill-os
+```
+Hoặc sử dụng qua `npx`:
+```bash
+npx ai-developer-skill-os init
+```
+
+## 🧪 Testing
+
+This project includes a full test suite to ensure registry integrity and SKILL.md spec compliance:
+
+```bash
+npm test
+```
+
+CI runs automatically on every PR via GitHub Actions, enforcing:
+- Registry matches filesystem
+- All SKILL.md frontmatters comply with `docs/SPEC.md`
+- Install script idempotency
+
+## 🗑️ Cách Gỡ Cài Đặt (Uninstallation)
+
+Nếu bạn đã cài đặt thông qua npm global, bạn có thể gỡ bỏ bằng lệnh:
+```bash
+npm uninstall -g ai-developer-skill-os
+```
+
+## 🚀 Tra Cứu (Help)
+
+Để tra cứu danh sách toàn bộ 20+ Kỹ năng và các mẹo sử dụng, hãy gọi:
+```bash
+./qk-help "Hiển thị tất cả các skill"
+```

package/bin/install.js

@@ -237,8 +237,20 @@ Nếu người dùng sử dụng tham số (argument), bạn BẮT BUỘC phải
         }
 
         if (fs.existsSync(ruleFilePath)) {
-          fs.appendFileSync(ruleFilePath, "\n\n" + writeContent);
-          console.log(`✅ Đã GHI THÊM cấu hình tự động vào file: ${ruleFilePath}`);
+          const existingContent = fs.readFileSync(ruleFilePath, 'utf8');
+          const marker = isGemini ? '<RULE[ai_skill_os]>' : '[Role]\nYou are an elite AI Software Engineer.';
+          const markerIndex = existingContent.indexOf(marker);
+          if (markerIndex !== -1) {
+            const before = existingContent.substring(0, markerIndex);
+            const after = existingContent.substring(markerIndex).split('\n').slice(isGemini ? 2 : 1).join('\n');
+            const lastMarkerEnd = after.indexOf(isGemini ? '</RULE[ai_skill_os]>' : '[Trigger Mechanism]');
+            const actualAfter = lastMarkerEnd !== -1 ? after.substring(lastMarkerEnd + (isGemini ? 19 : 18)).trimStart() : after;
+            fs.writeFileSync(ruleFilePath, before + writeContent.trimStart() + (actualAfter ? '\n' + actualAfter : '') + '\n');
+            console.log(`✅ Đã CẬP NHẬT cấu hình tự động trong file: ${ruleFilePath}`);
+          } else {
+            fs.appendFileSync(ruleFilePath, "\n\n" + writeContent);
+            console.log(`✅ Đã GHI THÊM cấu hình tự động vào file: ${ruleFilePath}`);
+          }
         } else {
           fs.writeFileSync(ruleFilePath, writeContent);
           console.log(`✅ Đã TẠO MỚI file cấu hình: ${ruleFilePath}`);

package/package.json

@@ -1,34 +1,44 @@
-{
-  "name": "ai-developer-skill-os",
-  "version": "3.1.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": {
-    "ai-developer-skill-os": "bin/install.js",
-    "ai-skill": "bin/install.js"
-  },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/phamquangkhanh2999/ai-developer-skill-os.git"
-  },
-  "keywords": [
-    "ai",
-    "claude",
-    "cursor",
-    "windsurf",
-    "skills",
-    "developer",
-    "agent",
-    "prompts",
-    "framework"
-  ],
-  "author": "Quang Khánh",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/phamquangkhanh2999/ai-developer-skill-os/issues"
-  },
-  "homepage": "https://github.com/phamquangkhanh2999/ai-developer-skill-os#readme"
-}
+{
+  "name": "ai-developer-skill-os",
+  "version": "3.1.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": {
+    "ai-developer-skill-os": "bin/install.js",
+    "ai-skill": "bin/install.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:registry": "vitest run --config vitest.config.js",
+    "lint": "echo \"No linter configured\" && exit 0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phamquangkhanh2999/ai-developer-skill-os.git"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "cursor",
+    "windsurf",
+    "skills",
+    "developer",
+    "agent",
+    "prompts",
+    "framework"
+  ],
+  "author": "Quang Khánh",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/phamquangkhanh2999/ai-developer-skill-os/issues"
+  },
+  "homepage": "https://github.com/phamquangkhanh2999/ai-developer-skill-os#readme",
+  "devDependencies": {
+    "vitest": "^2.1.0",
+    "fast-glob": "^3.3.0",
+    "gray-matter": "^4.0.0",
+    "js-yaml": "^4.1.0"
+  }
+}

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

@@ -1,9 +1,11 @@
 ---
 name: qk-access-policy
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Manage RBAC, ABAC, and security boundaries.
 category: security
+behavior: static-analysis
+intent: review-code
 priority: high
 tags: [security, rbac, auth, permissions]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
 > **Goal:** "Bảo vệ cổng" (Security Guard). Xác định xem người dùng có đủ thẩm quyền để truy cập vào một Component UI hoặc một Endpoint API hay không.
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Role Assessment):**
    - Identify the user roles (Guest, User, Admin, SuperAdmin).
 2. **Implement (Boundary Definition):**
@@ -28,13 +31,17 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
    - Ensure you didn't grant broad access by default.
 
 ## 🛡️ 2. Constraints & Rules
+
 - **Full Stack Protection:** Never hide UI elements without also securing the corresponding backend API.
 
 ## 🤝 3. Handoff Pipeline
+
 1. `validate`: Trigger `qk-validation-gate` to check for security flaws.
 2. `complete`: Generate the Access Control Report.
 
 ## 📝 4. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt.
+
 - **Tóm tắt (Summary):** Các role vừa được setup.
 - **Chi tiết (Changes):** UI và API nào đã được bảo vệ.

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

@@ -1,9 +1,11 @@
 ---
 name: qk-ai-builder
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Design AI Logic, Prompts, RAG pipelines, and Agents.
 category: ai
+behavior: development
+intent: implement-feature
 priority: medium
 tags: [ai, llm, prompt-engineering, rag, agents]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, design, implement, validate, complete]
 > **Goal:** "AI Engineer". Xây dựng các tính năng thông minh bằng LLM (Chatbot, RAG pipeline, Agent workflows).
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Task Breakdown):**
    - Determine the AI use case (Classification, Generation, Chat, Search).
 2. **Design (Prompt Engineering):**
@@ -29,13 +32,17 @@ pipeline: [analyze, design, implement, validate, complete]
    - Ensure API keys are not hardcoded.
 
 ## 🛡️ 2. Constraints & Rules
+
 - **JSON Parsing:** Always enforce JSON outputs if the AI response is consumed by the app, and handle parse errors.
 
 ## 🤝 3. Handoff Pipeline
+
 1. `validate`: Send to validation gate.
 2. `complete`: Output the AI Integration Report.
 
 ## 📝 4. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt.
+
 - **Tóm tắt (Summary):** Luồng AI đã thiết lập.
 - **Chi tiết (Changes):** Prompt và logic gọi API.

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

@@ -1,9 +1,11 @@
 ---
 name: qk-api-lifecycle
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Design, implement, and integrate API endpoints.
 category: engineering
+behavior: development
+intent: implement-feature
 priority: high
 tags: [api, backend, frontend-integration, endpoints]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
 > **Goal:** Quản lý toàn bộ vòng đời của một API, từ việc thiết kế Spec (Swagger/Types) cho đến khi Backend code xong và Frontend gọi thành công.
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Contract Definition):**
    - Read the user requirements.
    - Define the exact API contract (Request Body, Query Params, Response DTO) in TypeScript interfaces or OpenAPI spec.
@@ -34,10 +37,12 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
    - Ensure loading states are managed on the frontend.
 
 ## 🛡️ 2. Constraints & Rules
+
 - **No Hardcoded URLs:** Never hardcode `http://localhost:3000` inside frontend components. Always use environment variables (`process.env.API_URL`).
 - **Separation of Concerns:** Do NOT write `fetch` or `axios.get` directly inside a React UI component. Extract it to a custom hook or an API service file.
 
 ## 🌳 3. Decision Tree
+
 ```text
 Is this a Backend or Frontend task?
   ├── BACKEND → Does the API need Database access?
@@ -49,12 +54,15 @@ Is this a Backend or Frontend task?
 ```
 
 ## 🤝 4. Handoff Pipeline
+
 1. `engineering-standard`: Verify API naming conventions (e.g., `GET /users` instead of `POST /getUsers`).
 2. `validate`: Run API tests and Type-checks.
 3. `complete`: Generate the final report.
 
 ## 📝 5. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt. Sử dụng template chuẩn của hệ thống:
+
 - **Tóm tắt (Summary):** Các endpoint đã tạo hoặc tích hợp.
 - **Chi tiết (Changes):** File nào chứa logic API.
 - **Kiến trúc (Reasoning):** Lý do chọn thư viện hoặc cách bắt lỗi (Error handling).

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

@@ -1,6 +1,6 @@
 ---
 name: qk-bug-resolution
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Fix bugs and prevent regressions.
 category: engineering
@@ -21,6 +21,7 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
 > **Goal:** Định vị nguyên nhân, sửa lỗi triệt để, và đảm bảo lỗi không bị lặp lại (Regression Prevention).
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Root Cause Analysis):**
    - Read the provided error log or bug description.
    - Trace the error to the exact file and line of code.
@@ -36,11 +37,13 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
    - Ensure backward compatibility.
 
 ## 🛡️ 3. Constraints & Rules
+
 - **No Guesses:** Do not assume the shape of an API response. Print it or read the type definitions first.
 - **Minimal Fix:** Always prefer a 1-line fix over a 100-line refactor, unless the architecture is fundamentally broken.
 - **Clean Up:** Remove any `console.log()` or debugger statements introduced during the debugging process.
 
 ## 🌳 3. Decision Tree
+
 ```text
 Is there a Stack Trace?
   ├── YES → Use grep_search to find the exact file and line number.
@@ -52,13 +55,17 @@ Is the bug related to State/Re-rendering?
 ```
 
 ## 🤝 4. Handoff Pipeline
+
 After implementing the fix, map to the pipeline:
+
 1. `engineering-standard`: Ensure the fix follows naming and architecture rules.
 2. `validate`: Run linters and tests (via `qk-validation-gate` equivalent).
 3. `complete`: Output the final report.
 
 ## 📝 5. Output Format
+
 Vui lòng sử dụng template `templates/bug-report.md` (Báo Cáo Xử Lý Lỗi) để phản hồi lại cho người dùng bằng Tiếng Việt. Nội dung bao gồm:
+
 - Summary
 - Changes
 - Root Cause