heraspec 0.1.14 → 0.1.15

package/dist/core/templates/skills/project-memory/skill.vi.md

@@ -0,0 +1,223 @@
+---
+name: project-memory
+description: Hệ thống bộ nhớ dự án bổ trợ cho AI agent. Ghi lại các quan sát, quyết định và tóm tắt phiên làm việc để duy trì ngữ cảnh giữa các phiên phát triển. Ngăn ngừa việc làm trùng lặp, theo dõi các quyết định kiến trúc và cho phép truy xuất ngữ cảnh tối ưu token.
+projectType: all
+---
+
+# Project Memory Skill
+
+## Mục đích
+
+Cho phép AI agent duy trì **ngữ cảnh dự án bền vững** qua các phiên làm việc bằng cách tiếp cận bổ trợ (không can thiệp). Hệ thống bộ nhớ ghi lại những gì đã làm, đã học được và những quyết định đã đưa ra — để các phiên trong tương lai bắt đầu với ngữ cảnh có liên quan thay vì phải đọc lại toàn bộ mã nguồn (codebase).
+
+## Khi nào nên dùng
+
+- **Trước khi triển khai tính năng mới**: Tìm kiếm bộ nhớ xem có công việc tương tự nào đã làm trước đó không.
+- **Sau khi hoàn thành một nhiệm vụ quan trọng**: Ghi lại quan sát (observation) để lưu lại những gì đã thực hiện.
+- **Vào cuối một phiên làm việc (session)**: Tóm tắt phiên làm việc để tham khảo sau này.
+- **Khi bắt đầu một phiên làm việc phức tạp**: Đọc ngữ cảnh để hiểu lịch sử của dự án.
+
+## Cách tiếp cận bổ trợ (Complementary Approach)
+
+> **Skill này mang tính BỔ TRỢ, không bắt buộc.** AI agent sử dụng bộ nhớ KHI HỮU ÍCH, không phải ở mọi bước.
+> 
+> - Nhiệm vụ đơn giản (sửa lỗi chính tả, format code): Bỏ qua bộ nhớ hoàn toàn → tốn 0 token.
+> - Nhiệm vụ phức tạp (tính năng mới, thay đổi kiến trúc): Dùng bộ nhớ → tiết kiệm 10-30x token so với việc đọc lại codebase.
+
+## Các Lệnh Có Sẵn
+
+### 1. Ghi lại quan sát (Log an Observation - Post-Task)
+Ghi lại những gì đã làm sau khi hoàn thành một nhiệm vụ quan trọng:
+
+```bash
+heraspec memory log \
+  --type <decision|bugfix|feature|refactor|discovery|change> \
+  --title "Tiêu đề mô tả ngắn gọn" \
+  --narrative "Mô tả chi tiết về những gì đã làm và lý do" \
+  --concepts "tag1,tag2,tag3" \
+  --files-modified "src/file1.ts,src/file2.ts"
+```
+
+**Các loại quan sát (Observation types):**
+| Loại (Type) | Icon | Khi nào dùng |
+|------|------|------------|
+| `decision` | ⚖️ | Quyết định về kiến trúc hoặc thiết kế kèm theo lý do |
+| `bugfix` | 🔴 | Sửa lỗi kèm theo nguyên nhân gốc rễ |
+| `feature` | 🟢 | Triển khai tính năng mới |
+| `refactor` | 🔄 | Tái cấu trúc hoặc tối ưu hóa mã nguồn |
+| `discovery` | 🔵 | Những phát hiện quan trọng về codebase hoặc hành vi |
+| `change` | ✅ | Các thay đổi code chung chung |
+
+### 2. Tìm kiếm trong bộ nhớ (Search Memory - Pre-Implementation)
+Kiểm tra xem các công việc liên quan có tồn tại không trước khi triển khai tính năng mới:
+
+```bash
+heraspec memory search "authentication middleware"
+heraspec memory search --type feature --concepts "auth,login"
+heraspec memory search --id 42   # Lấy chi tiết đầy đủ của observation #42
+```
+
+### 3. Tạo ngữ cảnh (Generate Context - Session Start)
+Nhận bản tóm tắt các hoạt động gần đây của dự án:
+
+```bash
+heraspec memory context           # In ra stdout
+heraspec memory context --output file  # Ghi vào file heraspec/memory/context.md
+```
+
+### 4. Tóm tắt phiên làm việc (Summarize Session - Session End)
+Ghi lại những thành quả đạt được trong phiên làm việc này:
+
+```bash
+heraspec memory summarize \
+  --request "Người dùng đã yêu cầu gì?" \
+  --completed "Những gì đã được thực hiện?" \
+  --learned "Những hiểu biết (insights) quan trọng đã phát hiện" \
+  --next-steps "Những việc còn lại cần làm" \
+  --files-edited "src/file1.ts,src/file2.ts"
+```
+
+### 5. Xem trạng thái (View Status)
+Kiểm tra số liệu thống kê bộ nhớ:
+
+```bash
+heraspec memory status    # Số lượng observation, top concepts, top files
+heraspec memory timeline  # Xem hoạt động theo thứ tự thời gian
+```
+
+### 6. Báo cáo Phân tích Token (Token Analytics Report)
+Xem bảng so sánh chi tiết token đã dùng và tiết kiệm theo từng dự án:
+
+```bash
+heraspec memory analytics            # Bảng + biểu đồ về hiệu quả token
+heraspec memory analytics --history  # Đính kèm thêm 13 mốc thời gian file DB thay đổi kích thước
+```
+
+Kết quả bao gồm:
+- **Bảng (Table)**: Tên dự án, Số thao tác, Token khi dùng Memory, Token khi không dùng Memory, % Tiết kiệm, **Kích thước DB**
+- **Biểu đồ thanh (Bar Chart)**: So sánh trực quan số token đã tránh được cho mỗi dự án
+- **Tổng cộng (Totals)**: Tổng hợp tiết kiệm trên tất cả dự án
+- **Lịch sử (History - Tùy chọn)**: Bảng thời gian (Chronological delta chart) cho thấy file `.db` đã thay đổi kích thước ra sao qua các lần cập nhật.
+
+### 7. Bảo trì (Maintenance)
+```bash
+heraspec memory prune 90  # Xóa các observation cũ hơn 90 ngày
+```
+
+## Quy trình làm việc cho AI Agent
+
+### Khi nào nên dùng Memory (Cây Quyết Định)
+
+```
+Nhận nhiệm vụ từ user
+├── Nhiệm vụ đơn giản/nhỏ lẻ? → Bỏ qua bộ nhớ, làm luôn
+├── Tính năng mới hay thay đổi lớn?
+│   ├── Tìm kiếm bộ nhớ: "heraspec memory search <từ khóa>"
+│   ├── Tìm thấy kết quả? → Đọc observation liên quan, tránh làm lại từ đầu
+│   └── Không có kết quả? → Tiến hành bình thường
+├── Sau khi hoàn thành nhiệm vụ:
+│   ├── Quan trọng/Lớn? → Ghi lại observation
+│   └── Nhỏ lẻ? → Bỏ qua ghi log
+└── Kết thúc phiên làm việc?
+    └── Đã hoàn thành nhiều nhiệm vụ? → Tạo tóm tắt phiên (session summary)
+```
+
+### Các Nguyên Tắc Chính
+
+1. **Đừng gượng ép**: Chỉ sử dụng bộ nhớ khi nó thực sự giúp tiết kiệm thời gian hoặc tránh sai sót.
+2. **Chất lượng hơn số lượng**: Một observation chi tiết còn hơn mười cái hời hợt.
+3. **Concept là cốt lõi**: Việc gắn thẻ concept chuẩn (`auth`, `database`, `api`, `ui`) giúp tìm kiếm hiệu quả.
+4. **File cũng rất quan trọng**: Ghi lại file nào đã sửa giúp cho AI lần sau điều hướng dễ dàng hơn.
+
+## Cấu hình
+
+Cấu hình bộ nhớ được lưu trữ tại `heraspec/memory/config.json`:
+
+```json
+{
+  "totalObservationCount": 50,
+  "fullObservationCount": 5,
+  "sessionCount": 5,
+  "maxTokens": 6000,
+  "showLastSummary": true
+}
+```
+
+## Tối ưu (Token Economics)
+
+| Hành động | Chi phí Token | Token Tiết kiệm được |
+|--------|-----------|---------------|
+| Đọc ngữ cảnh (context) | ~2,000-4,000 | so với ~50,000-120,000 khi đọc lại codebase |
+| Tìm kiếm bộ nhớ (search)| ~500-1,000 | so với ~5,000-15,000 nếu phải làm lại mã nguồn |
+| Ghi lại observation | ~200-500 | Đầu tư dài hạn cho các phiên sau |
+| Smart explore (outline) | ~1,000-2,000 | so với ~12,000+ nếu đọc toàn bộ file |
+
+Để xem bảng phân tích trực tiếp về số token đã tiết kiệm, chạy:
+```bash
+heraspec memory analytics
+```
+
+## Tích hợp dữ liệu cũ (Bootstrapping Existing Projects)
+
+Nếu bạn vừa thêm skill `project-memory` vào một **dự án cũ** đã và đang làm việc theo quy trình HeraSpec (đã có thư mục `heraspec/specs/` và `heraspec/archives/`), bạn có thể "tích hợp" dữ liệu về bộ nhớ rất dễ dàng mà không cần lập trình thêm.
+
+Chỉ cần gửi duy nhất một prompt sau cho AI Agent (MỘT LẦN VÀ DUY NHẤT):
+
+```text
+Sử dụng skill project-memory.
+Bạn hãy khởi tạo memory cho dự án này từ các specs và archives đã có.
+Mở thư mục: heraspec/specs/ và heraspec/archives/
+Với MỖI sub-folder/file có trong đó, hãy đọc lướt để hiểu nội dung, sau đó chạy lệnh:
+
+heraspec memory log \
+  --type feature \
+  --title "[Trích xuất tên spec/change]" \
+  --narrative "[Tóm tắt ngắn gọn những gì đã được triển khai trong spec này]" \
+  --concepts "[Trích xuất các thẻ/công nghệ chính]" \
+  --files-modified "[Trích xuất hoặc suy thoái các file bị ảnh hưởng]"
+
+Lặp lại việc này cho đến khi di chuyển (migrate) hoàn tất tất cả spec cũ vào hệ thống memory.
+```
+
+Ngoài ra, có thể sử dụng **lệnh CLI có sẵn** (nhanh hơn, không tốn AI token):
+```bash
+heraspec memory bootstrap        # Tương tác — hỏi xác nhận trước khi chạy
+heraspec memory bootstrap --yes  # Không tương tác — tự động xác nhận
+```
+
+Lệnh này sẽ tự động quét `heraspec/specs/`, `heraspec/archives/` và `heraspec/changes/`, trích xuất tiêu đề/nội dung/file từ mỗi markdown spec, rồi chèn vào cơ sở dữ liệu memory.
+
+> **Lưu ý:** Các tiêu đề trùng lặp sẽ tự động bị bỏ qua, nên chạy lệnh nhiều lần vẫn an toàn.
+
+## Báo cáo do Agent kích hoạt (Agent-Triggered Reporting)
+
+Khi user yêu cầu AI agent xem báo cáo bộ nhớ, phân tích token hoặc thống kê tiết kiệm — agent nên chạy lệnh CLI và hiển thị kết quả cho user:
+
+```text
+User: "Cho tôi xem báo cáo phân tích memory"
+User: "Hệ thống memory đã tiết kiệm bao nhiêu token?"
+User: "Xem báo cáo token usage"
+User: "Show me the memory analytics report"
+```
+
+**Hành động của Agent:** Chạy lệnh sau và hiển thị kết quả cho user:
+```bash
+heraspec memory analytics
+```
+
+Để xem trạng thái nhanh:
+```bash
+heraspec memory status
+```
+
+Để xem dòng thời gian:
+```bash
+heraspec memory timeline
+```
+
+## Hạn chế (Limitations)
+
+- Bộ nhớ chỉ mang tính cục bộ (local) của dự án (lưu trong `heraspec/memory/`).
+- Yêu cầu gói npm `better-sqlite3`.
+- Tìm kiếm FTS5 là tìm kiếm dựa trên từ khóa (keyword-based), không phải theo ngữ nghĩa (semantic).
+- Agent phải tự quyết định thời điểm thích hợp để sử dụng bộ nhớ (cách tiếp cận bổ trợ).

package/dist/core/templates/skills/seo-audit/skill.md

@@ -0,0 +1,75 @@
+# Skill: SEO Audit (Cross-Cutting)
+
+## Purpose
+
+Run a comprehensive SEO audit — keyword research, on-page analysis, content gaps, technical checks, and competitor comparison to generate a prioritized SEO action plan.
+
+## When to Use
+
+- When assessing a website's overall SEO health and indexation status.
+- When researching keyword opportunities and identifying high-volume, low-difficulty search queries.
+- When identifying content gaps where competitors rank higher.
+- When reviewing technical website issues (crawlability, page speed, structured schema data).
+
+## Step-by-Step Process
+
+### Step 1: Keyword & Competitor Research
+- Extract primary and secondary keywords relevant to the business/domain.
+- Group keywords by search intent (informational, navigational, commercial, transactional).
+- Identify top 2-3 organic competitors.
+
+### Step 2: On-Page SEO Analysis
+- Verify title tag length (50-60 chars) and meta description length (150-160 chars).
+- Confirm presence of exactly one H1 tag per page.
+- Evaluate subheading hierarchy (H2/H3) and keyword usage.
+- Assess image alt text and URL clean structure.
+
+### Step 3: Content Gap & Freshness Review
+- Detect topics covered by competitors but missing on the site.
+- Identify pages with thin content (<300 words) or content older than 12 months.
+
+### Step 4: Technical SEO Audit
+- Review Robots.txt and XML sitemap configurations.
+- Check canonical tags, HTTPS mixed content, and 404 broken links.
+- Review Page Speed and Core Web Vitals (LCP, INP, CLS) markers.
+
+### Step 5: Prioritized Action Plan Formulation
+- Group recommendations into "Quick Wins" (<2h effort, high impact) and "Strategic Investments" (long-term, pillar pages).
+
+## Required Input
+
+- **Domain/URL**: The website to audit.
+- **Audit Type**: Full site audit, keyword research, content gap, or technical SEO check.
+- **Target Keywords** (Optional): Specific terms already being targeted.
+- **Competitors** (Optional): Specific competitor URLs/domains.
+
+## Expected Output
+
+- **Executive Summary**: 3-5 sentence overview of SEO health and top 3 priorities.
+- **Keyword Table**: Formatted table with Estimated Difficulty, Opportunity Score, and Intent.
+- **On-Page Issues Table**: Issues categorized by Severity (Critical, High, Medium, Low).
+- **Technical SEO Checklist**: Status (Pass, Fail, Warning) of crawlability, speed, and schema.
+- **Prioritized Action Plan**: Split into Quick Wins and Strategic Investments.
+
+## Tone & Rules
+
+- Write in a professional, marketing-focused, data-driven tone.
+- Do not make generic claims; base recommendations on specific, quantifiable SEO principles.
+- Use bullet points and markdown tables for maximum scannability.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to draft the final SEO audit report or content briefs.
+- **ui-ux**: Use to optimize pages for Core Web Vitals and mobile responsiveness.

package/dist/core/templates/skills/seo-audit/skill.vi.md

@@ -0,0 +1,75 @@
+# Kỹ năng: Kiểm toán SEO (SEO Audit) (Cross-Cutting)
+
+## Mục đích
+
+Thực hiện kiểm toán SEO toàn diện — nghiên cứu từ khóa, phân tích trên trang (on-page), tìm khoảng trống nội dung, kiểm tra kỹ thuật (technical SEO), và so sánh đối thủ cạnh tranh để lập kế hoạch hành động SEO tối ưu.
+
+## Khi nào sử dụng
+
+- Khi đánh giá sức khỏe SEO tổng thể và trạng thái lập chỉ mục (indexation) của một website.
+- Khi tìm kiếm cơ hội từ khóa và xác định các truy vấn tìm kiếm có lưu lượng cao nhưng độ khó thấp.
+- Khi phát hiện các khoảng trống nội dung mà đối thủ đang xếp hạng cao hơn.
+- Khi rà soát các vấn đề kỹ thuật của website (khả năng thu thập thông tin - crawlability, tốc độ trang, dữ liệu cấu trúc schema).
+
+## Quy trình từng bước
+
+### Bước 1: Nghiên cứu Từ khóa & Đối thủ cạnh tranh
+- Trích xuất từ khóa chính và phụ liên quan đến lĩnh vực kinh doanh/tên miền.
+- Phân nhóm từ khóa theo mục đích tìm kiếm (thông tin, điều hướng, thương mại, giao dịch).
+- Xác định 2-3 đối thủ cạnh tranh trực tiếp trên kết quả tìm kiếm tự nhiên.
+
+### Bước 2: Phân tích SEO On-Page
+- Kiểm tra độ dài thẻ tiêu đề (50-60 ký tự) và thẻ mô tả meta (150-160 ký tự).
+- Đảm bảo mỗi trang chỉ có duy nhất một thẻ H1.
+- Đánh giá cấu trúc phân cấp tiêu đề (H2/H3) và cách phân bổ từ khóa.
+- Đánh giá thuộc tính alt của ảnh và cấu trúc đường dẫn (URL) thân thiện.
+
+### Bước 3: Đánh giá Khoảng trống & Độ mới của Nội dung
+- Phát hiện các chủ đề đối thủ đã bao phủ nhưng trang web của bạn chưa có.
+- Xác định các trang có nội dung mỏng (<300 từ) hoặc không được cập nhật trong vòng 12 tháng qua.
+
+### Bước 4: Kiểm toán Kỹ thuật (Technical SEO)
+- Kiểm tra cấu hình file Robots.txt và sơ đồ trang XML sitemap.
+- Kiểm tra thẻ canonical, lỗi bảo mật hỗn hợp HTTPS và các liên kết gãy 404.
+- Đánh giá tốc độ tải trang và các chỉ số Core Web Vitals (LCP, INP, CLS).
+
+### Bước 5: Lập Kế hoạch Hành động Ưu tiên
+- Phân nhóm các đề xuất thành "Thành công nhanh" (Quick Wins - tốn ít hơn 2h thực hiện, hiệu quả ngay) và "Đầu tư Chiến lược" (Strategic Investments - dài hạn, xây dựng cụm chủ đề pillar page).
+
+## Input yêu cầu
+
+- **Domain/URL**: Trang web cần kiểm toán.
+- **Loại kiểm toán**: Kiểm toán toàn bộ trang, nghiên cứu từ khóa, phân tích khoảng trống nội dung, hoặc kiểm tra SEO kỹ thuật.
+- **Từ khóa mục tiêu** (Không bắt buộc): Các cụm từ cụ thể mà dự án đang muốn nhắm tới.
+- **Đối thủ cạnh tranh** (Không bắt buộc): Tên miền của các đối thủ cần so sánh.
+
+## Output mong đợi
+
+- **Tóm tắt điều hành**: Bản tóm tắt 3-5 câu về tình trạng SEO của website và 3 ưu tiên hàng đầu.
+- **Bảng Từ khóa**: Bảng định dạng rõ ràng gồm Độ khó ước tính, Điểm cơ hội và Ý định tìm kiếm.
+- **Bảng lỗi On-Page**: Danh sách các lỗi được phân loại theo mức độ nghiêm trọng (Nghiêm trọng, Cao, Trung bình, Thấp).
+- **Checklist SEO Kỹ thuật**: Trạng thái (Đạt, Lỗi, Cảnh báo) của các mục crawlability, tốc độ và dữ liệu cấu trúc schema.
+- **Kế hoạch hành động**: Được chia thành Quick Wins và Strategic Investments.
+
+## Giọng điệu & Quy tắc
+
+- Sử dụng giọng điệu chuyên nghiệp, định hướng marketing và dựa trên dữ liệu thực tế.
+- Tránh đưa ra các nhận định chung chung; các đề xuất phải dựa trên các nguyên tắc SEO cụ thể, có thể định lượng được.
+- Sử dụng các danh sách dạng dấu chấm và bảng markdown để đảm bảo dễ đọc nhất.
+
+## 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 để viết báo cáo kiểm toán SEO cuối cùng hoặc lập dàn ý nội dung (content briefs).
+- **ui-ux**: Dùng để tối ưu hóa trang web cho Core Web Vitals và khả năng tương thích trên thiết bị di động.

package/dist/core/templates/skills/seo-audit-skill.md

@@ -0,0 +1,75 @@
+# Skill: SEO Audit (Cross-Cutting)
+
+## Purpose
+
+Run a comprehensive SEO audit — keyword research, on-page analysis, content gaps, technical checks, and competitor comparison to generate a prioritized SEO action plan.
+
+## When to Use
+
+- When assessing a website's overall SEO health and indexation status.
+- When researching keyword opportunities and identifying high-volume, low-difficulty search queries.
+- When identifying content gaps where competitors rank higher.
+- When reviewing technical website issues (crawlability, page speed, structured schema data).
+
+## Step-by-Step Process
+
+### Step 1: Keyword & Competitor Research
+- Extract primary and secondary keywords relevant to the business/domain.
+- Group keywords by search intent (informational, navigational, commercial, transactional).
+- Identify top 2-3 organic competitors.
+
+### Step 2: On-Page SEO Analysis
+- Verify title tag length (50-60 chars) and meta description length (150-160 chars).
+- Confirm presence of exactly one H1 tag per page.
+- Evaluate subheading hierarchy (H2/H3) and keyword usage.
+- Assess image alt text and URL clean structure.
+
+### Step 3: Content Gap & Freshness Review
+- Detect topics covered by competitors but missing on the site.
+- Identify pages with thin content (<300 words) or content older than 12 months.
+
+### Step 4: Technical SEO Audit
+- Review Robots.txt and XML sitemap configurations.
+- Check canonical tags, HTTPS mixed content, and 404 broken links.
+- Review Page Speed and Core Web Vitals (LCP, INP, CLS) markers.
+
+### Step 5: Prioritized Action Plan Formulation
+- Group recommendations into "Quick Wins" (<2h effort, high impact) and "Strategic Investments" (long-term, pillar pages).
+
+## Required Input
+
+- **Domain/URL**: The website to audit.
+- **Audit Type**: Full site audit, keyword research, content gap, or technical SEO check.
+- **Target Keywords** (Optional): Specific terms already being targeted.
+- **Competitors** (Optional): Specific competitor URLs/domains.
+
+## Expected Output
+
+- **Executive Summary**: 3-5 sentence overview of SEO health and top 3 priorities.
+- **Keyword Table**: Formatted table with Estimated Difficulty, Opportunity Score, and Intent.
+- **On-Page Issues Table**: Issues categorized by Severity (Critical, High, Medium, Low).
+- **Technical SEO Checklist**: Status (Pass, Fail, Warning) of crawlability, speed, and schema.
+- **Prioritized Action Plan**: Split into Quick Wins and Strategic Investments.
+
+## Tone & Rules
+
+- Write in a professional, marketing-focused, data-driven tone.
+- Do not make generic claims; base recommendations on specific, quantifiable SEO principles.
+- Use bullet points and markdown tables for maximum scannability.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to draft the final SEO audit report or content briefs.
+- **ui-ux**: Use to optimize pages for Core Web Vitals and mobile responsiveness.

package/dist/core/templates/skills/seo-audit-skill.vi.md

@@ -0,0 +1,75 @@
+# Kỹ năng: Kiểm toán SEO (SEO Audit) (Cross-Cutting)
+
+## Mục đích
+
+Thực hiện kiểm toán SEO toàn diện — nghiên cứu từ khóa, phân tích trên trang (on-page), tìm khoảng trống nội dung, kiểm tra kỹ thuật (technical SEO), và so sánh đối thủ cạnh tranh để lập kế hoạch hành động SEO tối ưu.
+
+## Khi nào sử dụng
+
+- Khi đánh giá sức khỏe SEO tổng thể và trạng thái lập chỉ mục (indexation) của một website.
+- Khi tìm kiếm cơ hội từ khóa và xác định các truy vấn tìm kiếm có lưu lượng cao nhưng độ khó thấp.
+- Khi phát hiện các khoảng trống nội dung mà đối thủ đang xếp hạng cao hơn.
+- Khi rà soát các vấn đề kỹ thuật của website (khả năng thu thập thông tin - crawlability, tốc độ trang, dữ liệu cấu trúc schema).
+
+## Quy trình từng bước
+
+### Bước 1: Nghiên cứu Từ khóa & Đối thủ cạnh tranh
+- Trích xuất từ khóa chính và phụ liên quan đến lĩnh vực kinh doanh/tên miền.
+- Phân nhóm từ khóa theo mục đích tìm kiếm (thông tin, điều hướng, thương mại, giao dịch).
+- Xác định 2-3 đối thủ cạnh tranh trực tiếp trên kết quả tìm kiếm tự nhiên.
+
+### Bước 2: Phân tích SEO On-Page
+- Kiểm tra độ dài thẻ tiêu đề (50-60 ký tự) và thẻ mô tả meta (150-160 ký tự).
+- Đảm bảo mỗi trang chỉ có duy nhất một thẻ H1.
+- Đánh giá cấu trúc phân cấp tiêu đề (H2/H3) và cách phân bổ từ khóa.
+- Đánh giá thuộc tính alt của ảnh và cấu trúc đường dẫn (URL) thân thiện.
+
+### Bước 3: Đánh giá Khoảng trống & Độ mới của Nội dung
+- Phát hiện các chủ đề đối thủ đã bao phủ nhưng trang web của bạn chưa có.
+- Xác định các trang có nội dung mỏng (<300 từ) hoặc không được cập nhật trong vòng 12 tháng qua.
+
+### Bước 4: Kiểm toán Kỹ thuật (Technical SEO)
+- Kiểm tra cấu hình file Robots.txt và sơ đồ trang XML sitemap.
+- Kiểm tra thẻ canonical, lỗi bảo mật hỗn hợp HTTPS và các liên kết gãy 404.
+- Đánh giá tốc độ tải trang và các chỉ số Core Web Vitals (LCP, INP, CLS).
+
+### Bước 5: Lập Kế hoạch Hành động Ưu tiên
+- Phân nhóm các đề xuất thành "Thành công nhanh" (Quick Wins - tốn ít hơn 2h thực hiện, hiệu quả ngay) và "Đầu tư Chiến lược" (Strategic Investments - dài hạn, xây dựng cụm chủ đề pillar page).
+
+## Input yêu cầu
+
+- **Domain/URL**: Trang web cần kiểm toán.
+- **Loại kiểm toán**: Kiểm toán toàn bộ trang, nghiên cứu từ khóa, phân tích khoảng trống nội dung, hoặc kiểm tra SEO kỹ thuật.
+- **Từ khóa mục tiêu** (Không bắt buộc): Các cụm từ cụ thể mà dự án đang muốn nhắm tới.
+- **Đối thủ cạnh tranh** (Không bắt buộc): Tên miền của các đối thủ cần so sánh.
+
+## Output mong đợi
+
+- **Tóm tắt điều hành**: Bản tóm tắt 3-5 câu về tình trạng SEO của website và 3 ưu tiên hàng đầu.
+- **Bảng Từ khóa**: Bảng định dạng rõ ràng gồm Độ khó ước tính, Điểm cơ hội và Ý định tìm kiếm.
+- **Bảng lỗi On-Page**: Danh sách các lỗi được phân loại theo mức độ nghiêm trọng (Nghiêm trọng, Cao, Trung bình, Thấp).
+- **Checklist SEO Kỹ thuật**: Trạng thái (Đạt, Lỗi, Cảnh báo) của các mục crawlability, tốc độ và dữ liệu cấu trúc schema.
+- **Kế hoạch hành động**: Được chia thành Quick Wins và Strategic Investments.
+
+## Giọng điệu & Quy tắc
+
+- Sử dụng giọng điệu chuyên nghiệp, định hướng marketing và dựa trên dữ liệu thực tế.
+- Tránh đưa ra các nhận định chung chung; các đề xuất phải dựa trên các nguyên tắc SEO cụ thể, có thể định lượng được.
+- Sử dụng các danh sách dạng dấu chấm và bảng markdown để đảm bảo dễ đọc nhất.
+
+## 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 để viết báo cáo kiểm toán SEO cuối cùng hoặc lập dàn ý nội dung (content briefs).
+- **ui-ux**: Dùng để tối ưu hóa trang web cho Core Web Vitals và khả năng tương thích trên thiết bị di động.

package/dist/core/templates/skills/smart-explore/skill.md

@@ -0,0 +1,141 @@
+---
+name: smart-explore
+description: Token-efficient code exploration — view file structure, search symbols, and read specific implementations without loading full files. Reduces token usage by 4-18x compared to reading entire files.
+projectType: all
+---
+
+# Smart Explore Skill
+
+## Purpose
+
+Enable AI agents to **explore codebases efficiently** by viewing structural outlines, searching for symbols, and extracting specific implementations — without reading entire files. This dramatically reduces token consumption when navigating large projects.
+
+## When to Use
+
+- **Understanding a new file**: Use `outline` instead of reading the full file
+- **Finding where something is defined**: Use `search` to locate symbols across the project
+- **Reading a specific function**: Use `unfold` to extract just that function's code
+
+## Token Savings
+
+| Method | Typical Token Cost | Notes |
+|--------|-------------------|-------|
+| Read full file | ~12,000+ | All content, most irrelevant |
+| **Outline** | ~1,000-2,000 | Structural skeleton only |
+| **Search** | ~2,000-6,000 | Symbol locations across codebase |
+| **Unfold** | ~400-2,100 | Exact function/class source |
+
+**Savings: 4-18x** compared to reading full files.
+
+## Available Commands
+
+### 1. Outline — Structural Skeleton
+
+View all symbols (functions, classes, interfaces, exports) in a file without reading the full source:
+
+```bash
+heraspec explore outline src/core/memory/memory-store.ts
+```
+
+**Output example:**
+```
+## 📄 src/core/memory/memory-store.ts
+*typescript | 285 lines | ~71250 tokens*
+
+🏛️ export class MemoryStore (L20-285)
+  ↳ open() (L32-58)
+  ↳ close() (L63-68)
+  ↳ addObservation(input) (L88-120)
+  ↳ getObservationById(id) (L125-132)
+  ↳ getRecentObservations(project, limit) (L140-160)
+  ↳ addSummary(input) (L165-195)
+  ↳ getStatus(project) (L200-260)
+```
+
+### 2. Search — Find Symbols Across Codebase
+
+Search for functions, classes, interfaces by name across the project:
+
+```bash
+heraspec explore search "MemoryStore" src/
+heraspec explore search "addObservation" src/ --limit 10
+```
+
+**Output example:**
+```
+## Symbol Search: "MemoryStore" (3 results)
+
+| Rel | Type | Name | File | Lines |
+|-----|------|------|------|-------|
+| 100% | 🏛️ class | MemoryStore | src/core/memory/memory-store.ts | L20-285 |
+| 60% | ⚡ function | MemoryStoreFactory | src/core/memory/index.ts | L10-15 |
+| 40% | 📌 variable | memoryStore | src/commands/memory.ts | L25-25 |
+```
+
+### 3. Unfold — Extract Specific Symbol Source
+
+Read just the implementation of a specific function or class:
+
+```bash
+heraspec explore unfold src/core/memory/memory-store.ts addObservation
+```
+
+**Output example:**
+```
+## method: addObservation
+*src/core/memory/memory-store.ts:L88-120 | ~800 tokens (vs ~71250 full file)*
+
+  addObservation(input: ObservationInput): Observation {
+    this.ensureOpen();
+    // ... full implementation
+  }
+```
+
+## Supported Languages
+
+| Language | Extensions | Symbols Detected |
+|----------|-----------|-----------------|
+| TypeScript | `.ts`, `.tsx` | class, interface, type, enum, function, method, variable |
+| JavaScript | `.js`, `.jsx`, `.mjs` | class, function, method, variable |
+| Python | `.py` | class, function, method, variable |
+| PHP | `.php` | class, interface, function |
+| Go | `.go` | struct, interface, func |
+| Rust | `.rs` | struct, trait, enum, fn |
+| Java | `.java` | class, interface, method |
+| C# | `.cs` | class, interface, method |
+| Vue | `.vue` | Same as TypeScript |
+| Svelte | `.svelte` | Same as TypeScript |
+
+## Workflow for AI Agents
+
+### Exploration Strategy
+
+```
+Need to understand a file?
+├── Step 1: heraspec explore outline <file>
+│   → See all functions, classes, interfaces (~1K tokens)
+├── Step 2: Identify relevant symbols from outline
+├── Step 3: heraspec explore unfold <file> <symbol>
+│   → Read just the relevant function (~400-2K tokens)
+└── Only read full file if you need comprehensive understanding
+
+Need to find where something is?
+├── heraspec explore search "<name>" <path>
+│   → Find symbol locations across codebase
+├── Then use unfold to read specific implementations
+└── Avoid grep-like full-text search when possible
+```
+
+### Key Principles
+
+1. **Outline first, read later**: Always check the outline before reading full files
+2. **Unfold specific symbols**: Don't read entire files when you only need one function
+3. **Search before browsing**: Find what you need by name rather than scanning directories
+4. **Skip node_modules, dist, .git**: Automatically excluded from search
+
+## Limitations
+
+- Uses regex-based parsing (not AST) — may miss some complex patterns
+- Symbol end-line detection is approximate (brace/indent counting)
+- Method detection within classes requires proper indentation
+- Does not handle dynamically generated code or macros