heraspec 0.1.13 → 0.1.15

package/dist/core/templates/skills/sourcecode-analyzer-skill.vi.md

@@ -0,0 +1,210 @@
+---
+name: sourcecode-analyzer
+description: Phân tích sâu source code theo mô hình đa agent cho kiến trúc, coding style, design pattern, ngôn ngữ, framework, thư viện, cấu trúc module, extension point và khả năng tích hợp. Sử dụng khi agent cần hiểu tối đa codebase trước khi lập kế hoạch feature, refactor, integration, migration, audit hoặc documentation.
+projectType: all
+---
+
+# Source Code Analyzer (Tiếng Việt)
+
+## Mục tiêu
+Tạo báo cáo phân tích kiến trúc và khả năng tích hợp có độ tin cậy cao, dựa trên bằng chứng trực tiếp từ source code.
+
+## Phạm vi
+Phân tích:
+- Ranh giới kiến trúc và phân lớp
+- Stack framework/CMS/runtime và dependency
+- Coding style và conventions
+- Modules/themes/plugins và extension points
+- API surfaces (REST/GraphQL/webhooks/events/CLI/jobs)
+- Data layer và mô hình cấu hình
+- Bảo mật và vận hành
+- Khả năng tích hợp và các ràng buộc
+
+Không:
+- Sửa business logic
+- Chạy lệnh hủy hoại
+- Cài đặt hoặc nâng cấp dependency nếu chưa được yêu cầu
+
+## Đầu ra bắt buộc
+Ghi báo cáo vào `_analytics/structure.md` (hoặc đường dẫn do người dùng chỉ định), đúng thứ tự section như trong `Report Template`.
+
+## Quy tắc bằng chứng
+Mỗi nhận định quan trọng phải:
+- Có bằng chứng cụ thể (đường dẫn file, symbol/class/function, tóm tắt snippet ngắn)
+- Gán mức độ tin cậy `High`, `Medium` hoặc `Low`
+- Gán loại nhận định:
+  - `Observed`: Xác nhận trực tiếp trong source
+  - `Inferred`: Suy ra từ nhiều quan sát đã xác thực
+  - `Assumed`: Giả định hợp lý nhưng chưa xác thực
+
+Không đưa ra kết luận không có cơ sở.
+
+## Điều phối đa agent
+Nếu có subagents, tách song song 4 lane:
+
+1. `Architecture lane`
+- Lập bản đồ topology thư mục, layers, modules/plugins/themes
+- Xác định entry points và hướng phụ thuộc
+
+2. `Style and design lane`
+- Xác định naming conventions, folder conventions, patterns, anti-patterns
+- Xác định coding standards và quality gates (lint/test/static check)
+
+3. `Dependency and runtime lane`
+- Xác định ngôn ngữ/runtime/framework versions
+- Inventory thư viện quan trọng và vai trò
+
+4. `Integration and security lane`
+- Lập bản đồ APIs, events/hooks, queues, cron/jobs, webhooks, third-party SDKs
+- Đánh giá authN/authZ, input validation, secrets handling và attack surface
+
+Nhiệm vụ của coordinator:
+- Chuẩn hóa output của các lane
+- Xử lý mâu thuẫn giữa các lane
+- Tổng hợp 1 báo cáo cuối cùng có bằng chứng và confidence
+
+Nếu không có subagents, chạy tuần tự theo cùng quy trình lane.
+
+## Workflow
+
+### Step 0 — Knowledge Lookup (Tra cứu kiến thức sẵn có)
+Trước khi phân tích toàn bộ, kiểm tra knowledge base đã có sẵn:
+
+1. Kiểm tra `heraspec/knowledge/index.json` có tồn tại trong dự án không
+2. Đọc tất cả entries và đối chiếu với dự án hiện tại:
+   - Với signal `file-contains`: kiểm tra file tồn tại VÀ chứa chuỗi chỉ định
+   - Với signal `directory-exists`: kiểm tra thư mục tồn tại
+   - Mỗi signal khớp = +1 điểm match score
+3. Nếu `score >= minMatchScore` cho bất kỳ entry nào:
+   - Đọc `structure.md` tương ứng từ `heraspec/knowledge/<knowledgePath>/`
+   - Sử dụng làm **baseline phân tích** — bỏ qua Steps 1-8 cho các section đã có
+   - Chỉ tập trung vào **khác biệt riêng dự án** (custom plugins, configs, .env, custom code)
+   - Đầu ra: gộp baseline knowledge + delta riêng dự án thành báo cáo cuối
+4. Kiểm tra thêm `heraspec/knowledge/custom/index.json` cho knowledge riêng dự án
+5. Nếu không match: tiến hành phân tích đầy đủ từ Step 1
+
+Phân cấp knowledge: `heraspec/knowledge/<category>/<runtime>/<framework>/<cms>/`
+
+### Step 1 - Baseline Metadata
+Đọc metadata ở root trước:
+- `composer.json`, `composer.lock`
+- `package.json`, lockfiles
+- `docker*`, `Makefile`, CI configs
+- `.env.example`, config directories
+
+Thu thập:
+- Language/runtime versions
+- Framework/CMS versions
+- Build và deployment model
+
+### Step 2 - Repository Topology
+Lập bản đồ thư mục chính và trách nhiệm:
+- Core/domain/infrastructure boundaries
+- Kiến trúc plugin/module/theme
+- Shared libraries và cross-cutting concerns
+- Bootstrapping và entry points
+
+### Step 3 - Architectural Patterns
+Xác định và đánh giá:
+- Layered/hexagonal/modular/monolith/microservice patterns
+- Sử dụng service container/DI
+- Event-driven flows
+- Điểm nóng coupling và boundaries
+
+### Step 4 - Coding Style and Design Conventions
+Kiểm tra các file đại diện mỗi layer:
+- Naming conventions (class/function/file)
+- Folder và namespace strategy
+- Error handling patterns
+- Test style và coverage signals
+- Static analysis/lint/format rules
+
+### Step 5 - Extension Model
+Lập bản đồ cơ chế mở rộng:
+- Hooks/filters/events/listeners
+- Đăng ký module/plugin và lifecycle
+- Theme/template override model
+- Custom providers, middleware, policies
+
+### Step 6 - API and Interaction Surfaces
+Thống kê interfaces nội bộ và bên ngoài:
+- REST/GraphQL routes và controllers
+- Command bus, queues, jobs, schedulers
+- CLI commands, webhooks, callbacks
+- Public SDK/service abstractions
+
+### Step 7 - Data and State
+Phân tích:
+- ORM/data access strategy
+- Migration và seeding patterns
+- Cache/session/queue drivers
+- Transaction boundaries và consistency risks
+
+### Step 8 - Security and Compliance Signals
+Kiểm tra:
+- Authentication và authorization model
+- CSRF/XSS/SQLi protections
+- Secrets và credential handling
+- Rate limiting và abuse protection
+- Audit logging và trace các thao tác nhạy cảm
+
+### Step 9 - Integration Readiness
+Đánh giá khả năng tích hợp theo:
+- Data integration
+- API integration
+- Event integration
+- UI/theme integration
+- Deployment/infra integration
+
+Mỗi loại tích hợp cần tóm tắt:
+- Entry points hiện có
+- Adapters cần bổ sung
+- Độ phức tạp ước tính (`Low`/`Medium`/`High`)
+- Rủi ro chính và hướng giảm thiểu
+
+### Step 10 - Synthesis
+Tổng hợp findings vào một báo cáo, ưu tiên kết luận có bằng chứng, và liệt kê unknowns đang cần xác minh.
+
+## Report Template
+
+Sử dụng đúng thứ tự section sau trong `_analytics/structure.md`:
+
+1. `Executive Summary`
+2. `Technology Profile`
+3. `Repository Topology`
+4. `Architecture and Dependency Flow`
+5. `Coding Style and Conventions`
+6. `Extension Points (Modules/Themes/Plugins/Hooks)`
+7. `API and Interaction Surfaces`
+8. `Data Model and State Management`
+9. `Security Posture`
+10. `Integration Capability Matrix`
+11. `Strengths, Weaknesses, Risks`
+12. `Top 10 Evidence Items`
+13. `Unknowns and Verification Plan`
+14. `Recommended Next Actions (30/60/90 day)`
+
+## Integration Capability Matrix Format
+
+Mỗi integration domain là 1 dòng:
+
+| Domain | Entry Points | Required Adapters | Complexity | Risks | Confidence |
+|---|---|---|---|---|---|
+
+Bắt buộc gồm:
+- External APIs
+- Authentication/SSO
+- Payment
+- Messaging/Queue
+- Storage/CDN
+- Observability
+- Admin/UI customization
+- Content/data migration
+
+## Completion Checklist
+Chỉ kết thúc skill khi đủ các điều kiện:
+- Report tồn tại ở đường dẫn mục tiêu
+- Mỗi nhận định quan trọng đều có bằng chứng
+- Giả định được đánh dấu rõ ràng
+- Integration matrix đầy đủ
+- Top risks có hướng giảm thiểu đề xuất

package/dist/core/templates/skills/spec-writer/skill.md

@@ -0,0 +1,61 @@
+# Skill: Specification Writing (Cross-Cutting)
+
+## Purpose
+
+Write and refine high-quality functional/technical specifications, user stories, and delta specs for consumption by AI agents.
+
+## When to Use
+
+- When starting a new feature change (Step 1 of the HeraSpec workflow)
+- When converting high-level business ideas into structured technical specs
+- When refining delta specs during parallel merge validation
+
+## Step-by-Step Process
+
+### Step 1: Define User Story & Scenarios
+- Structure the core requirement as a User Story (As a... I want to... So that...)
+- Formulate behavioral scenarios using GIVEN-WHEN-THEN syntax (Gherkin style)
+- Define happy paths, error paths, and edge cases
+
+### Step 2: Structure metadata
+- Specify target components, domains, and technical stacks
+- Verify requirements match the architectural conventions defined in `project.md`
+
+### Step-3: Write Delta Spec
+- Segment new, modified, and removed requirements clearly:
+  - `## ADDED Requirements`
+  - `## MODIFIED Requirements` (must specify the exact Before vs. After states)
+  - `## REMOVED Requirements`
+
+## Required Input
+
+- Business requirement description or user prompt
+- Technical stack metadata from `project.md`
+
+## Expected Output
+
+- Clean markdown specification following the HeraSpec format
+- Complete Delta Spec with GIVEN-WHEN-THEN scenarios
+
+## Tone & Rules
+
+- Be extremely precise. Avoid ambiguous language like "user-friendly" or "fast".
+- Always define exact failure states (e.g. "returns 401 Unauthorized" instead of "shows error").
+- Scenarios MUST be testable and actionable.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to format the specifications into product manuals.
+- **suggestion**: Use to identify gaps in existing specs.

package/dist/core/templates/skills/spec-writer/skill.vi.md

@@ -0,0 +1,61 @@
+# Kỹ năng: Viết Đặc tả (Specification Writing) (Cross-Cutting)
+
+## Mục đích
+
+Viết và tinh chỉnh các đặc tả chức năng/kỹ thuật chất lượng cao, các user stories và các delta specs để các AI agent có thể đọc hiểu và thực thi hiệu quả.
+
+## Khi nào sử dụng
+
+- Khi bắt đầu tạo một Change mới (Bước 1 của quy trình HeraSpec)
+- Khi chuyển đổi các ý tưởng nghiệp vụ mức cao thành tài liệu spec có cấu trúc kỹ thuật
+- Khi tinh chỉnh delta specs trong quá trình giải quyết xung đột song song (parallel merge)
+
+## Quy trình từng bước
+
+### Bước 1: Định nghĩa User Story & Scenarios
+- Cấu trúc yêu cầu cốt lõi dưới dạng User Story (Với vai trò là... Tôi muốn... Để...)
+- Xây dựng các kịch bản hành vi (scenarios) sử dụng cú pháp GIVEN-WHEN-THEN (phong cách Gherkin)
+- Định nghĩa rõ luồng xử lý thành công (happy path), luồng lỗi (error path) và trường hợp biên (edge cases)
+
+### Bước 2: Cấu trúc phần Meta
+- Chỉ định rõ các component mục tiêu, domain và technical stack
+- Xác minh các yêu cầu phải khớp với quy ước kiến trúc được định nghĩa trong `project.md`
+
+### Bước 3: Viết Delta Spec
+- Phân đoạn rõ ràng các yêu cầu mới, sửa đổi và loại bỏ:
+  - `## ADDED Requirements`
+  - `## MODIFIED Requirements` (phải nêu rõ trạng thái Trước đây (Before) vs. Bây giờ (After))
+  - `## REMOVED Requirements`
+
+## Input yêu cầu
+
+- Mô tả yêu cầu nghiệp vụ hoặc prompt yêu cầu từ người dùng
+- Thông tin về tech stack lấy từ `project.md`
+
+## Output mong đợi
+
+- File đặc tả markdown sạch sẽ tuân thủ đúng định dạng của HeraSpec
+- File Delta Spec hoàn chỉnh với các kịch bản GIVEN-WHEN-THEN
+
+## Giọng điệu & Quy tắc
+
+- Cực kỳ chính xác. Tránh các từ ngữ mơ hồ như "thân thiện với người dùng" hoặc "nhanh chóng".
+- Luôn định nghĩa rõ các trạng thái lỗi cụ thể (ví dụ: "trả về lỗi 401 Unauthorized" thay vị "hiển thị lỗi").
+- Các kịch bản (scenarios) BẮT BUỘC phải kiểm thử được và có thể triển khai được.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Dùng để định dạng các đặc tả kỹ thuật thành hướng dẫn sản phẩm.
+- **suggestion**: Dùng để phát hiện các lỗ hổng trong các spec hiện có.

package/dist/core/templates/skills/spec-writer-skill.md

@@ -0,0 +1,61 @@
+# Skill: Specification Writing (Cross-Cutting)
+
+## Purpose
+
+Write and refine high-quality functional/technical specifications, user stories, and delta specs for consumption by AI agents.
+
+## When to Use
+
+- When starting a new feature change (Step 1 of the HeraSpec workflow)
+- When converting high-level business ideas into structured technical specs
+- When refining delta specs during parallel merge validation
+
+## Step-by-Step Process
+
+### Step 1: Define User Story & Scenarios
+- Structure the core requirement as a User Story (As a... I want to... So that...)
+- Formulate behavioral scenarios using GIVEN-WHEN-THEN syntax (Gherkin style)
+- Define happy paths, error paths, and edge cases
+
+### Step 2: Structure metadata
+- Specify target components, domains, and technical stacks
+- Verify requirements match the architectural conventions defined in `project.md`
+
+### Step-3: Write Delta Spec
+- Segment new, modified, and removed requirements clearly:
+  - `## ADDED Requirements`
+  - `## MODIFIED Requirements` (must specify the exact Before vs. After states)
+  - `## REMOVED Requirements`
+
+## Required Input
+
+- Business requirement description or user prompt
+- Technical stack metadata from `project.md`
+
+## Expected Output
+
+- Clean markdown specification following the HeraSpec format
+- Complete Delta Spec with GIVEN-WHEN-THEN scenarios
+
+## Tone & Rules
+
+- Be extremely precise. Avoid ambiguous language like "user-friendly" or "fast".
+- Always define exact failure states (e.g. "returns 401 Unauthorized" instead of "shows error").
+- Scenarios MUST be testable and actionable.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to format the specifications into product manuals.
+- **suggestion**: Use to identify gaps in existing specs.

package/dist/core/templates/skills/spec-writer-skill.vi.md

@@ -0,0 +1,61 @@
+# Kỹ năng: Viết Đặc tả (Specification Writing) (Cross-Cutting)
+
+## Mục đích
+
+Viết và tinh chỉnh các đặc tả chức năng/kỹ thuật chất lượng cao, các user stories và các delta specs để các AI agent có thể đọc hiểu và thực thi hiệu quả.
+
+## Khi nào sử dụng
+
+- Khi bắt đầu tạo một Change mới (Bước 1 của quy trình HeraSpec)
+- Khi chuyển đổi các ý tưởng nghiệp vụ mức cao thành tài liệu spec có cấu trúc kỹ thuật
+- Khi tinh chỉnh delta specs trong quá trình giải quyết xung đột song song (parallel merge)
+
+## Quy trình từng bước
+
+### Bước 1: Định nghĩa User Story & Scenarios
+- Cấu trúc yêu cầu cốt lõi dưới dạng User Story (Với vai trò là... Tôi muốn... Để...)
+- Xây dựng các kịch bản hành vi (scenarios) sử dụng cú pháp GIVEN-WHEN-THEN (phong cách Gherkin)
+- Định nghĩa rõ luồng xử lý thành công (happy path), luồng lỗi (error path) và trường hợp biên (edge cases)
+
+### Bước 2: Cấu trúc phần Meta
+- Chỉ định rõ các component mục tiêu, domain và technical stack
+- Xác minh các yêu cầu phải khớp với quy ước kiến trúc được định nghĩa trong `project.md`
+
+### Bước 3: Viết Delta Spec
+- Phân đoạn rõ ràng các yêu cầu mới, sửa đổi và loại bỏ:
+  - `## ADDED Requirements`
+  - `## MODIFIED Requirements` (phải nêu rõ trạng thái Trước đây (Before) vs. Bây giờ (After))
+  - `## REMOVED Requirements`
+
+## Input yêu cầu
+
+- Mô tả yêu cầu nghiệp vụ hoặc prompt yêu cầu từ người dùng
+- Thông tin về tech stack lấy từ `project.md`
+
+## Output mong đợi
+
+- File đặc tả markdown sạch sẽ tuân thủ đúng định dạng của HeraSpec
+- File Delta Spec hoàn chỉnh với các kịch bản GIVEN-WHEN-THEN
+
+## Giọng điệu & Quy tắc
+
+- Cực kỳ chính xác. Tránh các từ ngữ mơ hồ như "thân thiện với người dùng" hoặc "nhanh chóng".
+- Luôn định nghĩa rõ các trạng thái lỗi cụ thể (ví dụ: "trả về lỗi 401 Unauthorized" thay vị "hiển thị lỗi").
+- Các kịch bản (scenarios) BẮT BUỘC phải kiểm thử được và có thể triển khai được.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Dùng để định dạng các đặc tả kỹ thuật thành hướng dẫn sản phẩm.
+- **suggestion**: Dùng để phát hiện các lỗ hổng trong các spec hiện có.

package/dist/core/templates/skills/sql-queries/skill.md

@@ -0,0 +1,67 @@
+# Skill: SQL Queries (Cross-Cutting)
+
+## Purpose
+
+Write correct, readable, and highly performant SQL queries across all major database systems and data warehouse dialects (PostgreSQL, Snowflake, BigQuery, Redshift, Databricks SQL).
+
+## When to Use
+
+- When writing complex analytical queries involving CTEs, window functions, and cohort retention calculations.
+- When optimizing slow-running SQL queries or translating queries between database dialects.
+- When designing data models, schema migrations, and indexing strategies.
+
+## Step-by-Step Process
+
+### Step 1: Analyze Schema & Dialect
+- Identify the target database engine (PostgreSQL, BigQuery, Snowflake, etc.).
+- Review available table schemas, keys, indexes, and partitioning keys.
+
+### Step 2: Structure Using CTEs
+- Break down complex logic into small, readable Common Table Expressions (CTEs) representing logical steps.
+
+### Step 3: Write Dialect-Specific Logic
+- Implement date/time arithmetic, string manipulation, JSON/array functions, and window functions using syntax specific to the selected dialect.
+
+### Step 4: Performance Optimization
+- Apply database-specific optimization rules:
+  - PostgreSQL: Use `EXPLAIN ANALYZE`, index columns, prefer `EXISTS` over `IN` for subqueries.
+  - BigQuery: Minimize scanned bytes, partition on date columns, use `APPROX_COUNT_DISTINCT`.
+  - Snowflake: Leverage clustering keys, transient tables, and avoid unnecessary warehouse resizing.
+
+### Step 5: Test & Debug
+- Verify correct handling of boundary cases (division by zero, null fields, type mismatch casting).
+
+## Required Input
+
+- **Database Engine**: PostgreSQL, BigQuery, Snowflake, etc.
+- **Goal/Query Purpose**: What analytical question the query should answer.
+- **Table Schema**: Definitions, keys, and partitioning details.
+
+## Expected Output
+
+- **Optimized SQL Code**: Full query code formatted using uppercase keywords and standard alignment.
+- **Performance Explanation**: Brief details on partition pruning, indexing, or dialect-specific functions used to speed up the query.
+- **Query Flow Explanation**: Explanation of each CTE step for developer readability.
+
+## Tone & Rules
+
+- Write clean, modern SQL using uppercase for keywords (SELECT, FROM, WHERE, etc.).
+- Always qualify column names with table aliases when using JOINs.
+- Avoid nested subqueries; always prefer Common Table Expressions (CTEs) for readability.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to document database schemas or technical data flow maps.
+- **debug**: Use to diagnose and resolve errors returned by SQL execution engines.

package/dist/core/templates/skills/sql-queries/skill.vi.md

@@ -0,0 +1,67 @@
+# Kỹ năng: Truy vấn SQL (SQL Queries) (Cross-Cutting)
+
+## Mục đích
+
+Viết các câu truy vấn SQL chính xác, dễ đọc và đạt hiệu năng tối ưu trên các hệ thống cơ sở dữ liệu và kho dữ liệu phổ biến (PostgreSQL, Snowflake, BigQuery, Redshift, Databricks SQL).
+
+## Khi nào sử dụng
+
+- Khi viết các câu truy vấn phân tích phức tạp có sử dụng CTEs, hàm cửa sổ (window functions) và tính toán tỷ lệ giữ chân khách hàng (cohort retention).
+- Khi tối ưu hóa các câu lệnh SQL chạy chậm hoặc chuyển đổi cú pháp truy vấn giữa các hệ quản trị cơ sở dữ liệu khác nhau.
+- Khi thiết kế mô hình dữ liệu, viết mã dịch chuyển cấu trúc bảng (migrations) và lập chiến lược đánh chỉ mục (indexing).
+
+## Quy trình từng bước
+
+### Bước 1: Phân tích Lược đồ & Cú pháp Dialect
+- Xác định hệ quản trị cơ sở dữ liệu đích (PostgreSQL, BigQuery, Snowflake, v.v...).
+- Xem xét cấu trúc các bảng dữ liệu, khóa chính/phụ, chỉ mục (indexes) và khóa phân vùng (partition keys).
+
+### Bước 2: Cấu trúc hóa bằng CTEs
+- Chia nhỏ logic phức tạp thành các biểu thức bảng chung (Common Table Expressions - CTEs) dễ đọc, đại diện cho từng bước xử lý dữ liệu tuần tự.
+
+### Bước 3: Viết Logic Đặc thù theo Dialect
+- Triển khai các phép toán ngày/tháng, xử lý chuỗi văn bản, trích xuất JSON/mảng và các hàm cửa sổ sử dụng đúng cú pháp của cơ sở dữ liệu đích.
+
+### Bước 4: Tối ưu hóa Hiệu năng (Performance Optimization)
+- Áp dụng các quy tắc tối ưu đặc thù:
+  - PostgreSQL: Sử dụng `EXPLAIN ANALYZE` để xem chi tiết thực thi, đánh chỉ mục các cột lọc/join, ưu tiên `EXISTS` thay vì `IN` cho truy vấn con.
+  - BigQuery: Giảm thiểu dung lượng quét dữ liệu (scanned bytes), lọc theo cột phân vùng date, sử dụng `APPROX_COUNT_DISTINCT`.
+  - Snowflake: Tận dụng khóa gom cụm (clustering keys), bảng tạm thời (transient tables) và tránh thay đổi kích thước warehouse không cần thiết.
+
+### Bước 5: Kiểm thử & Sửa lỗi
+- Xác minh cách xử lý các trường hợp đặc biệt (chia cho 0, giá trị null, ép kiểu dữ liệu mismatch).
+
+## Input yêu cầu
+
+- **Database Engine**: Loại cơ sở dữ liệu (PostgreSQL, BigQuery, Snowflake, v.v...).
+- **Mục đích truy vấn**: Câu hỏi nghiệp vụ cần trả lời bằng dữ liệu.
+- **Lược đồ bảng (Table Schema)**: Định nghĩa các bảng, kiểu dữ liệu, các trường khóa và chi tiết phân vùng.
+
+## Output mong đợi
+
+- **Mã lệnh SQL Tối ưu**: Câu lệnh SQL hoàn chỉnh được định dạng viết hoa các từ khóa chính và căn lề chuẩn mực.
+- **Giải thích Hiệu năng**: Mô tả ngắn gọn về phân vùng dữ liệu, chỉ mục hoặc hàm đặc thù được dùng để tăng tốc truy vấn.
+- **Giải thích Luồng truy vấn**: Giải thích rõ ràng mục đích của từng bước CTE để nhà phát triển dễ đọc hiểu.
+
+## Giọng điệu & Quy tắc
+
+- Viết mã SQL sạch, hiện đại bằng cách viết hoa các từ khóa chuẩn (SELECT, FROM, WHERE, v.v...).
+- Luôn đặt tên viết tắt (alias) cho các bảng và gọi tên cột kèm alias khi thực hiện JOINs.
+- Hạn chế viết các truy vấn con lồng nhau phức tạp; luôn ưu tiên sử dụng CTEs để giữ code sạch sẽ.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Sử dụng để viết tài liệu thiết kế cơ sở dữ liệu hoặc sơ đồ luồng dữ liệu kỹ thuật.
+- **debug**: Sử dụng để chẩn đoán và khắc phục các lỗi cú pháp/logic do công cụ cơ sở dữ liệu trả về.

package/dist/core/templates/skills/sql-queries-skill.md

@@ -0,0 +1,67 @@
+# Skill: SQL Queries (Cross-Cutting)
+
+## Purpose
+
+Write correct, readable, and highly performant SQL queries across all major database systems and data warehouse dialects (PostgreSQL, Snowflake, BigQuery, Redshift, Databricks SQL).
+
+## When to Use
+
+- When writing complex analytical queries involving CTEs, window functions, and cohort retention calculations.
+- When optimizing slow-running SQL queries or translating queries between database dialects.
+- When designing data models, schema migrations, and indexing strategies.
+
+## Step-by-Step Process
+
+### Step 1: Analyze Schema & Dialect
+- Identify the target database engine (PostgreSQL, BigQuery, Snowflake, etc.).
+- Review available table schemas, keys, indexes, and partitioning keys.
+
+### Step 2: Structure Using CTEs
+- Break down complex logic into small, readable Common Table Expressions (CTEs) representing logical steps.
+
+### Step 3: Write Dialect-Specific Logic
+- Implement date/time arithmetic, string manipulation, JSON/array functions, and window functions using syntax specific to the selected dialect.
+
+### Step 4: Performance Optimization
+- Apply database-specific optimization rules:
+  - PostgreSQL: Use `EXPLAIN ANALYZE`, index columns, prefer `EXISTS` over `IN` for subqueries.
+  - BigQuery: Minimize scanned bytes, partition on date columns, use `APPROX_COUNT_DISTINCT`.
+  - Snowflake: Leverage clustering keys, transient tables, and avoid unnecessary warehouse resizing.
+
+### Step 5: Test & Debug
+- Verify correct handling of boundary cases (division by zero, null fields, type mismatch casting).
+
+## Required Input
+
+- **Database Engine**: PostgreSQL, BigQuery, Snowflake, etc.
+- **Goal/Query Purpose**: What analytical question the query should answer.
+- **Table Schema**: Definitions, keys, and partitioning details.
+
+## Expected Output
+
+- **Optimized SQL Code**: Full query code formatted using uppercase keywords and standard alignment.
+- **Performance Explanation**: Brief details on partition pruning, indexing, or dialect-specific functions used to speed up the query.
+- **Query Flow Explanation**: Explanation of each CTE step for developer readability.
+
+## Tone & Rules
+
+- Write clean, modern SQL using uppercase for keywords (SELECT, FROM, WHERE, etc.).
+- Always qualify column names with table aliases when using JOINs.
+- Avoid nested subqueries; always prefer Common Table Expressions (CTEs) for readability.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to document database schemas or technical data flow maps.
+- **debug**: Use to diagnose and resolve errors returned by SQL execution engines.