ai-developer-skill-os 9.3.1 → 10.2.0

package/.agents/skills/qk-db-optimizer/SKILL.md

@@ -1,210 +0,0 @@
----
-# ── Identity ───────────────────────────────────────────────
-name: qk-db-optimizer
-version: 9.2.0
-status: stable
-description: "Tối ưu hiệu năng Database dựa trên bằng chứng kỹ thuật: phân tích EXPLAIN/ANALYZE, phát hiện N+1 queries, thiết kế Composite/Partial Index, refactor câu truy vấn chậm. Dùng skill này khi user nhắc đến: tối ưu query, query chậm, optimize db, thêm index, explain, slow query, n+1 query, lag database — kể cả khi chỉ nói 'câu SQL này chạy mất 5 giây'."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V9: Classification ─────────────────────────────────────
-type: utility
-
-intent:
-  - database-optimization
-  - performance-tuning
-
-complexity:
-  level: high
-  criteria:
-    files_affected: "1-5"
-    has_behavior_change: false
-    has_external_dependency: true
-    has_breaking_change: false
-
-triggers:
-  - "tối ưu query"
-  - "query chậm"
-  - "optimize db"
-  - "thêm index"
-  - "explain"
-  - "slow query"
-  - "n+1 query"
-  - "lag database"
-
-
-# ── V8: References ─────────────────────────────────────────
-workflow: refactor
-
-rules:
-  - global
-  - coding
-
-tools:
-  - filesystem
-  - terminal
-
-related_skills:
-  - qk-data-lifecycle
-  - qk-refactor
-
-knowledge_scope:
-  owns:
-    - database-performance
-    - query-optimization
-    - index-engineering
-  references:
-    - architecture
-    - anti-patterns
-
-# ── V8: Verification ───────────────────────────────────────
-verification:
-  required: true
-  strategy: performance-regression
-
-selection:
-  priority: medium
-  confidence_threshold: 0.85
-
-examples: []
-learnings: []
-
-# ── V7 Runtime ─────────────────────────────────────────────
-execution_mode: deterministic
-cost: medium
-latency: medium
-risk: medium
-side_effects: edit_files
-produces: [code, report]
-consumes: [query-log, source-code]
-
-token_budget:
-  max_files_read: 5
-  max_lines_per_read: 150
-  max_shell_commands: 2
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-
-# qk-db-optimizer — Evidence-Based Database Performance Tuner
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-Chịu trách nhiệm chẩn đoán và khắc phục điểm nghẽn hiệu năng cơ sở dữ liệu dựa trên **bằng chứng đo lường thực tế**: `EXPLAIN (ANALYZE, BUFFERS)` → tìm root cause → đề xuất Index / Query Rewrite — **tuyệt đối không đoán mò**.
-
----
-
-## Preconditions
-
-Trước khi đề xuất tối ưu, AI BẮT BUỘC xác nhận:
-
-- [ ] Đoạn query cụ thể (SQL thô hoặc câu gọi ORM) đang bị chậm.
-- [ ] Schema định nghĩa bảng và **danh sách index hiện có** trên các cột liên quan.
-- [ ] Output `EXPLAIN` hoặc `EXPLAIN ANALYZE` (nếu môi trường cho phép chạy query).
-- [ ] Quy mô dữ liệu ước tính (e.g. bảng có 1.000 rows hay 50.000.000 rows).
-
-*Nếu user yêu cầu "tối ưu database" mà không cung cấp query cụ thể hoặc slow log:*
-→ **EXIT: BLOCKED**
-→ Phản hồi: "Vui lòng cung cấp câu query bị chậm hoặc output log EXPLAIN để phân tích chính xác."
-
----
-
-## Scope
-
-✅ Skill này làm:
-- Phân tích Execution Plan: Xác định `Seq Scan` trên bảng lớn, `Nested Loop` kém hiệu quả, `Temporary disk spill`, hoặc `Filter cost` cao.
-- Phát hiện và giải quyết triệt để **N+1 queries** trong ORM (Prisma, Drizzle, Hibernate, ActiveRecord).
-- Thiết kế Index chính xác: Composite Index (tuân thủ quy tắc Left-to-Right prefix), Partial Index (lọc `WHERE is_deleted = false`), Covering Index (`INCLUDE`).
-- Tái cấu trúc câu truy vấn (Query rewrite): Chuyển `OFFSET` lớn sang Keyset Pagination (Cursor-based), thay `NOT IN` bằng `NOT EXISTS` hoặc `LEFT JOIN ... IS NULL`.
-- Báo cáo định lượng trước và sau (Before / After Cost & Execution Time).
-
-❌ Skill này KHÔNG làm:
-- Thêm index bừa bãi vào mọi cột (làm chậm `INSERT`, `UPDATE`, tăng dung lượng đĩa).
-- Tự ý thay đổi cấu trúc bảng hoặc drop cột (thuộc `qk-data-lifecycle`).
-- Can thiệp phần cứng DB hoặc tune memory server nếu không có file cấu hình repo.
-
----
-
-## Execution Steps
-
-### Step 1 — Thu thập Query & Phân tích EXPLAIN Plan
-```
-Inputs:  Slow query SQL/ORM, Schema & Existing Indexes
-Actions:
-  - Đọc câu query: xác định predicates (WHERE, JOIN, ORDER BY, GROUP BY).
-  - Đọc EXPLAIN output (nếu có):
-    - Tìm Node có `Cost` cao nhất.
-    - Kiểm tra `Rows Removed by Filter` (dấu hiệu thiếu index).
-    - Kiểm tra Sort method (in-memory quicksort hay external merge on disk).
-```
-
-### Step 2 — Chẩn đoán Root Cause
-```
-Xác định vấn đề cốt lõi:
-  - Missing Index: Cột lọc không có index dẫn tới Full Table Scan.
-  - Sub-optimal Index: Có index nhưng sai thứ tự cột trong Composite Index.
-  - Implicit Type Casting: So sánh varchar với int làm database vô hiệu hóa index.
-  - N+1 Query: Gọi loop query con thay vì batch load.
-  - Expensive Pagination: `OFFSET 100000` quét qua 100.000 dòng rồi vứt bỏ.
-```
-
-### Step 3 — Thiết kế Giải pháp Tối ưu
-```
-Actions:
-  - Chiến lược Index:
-    - Composite Index: Đặt cột equality (`=`) trước, cột range (`<`, `>`, `BETWEEN`) sau.
-    - Partial Index: Khi chỉ query tập con dữ liệu (VD: `WHERE status = 'PENDING'`).
-  - Chiến lược Query Rewrite:
-    - Viết lại sang Cursor Pagination (`WHERE id > :last_id LIMIT 20`).
-    - Dùng CTE hoặc Window functions thay cho multiple subqueries lặp lại.
-  - Chiến lược ORM: Thêm `include`/`select` cụ thể, tránh `SELECT *`, áp dụng batch loader.
-```
-
-### Step 4 — Verification & So sánh định lượng
-```
-Actions:
-  - Đối chiếu Expected Cost trước và sau tối ưu:
-    Before: Seq Scan on orders (cost=0.00..45210.00 rows=1200000)
-    After:  Index Scan using idx_orders_customer_created (cost=0.43..8.45 rows=20)
-  - Đảm bảo câu query sau khi rewrite trả về đúng 100% dữ liệu như câu query cũ.
-```
-
----
-
-## Prompt Template
-
-```
-DB Engine:    [PostgreSQL / MySQL / SQLite / MongoDB]
-Slow Query:   [Câu SQL hoặc đoạn code ORM cần tối ưu]
-Schema:       [Định nghĩa bảng và index hiện tại]
-Triệu chứng:  [Chạy mất bao lâu / Execution Plan nếu có]
-Volume:       [Số lượng bản ghi trong các bảng liên quan]
-```
-
-### Ví dụ theo Stack:
-
-**PostgreSQL (Composite Index & Keyset Pagination)**
-```
-DB Engine:    PostgreSQL 15
-Slow Query:   SELECT * FROM orders WHERE customer_id = 123 AND status = 'COMPLETED' ORDER BY created_at DESC LIMIT 20 OFFSET 50000;
-Volume:       Bảng orders có 10 triệu records. Hiện có index trên (customer_id).
-```
-→ AI chẩn đoán:
-  1. Offset 50.000 buộc engine quét qua 50.000 index entries.
-  2. Index hiện tại thiếu `status` và `created_at`.
-→ AI giải pháp:
-  1. Đề xuất Composite Index: `CREATE INDEX CONCURRENTLY idx_orders_cust_stat_created ON orders (customer_id, status, created_at DESC);`
-  2. Rewrite sang Cursor Pagination: `SELECT id, total, created_at FROM orders WHERE customer_id = 123 AND status = 'COMPLETED' AND created_at < :last_created_at ORDER BY created_at DESC LIMIT 20;`
-
-**Prisma ORM (Khắc phục N+1 Query)**
-```
-ORM:          Prisma
-Code:         
-  const users = await prisma.user.findMany({ take: 50 });
-  for (const user of users) {
-    user.posts = await prisma.post.findMany({ where: { authorId: user.id } });
-  }
-```
-→ AI sửa thành single query batching với eager load:
-  `const users = await prisma.user.findMany({ take: 50, include: { posts: { select: { id: true, title: true } } } });`
-

package/.agents/skills/qk-db-optimizer/capability.yaml

@@ -1,22 +0,0 @@
-# Auto-generated from SKILL.md frontmatter
-schema_version: 1
-id: "qk-db-optimizer"
-version: "9.1.0"
-description: "Tối ưu Database dựa trên bằng chứng: EXPLAIN → phân tích → index/join — không đoán mò."
-tools:
-  - "filesystem"
-  - "terminal"
-knowledge:
-  owns:
-    - "database-performance"
-    - "query-optimization"
-  references:
-    - "architecture"
-    - "anti-patterns"
-eval:
-  scorecard: "evals/scorecard.yaml"
-decision_boundary:
-  owns:
-    - "qk-db-optimizer"
-  does_not_own: []
-  conflicts_with: []

package/.agents/skills/qk-db-optimizer/evals/scorecard.yaml

@@ -1,28 +0,0 @@
-name: qk-db-optimizer-eval
-description: Đánh giá chất lượng tối ưu hóa Database
-version: 9.1.0
-threshold: 85 # Yêu cầu dựa trên bằng chứng, không đoán mò
-
-metrics:
-  - id: evidence_based_analysis
-    name: Phân tích dựa trên bằng chứng (EXPLAIN)
-    description: Agent có chạy EXPLAIN/Analyze trước khi thêm Index/Sửa query không?
-    weight: 40
-    criteria:
-      - Bắt buộc phải có thông tin Slow query log hoặc chạy EXPLAIN trước khi hành động (20đ)
-      - Phân tích đúng nguyên nhân từ Plan (vd: Seq Scan, Nested Loop, N+1) (20đ)
-
-  - id: optimal_solution
-    name: Đưa ra giải pháp tối ưu
-    description: Giải pháp đưa ra có giải quyết triệt để và an toàn không?
-    weight: 35
-    criteria:
-      - Không tạo các index dư thừa (overlapping) (15đ)
-      - Xử lý triệt để bài toán N+1 bằng JOIN hoặc DataLoader theo đúng chuẩn dự án (20đ)
-
-  - id: verification
-    name: Kiểm chứng cải thiện (Verification)
-    description: Agent có cố gắng đo lường lại sau khi sửa không?
-    weight: 25
-    criteria:
-      - Đối chiếu/ước lượng mức độ cải thiện sau khi áp dụng giải pháp (25đ)

package/.agents/skills/qk-design-system-engineering/SKILL.md

@@ -1,193 +0,0 @@
----
-# ── Identity ───────────────────────────────────────────────
-name: qk-design-system-engineering
-version: 9.2.0
-status: experimental
-description: "Quản trị hệ thống thiết kế (Định nghĩa quy tắc hệ thống, tokens, các biến thể component). Dùng skill này khi user nhắc đến: định nghĩa design system, cấu trúc token, quy chuẩn ui, design tokens, component variants, quản trị thiết kế — kể cả khi chỉ nói 'chuẩn hóa lại cách đặt tên tokens và variants của nút'."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V9: Classification ─────────────────────────────────────
-type: capability
-
-intent:
-  - design-system
-  - tokens
-  - component-library
-  - accessibility
-
-complexity:
-  level: medium
-  criteria:
-    files_affected: "1-5"
-    has_behavior_change: true
-    has_external_dependency: false
-    has_breaking_change: false
-
-triggers:
-  - "định nghĩa design system"
-  - "cấu trúc token"
-  - "quy chuẩn ui"
-  - "design tokens"
-  - "component variants"
-  - "quản trị thiết kế"
-
-
-# ── V8: References ─────────────────────────────────────────
-workflow: feature-delivery
-
-rules:
-  - global
-  - coding
-
-tools:
-  - filesystem
-
-related_skills:
-  - qk-ui-system-builder
-  - qk-ui-builder
-
-knowledge_scope:
-  domain:
-    - design-system
-    - tokens
-  concepts:
-    - visual-consistency
-    - components-rules
-  references:
-    - architecture
-    - anti-patterns
-
-decision_boundary:
-  owns:
-    - tokens
-    - components rules
-    - design governance
-  does_not_own:
-    - page implementation
-    - business logic
-  conflicts_with:
-    - qk-ui-system-builder
-
-knowledge_dependencies:
-  - design-intelligence
-  - accessibility-guidelines
-  - component-patterns
-
-# ── V8: Verification ───────────────────────────────────────
-verification:
-  required: true
-  strategy: feature
-
-selection:
-  priority: medium
-  confidence_threshold: 0.80
-
-examples: []
-learnings: []
-
-# ── V7 Runtime ─────────────────────────────────────────────
-execution_mode: deterministic
-cost: medium
-latency: medium
-risk: low
-side_effects: read_only
-produces: [report, tokens_definition]
-consumes: [user-description]
-
-token_budget:
-  max_files_read: 5
-  max_lines_per_read: 150
-  max_shell_commands: 0
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-
-# qk-design-system-engineering — Design System Governance & Architecture
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-Chịu trách nhiệm quản trị kiến trúc hệ thống thiết kế (Design System Governance), định nghĩa các tầng abstraction của Token (Global → Semantic → Component-scoped), chuẩn hóa Component API (Props, Variants theo CVA - Class Variance Authority) và thiết lập quy tắc mở rộng dài hạn.
-
----
-
-## Preconditions
-
-Trước khi định nghĩa quy chuẩn design system, AI BẮT BUỘC kiểm tra:
-
-- [ ] Xác định triết lý thiết kế và framework UI hiện tại (React, Vue, Web Components) từ `.agents/DEV_PROFILE.md`.
-- [ ] Kiểm tra hệ thống tokens và component library hiện hữu (nếu có).
-- [ ] Xác định phương pháp quản lý variant (CVA, Stitches, Vanilla CSS, Tailwind).
-- [ ] Nếu có sự xung đột giữa các biến thể hoặc phá vỡ tính nhất quán cốt lõi:
-  → **EXIT: BLOCKED**
-  → Báo cáo user ma trận xung đột và đề xuất nguyên tắc chuẩn hóa trước khi ban hành spec.
-
----
-
-## Scope
-
-✅ Skill này làm:
-- Thiết kế hệ thống phân cấp Tokens 3 tầng:
-  1. Primitive / Global Tokens: Giá trị thô (`blue-500: #3b82f6`, `spacing-4: 16px`).
-  2. Semantic / System Tokens: Ý nghĩa sử dụng (`color-intent-primary`, `surface-background-elevated`).
-  3. Component Tokens: Riêng cho component (`button-primary-bg`, `card-border-radius`).
-- Định nghĩa Component Variant Matrix (Primary, Secondary, Outline, Ghost, Destructive; Sizes: sm, md, lg).
-- Thiết lập quy tắc kế thừa (Design Governance) và tài liệu hóa `DESIGN.md`.
-- Hướng dẫn cấu trúc props component theo hướng composable (Compound Components).
-
-❌ Skill này KHÔNG làm:
-- Tự động dựng giao diện các màn hình nghiệp vụ cụ thể (→ `qk-ui-builder`).
-- Trực tiếp generate các file cấu hình build như tailwind.config (→ `qk-ui-system-builder`).
-- Viết API hoặc truy vấn cơ sở dữ liệu.
-
----
-
-## Execution Steps
-
-### Step 1 — Token Hierarchy & Taxonomy Design
-```
-Inputs:  Yêu cầu quy chuẩn, Brand Identity
-Actions:
-  - Thiết lập quy ước đặt tên (Naming convention: category-context-property-variant-state).
-  - Phân tách rạch ròi 3 tầng: Primitive → Semantic → Component.
-  - Đảm bảo tính linh hoạt khi thay đổi chủ đề (Theming / Multi-brand).
-Output: Token Taxonomy Specification
-```
-
-### Step 2 — Component Variant & API Matrix
-```
-Inputs:  Token Taxonomy, Target UI Components (Button, Input, Card, Modal)
-Actions:
-  - Định nghĩa ma trận biến thể (Variants: intent, size, state).
-  - Soạn thảo hợp đồng TypeScript Props cho từng component chuẩn (sử dụng Class Variance Authority).
-Output: Component API Contracts
-```
-
-### Step 3 — Governance & Documentation
-```
-Inputs:  Taxonomy & Component Contracts
-Actions:
-  - Cập nhật hoặc khởi tạo file `DESIGN.md` ở root dự án.
-  - Viết hướng dẫn sử dụng (Do's and Don'ts) cho các lập trình viên khác tuân theo.
-Output: DESIGN.md & Usage Guide
-```
-
-### Step 4 — Verification & Peer Review
-```
-Inputs:  Specification Draft
-Actions:
-  - Kiểm tra tính tương thích ngược với các component cũ đang chạy.
-  - Xác nhận tính khả thi với UI developer.
-Exit: SUCCESS
-```
-
----
-
-## Prompt Template
-
-```
-Hệ thống thiết kế: [Tên design system hoặc đối tượng cần quy chuẩn]
-Mục tiêu:          [Định nghĩa cấu trúc token 3 tầng / Chuẩn hóa variants cho Button & Input]
-Công nghệ:         [React + Tailwind + CVA / Vue + SCSS / ...]
-Quy tắc hiện tại:  [Tài liệu DESIGN.md cũ hoặc mô tả cách team đang dùng]
-```

package/.agents/skills/qk-design-system-engineering/capability.yaml

@@ -1,25 +0,0 @@
-# Auto-generated from SKILL.md frontmatter
-schema_version: 1
-id: "qk-design-system-engineering"
-version: "9.1.0"
-description: "Quản trị hệ thống thiết kế (Định nghĩa quy tắc hệ thống, tokens, các biến thể component)."
-tools:
-  - "filesystem"
-knowledge:
-  owns:
-    - "qk-design-system-engineering"
-  references:
-    - "architecture"
-    - "anti-patterns"
-eval:
-  scorecard: "evals/scorecard.yaml"
-decision_boundary:
-  owns:
-    - "tokens"
-    - "components rules"
-    - "design governance"
-  does_not_own:
-    - "page implementation"
-    - "business logic"
-  conflicts_with:
-    - "qk-ui-system-builder"

package/.agents/skills/qk-design-system-engineering/evals/scorecard.yaml

@@ -1,27 +0,0 @@
-name: qk-design-system-engineering-eval
-description: Đánh giá chất lượng quản trị hệ thống thiết kế (Design System)
-version: 9.1.0
-threshold: 85 # Đảm bảo sự nhất quán và ngăn chặn UI Slop từ gốc
-
-metrics:
-  - id: token_and_rules_definition
-    name: Định nghĩa Token và Quy tắc
-    description: Agent có thiết lập hệ thống token rõ ràng và nhất quán không?
-    weight: 40
-    criteria:
-      - Định nghĩa đầy đủ các quy tắc cho spacing, colors, typography (20đ)
-      - Ngăn chặn triệt để UI Slop bằng cách không cung cấp các token sai chuẩn (vd: độ tương phản quá thấp, font quá bé) (20đ)
-
-  - id: a11y_compliance
-    name: Tuân thủ Accessibility (A11y)
-    description: Các quy chuẩn có tính đến khả năng truy cập không?
-    weight: 30
-    criteria:
-      - Thiết lập quy tắc A11y ngay từ cấp độ Token (30đ)
-
-  - id: boundary_respect
-    name: Tôn trọng ranh giới (Decision Boundary)
-    description: Agent có giữ đúng vai trò Governance mà không lấn sân sang Implementation không?
-    weight: 30
-    criteria:
-      - Chỉ tập trung định nghĩa (Governance), KHÔNG thay thế việc viết UI code trực tiếp (nhường lại cho qk-ui-system-builder) (30đ)