codymaster 4.4.4 → 4.5.1

package/skills/skill-creator-ultra/resources/scripts_guide.md

@@ -1,339 +0,0 @@
-# 🔧 Hướng Dẫn Sử Dụng Scripts
-
-> Hướng dẫn chi tiết cách dùng 8 công cụ Python trong Skill Creator Ultra.
-> Tất cả scripts đều chạy độc lập, **không cần cài thêm thư viện** — chỉ cần Python 3.8+.
-
----
-
-## 📋 Tổng quan
-
-| # | Script | Chức năng | Khi nào dùng |
-| --- | --- | --- | --- |
-| 1 | `validate_skill.py` | Kiểm tra SKILL.md hợp lệ | Sau khi viết/sửa skill |
-| 2 | `simulate_skill.py` | Mô phỏng chạy thử | Test skill trước deploy |
-| 3 | `skill_audit.py` | Audit 7 nguyên tắc → chấm S-tier | Muốn biết skill đạt mấy điểm |
-| 4 | `skill_stats.py` | Thống kê + Cognitive Load | Xem skill có quá phức tạp không |
-| 5 | `skill_export.py` | Export ra 6 nền tảng | Dùng skill trên Cursor, Claude... |
-| 6 | `skill_compare.py` | So sánh 2 phiên bản | Khi nâng cấp skill |
-| 7 | `skill_scaffold.py` | Tạo skeleton skill mới | Bắt đầu viết skill từ đầu |
-
----
-
-## ⚙️ Chuẩn bị
-
-```bash
-# Kiểm tra Python đã cài chưa
-python --version
-# Output: Python 3.8+ là OK
-
-# Di chuyển vào thư mục scripts
-cd path/to/skill-generator/scripts/
-```
-
----
-
-## 1. validate_skill.py — Kiểm tra hợp lệ
-
-**Mục đích:** Kiểm tra SKILL.md có đúng cấu trúc, đủ sections, đúng frontmatter.
-
-```bash
-# Kiểm tra 1 file SKILL.md
-python validate_skill.py /path/to/SKILL.md
-
-# Kiểm tra cả thư mục skill
-python validate_skill.py /path/to/my-skill/
-```
-
-**Output mẫu:**
-
-```
-✅ Frontmatter: Có name, description
-✅ Section Goal: Có
-✅ Section Instructions: Có
-✅ Section Examples: Có (3 ví dụ)
-⚠️ Section Constraints: Chỉ có 2 rules (khuyến khích ≥5)
-
-📊 Kết quả: 18/20 checks PASS — Grade: A
-```
-
-**Khi nào dùng:**
-
-- Sau khi viết xong SKILL.md
-- Sau khi AI tạo skill cho bạn
-- Trước khi deploy skill vào production
-
----
-
-## 2. simulate_skill.py — Mô phỏng chạy thử
-
-**Mục đích:** Đi qua từng bước trong Instructions, phát hiện bước mơ hồ.
-
-```bash
-python simulate_skill.py /path/to/my-skill/
-```
-
-**Output mẫu:**
-
-```
-🔄 Đang mô phỏng skill `price-quoter`...
-
-📌 Step 1: Đọc email khách hàng → ✅ Rõ ràng
-📌 Step 2: Tra bảng giá → ✅ Rõ ràng
-📌 Step 3: Xử lý chiết khấu → ⚠️ "Xử lý" mơ hồ → Gợi ý: "tính chiết khấu theo bảng"
-📌 Step 4: Soạn email → ✅ Rõ ràng
-
-📊 3/4 steps rõ ràng — 1 cần sửa lại
-```
-
-**Khi nào dùng:**
-
-- Sau validate — muốn biết AI có hiểu đúng Instructions không
-- Phát hiện từ mơ hồ trước khi deploy
-
----
-
-## 3. skill_audit.py — Audit 7 nguyên tắc ⭐
-
-**Mục đích:** Chấm điểm skill theo 7 Nguyên Tắc Hoàn Hảo (thang 100 điểm).
-
-```bash
-# Audit bình thường
-python skill_audit.py /path/to/my-skill/
-
-# Output dạng JSON (cho CI/CD)
-python skill_audit.py /path/to/my-skill/ --json
-
-# Chấm khắt khe (cần ≥85% mới PASS, thay vì ≥70%)
-python skill_audit.py /path/to/my-skill/ --strict
-```
-
-**7 nguyên tắc được chấm:**
-
-| # | Nguyên tắc | Điểm tối đa | Kiểm tra gì |
-| --- | --- | --- | --- |
-| 1 | Atomic Logic | 15 | Tên không có AND, description tập trung |
-| 2 | Semantic Trigger | 15 | Description đủ dài, có trigger phrases |
-| 3 | 4 Core Sections | 15 | Goal + Instructions + Examples + Constraints |
-| 4 | Show Don't Tell | 15 | ≥2 ví dụ có Input/Output |
-| 5 | Semantic Precision | 15 | Không dùng từ mơ hồ |
-| 6 | Error Recovery | 15 | Có xử lý lỗi, branching |
-| 7 | Black Box Scripts | 10 | Scripts có --help, --dry-run |
-
-**Thang xếp hạng:**
-
-| Điểm | Tier | Ý nghĩa |
-| --- | --- | --- |
-| 95-100 | 🏆 S-tier | Hoàn hảo |
-| 85-94 | ⭐ A-tier | Xuất sắc |
-| 70-84 | ✅ B-tier | Tốt |
-| 55-69 | ⚠️ C-tier | Cần cải thiện |
-| 40-54 | ❌ D-tier | Yếu |
-| < 40 | 💀 F-tier | Fail |
-
-**Khi nào dùng:**
-
-- Muốn biết skill đạt bao nhiêu điểm
-- Tìm điểm yếu cần cải thiện
-- Đảm bảo chất lượng trước khi chia sẻ
-
----
-
-## 4. skill_stats.py — Thống kê chi tiết
-
-**Mục đích:** Phân tích kích thước, cấu trúc, Cognitive Load Score.
-
-```bash
-# Thống kê bình thường
-python skill_stats.py /path/to/my-skill/
-
-# Output JSON
-python skill_stats.py /path/to/my-skill/ --json
-```
-
-**Output mẫu:**
-
-```
-📊 SKILL STATS — Phân tích thống kê
-  Skill: price-quoter
-
-📏 Kích thước:
-   Dòng:   250
-   Từ:     1,800
-   Ký tự:  12,500
-
-🏗️ Cấu trúc:
-   Sections (H1):    4
-   Steps:            8
-   Examples:         3
-   Constraints:      ✅ 5 (DO) + 🚫 4 (DON'T)
-
-🧠 Cognitive Load:
-   Score: 52/100 — 🟡 Trung bình
-
-📋 Phân bổ nội dung:
-   Goal                      ██░░░░░░░░░░░░░░░░░░ 8% (20 dòng)
-   Instructions              ████████████░░░░░░░░ 45% (112 dòng)
-   Examples                  ██████████░░░░░░░░░░ 35% (87 dòng)
-   Constraints               ████░░░░░░░░░░░░░░░░ 12% (31 dòng)
-```
-
-**Khi nào dùng:**
-
-- Xem skill có quá dài/ngắn không
-- Kiểm tra Cognitive Load (AI có bị overload không)
-- So sánh cấu trúc với skill tốt
-
----
-
-## 5. skill_export.py — Export đa nền tảng
-
-**Mục đích:** Chuyển SKILL.md sang format của nền tảng khác.
-
-```bash
-# Export sang 1 nền tảng
-python skill_export.py /path/to/my-skill/ --platform cursor
-python skill_export.py /path/to/my-skill/ --platform claude
-python skill_export.py /path/to/my-skill/ --platform windsurf
-python skill_export.py /path/to/my-skill/ --platform cline
-python skill_export.py /path/to/my-skill/ --platform copilot
-python skill_export.py /path/to/my-skill/ --platform openclaw
-
-# Export tất cả nền tảng cùng lúc
-python skill_export.py /path/to/my-skill/ --platform all
-
-# Chỉ định thư mục output
-python skill_export.py /path/to/my-skill/ --platform all --output ./exports/
-```
-
-**Output mẫu:**
-
-```
-📦 SKILL EXPORT — Chuyển đổi đa nền tảng
-  Skill: price-quoter
-
-  ✅ Cursor Rule
-     📄 exports/cursor/price-quoter.mdc
-  ✅ Claude Code Command
-     📄 exports/claude/price-quoter.md
-  ✅ Windsurf Rule
-     📄 exports/windsurf/price-quoter.md
-  ✅ OpenClaw System Prompt
-     📄 exports/openclaw/price-quoter.txt
-
-  📊 Đã export 4/4 nền tảng
-```
-
-**Khi nào dùng:**
-
-- Muốn dùng skill trên Cursor, Claude Code, Windsurf...
-- Chia sẻ skill cho bạn bè dùng nền tảng khác
-
----
-
-## 6. skill_compare.py — So sánh 2 phiên bản
-
-**Mục đích:** So sánh 2 phiên bản skill, đánh giá cải thiện hay tệ hơn.
-
-```bash
-# So sánh 2 thư mục skill
-python skill_compare.py /path/to/old-skill/ /path/to/new-skill/
-
-# So sánh 2 file SKILL.md
-python skill_compare.py old-SKILL.md new-SKILL.md
-
-# Output JSON
-python skill_compare.py ./v1/ ./v2/ --json
-```
-
-**Output mẫu:**
-
-```
-🔄 SKILL COMPARE — So sánh 2 phiên bản
-
-  Metric                 OLD      NEW  Thay đổi
-  ──────────────────────────────────────────
-  📏 Dòng               120      250  +130 (+108%)
-  📋 Steps                4        8  +4 (+100%)
-  🎯 Examples             1        3  +2 (+200%)
-  🛡️ Error handling       0        5  +5 (new!)
-
-  📋 Sections thêm:
-     + Constraints (31 dòng)
-
-  🎉 VERDICT: Phiên bản mới TỐT HƠN (5 cải thiện, 0 giảm)
-```
-
-**Khi nào dùng:**
-
-- Sau khi nâng cấp skill → xem thay đổi gì
-- Đánh giá bản v2 có tốt hơn v1 không
-
----
-
-## 7. skill_scaffold.py — Tạo skeleton mới
-
-**Mục đích:** 1 lệnh → tạo cả thư mục + files template cho skill mới.
-
-```bash
-# Tạo cơ bản (chỉ SKILL.md)
-python skill_scaffold.py price-quoter
-
-# Tạo kèm scripts/
-python skill_scaffold.py price-quoter --with-scripts
-
-# Tạo đầy đủ (SKILL.md + scripts/ + resources/ + examples/)
-python skill_scaffold.py price-quoter --full
-
-# Chế độ tương tác (hỏi từng bước)
-python skill_scaffold.py price-quoter --interactive
-
-# Chỉ định thư mục output
-python skill_scaffold.py price-quoter --full --output ./skills/
-```
-
-**Output mẫu:**
-
-```
-🧩 SKILL SCAFFOLD — Tạo skill mới
-
-  ✅ Đã tạo skill: price-quoter
-  📁 Vị trí: C:\skills\price-quoter
-
-  📂 Cấu trúc:
-  price-quoter/
-  ├── SKILL.md                — Bộ não chính
-  ├── scripts/helper.py       — Script hỗ trợ (template)
-  ├── resources/reference.md  — Tài liệu tham khảo
-  └── examples/happy_path.md  — Ví dụ mẫu
-
-  💡 Tiếp theo:
-     1. Mở SKILL.md và điền nội dung
-     2. Chạy: python skill_audit.py price-quoter/
-```
-
-**Khi nào dùng:**
-
-- Muốn tự viết skill bằng tay (không qua AI)
-- Cần skeleton chuẩn để bắt đầu
-
----
-
-## 🔄 Pipeline khuyến nghị
-
-Quy trình chuẩn khi tạo skill mới:
-
-```
-1. Tạo skeleton    → skill_scaffold.py my-skill --full
-2. Viết nội dung   → Mở SKILL.md, điền vào
-3. Validate        → validate_skill.py my-skill/
-4. Simulate        → simulate_skill.py my-skill/
-5. Audit           → skill_audit.py my-skill/
-6. Fix issues      → Sửa theo khuyến nghị audit
-7. Re-audit        → skill_audit.py my-skill/ --strict
-8. Export          → skill_export.py my-skill/ --platform all
-9. Deploy!         → Copy vào .gemini/antigravity/skills/
-```
-
----
-
-> 📦 *Generated by Skill Creator Ultra v1.0 — Được phát triển bởi Thân Công Hải + Anthropic*

package/skills/skill-creator-ultra/resources/skill_template.md

@@ -1,124 +0,0 @@
-# Skill Template — Mẫu chuẩn cho SKILL.md
-
-Sử dụng mẫu dưới đây khi sinh `SKILL.md` cho skill mới.
-Thay thế các phần `< >` bằng nội dung thực tế.
-
----
-
-## Tại sao mỗi section quan trọng?
-
-Trước khi dùng template, hãy hiểu **TẠI SAO** mỗi phần tồn tại:
-
-| Section | Vai trò | Nếu thiếu thì sao? |
-| --- | --- | --- |
-| `description` | AI đọc ĐẦU TIÊN để quyết định dùng skill hay không | AI sẽ **KHÔNG BAO GIỜ** kích hoạt skill |
-| `# Goal` | Giúp AI hiểu MỤC ĐÍCH cuối cùng, tránh đi lạc hướng | AI có thể làm đúng bước nhưng sai mục tiêu |
-| `# Instructions` | Hướng dẫn AI đi TỪNG BƯỚC chính xác | AI tự "đoán" cách làm → Dễ sai, mỗi lần khác nhau |
-| `# Examples` | Cho AI thấy INPUT/OUTPUT mẫu → Giảm hallucination ~40% | AI bịa format output, không consistent |
-| `# Constraints` | Rào chắn an toàn, ngăn AI làm điều KHÔNG ĐƯỢC phép | AI có thể xóa file, gửi sai data, etc. |
-
----
-
-## Template
-
-```markdown
----
-name: <tên-skill-kebab-case>
-description: |
-  <Dòng 1: Hành động chính + đối tượng + phương pháp/chuẩn>
-  <Dòng 2: Chi tiết bổ sung hoặc phạm vi áp dụng>
-  <Dòng 3: Kích hoạt khi user nói "...", "...", "...">
----
-
-# Goal
-
-<Một câu duy nhất mô tả mục tiêu cuối cùng.
-Công thức: [Động từ] + [kết quả cụ thể] + [để đạt lợi ích gì]
-Ví dụ: "Sinh báo cáo tuần chuyên nghiệp trong 2 phút thay vì 30 phút."
-Test: Nếu đọc Goal mà hỏi "rồi sao?" → chưa đủ tốt.>
-
-# Instructions
-
-<Liệt kê các bước logic CỤ THỂ, đánh số thứ tự.
-Mỗi bước phải ACTIONABLE — AI đọc xong biết phải LÀM GÌ.>
-
-1. <Bước 1 — Hành động cụ thể>
-   - <Chi tiết con nếu cần>
-   - Nếu <điều kiện A> → <hành động X>
-   - Nếu <điều kiện B> → <hành động Y>
-2. <Bước 2 — Hành động cụ thể>
-3. <Bước 3 — Hành động cụ thể>
-   - ⚠️ Nếu lỗi xảy ra → <cách xử lý>
-4. ✅ VERIFY: <Kiểm tra kết quả bước 3 đúng chưa>
-5. <Bước cuối — Output cho user>
-
-# Examples
-
-## Ví dụ 1: <Tên tình huống — Happy path (mọi thứ OK)>
-
-**Context:** <Bối cảnh ngắn — TẠI SAO user cần làm việc này>
-
-**Input:**
-<Dữ liệu đầu vào — CHÍNH XÁC, dùng dữ liệu THẬT, không placeholder>
-
-**Thought Process:** <OPTIONAL nhưng rất hiệu quả>
-- Nhận thấy X → Áp dụng quy tắc Y
-- Kiểm tra Z → Kết quả W
-
-**Output:**
-<Kết quả CHÍNH XÁC mong muốn — đây là cái user sẽ thấy>
-
----
-
-## Ví dụ 2: <Tên tình huống — Edge case (có vấn đề / thiếu data)>
-
-**Context:** <Bối cảnh>
-
-**Input:**
-<Dữ liệu đầu vào — trường hợp BẤT THƯỜNG>
-
-**Output:**
-<Kết quả — skill xử lý vấn đề thế nào>
-
-# Constraints
-
-<Chuyển đổi quy tắc người dùng nói → format chuẩn bên dưới.
-Luôn bắt đầu bằng emoji + từ khóa mạnh.>
-
-- 🚫 KHÔNG ĐƯỢC: <Quy tắc cấm 1 — cụ thể, rõ ràng, không mơ hồ>
-- 🚫 KHÔNG ĐƯỢC: <Quy tắc cấm 2>
-- ✅ LUÔN LUÔN: <Quy tắc bắt buộc 1>
-- ✅ LUÔN LUÔN: <Quy tắc bắt buộc 2>
-- ⚠️ CHÚ Ý: <Cảnh báo/ghi chú quan trọng>
-```
-
----
-
-## Quy tắc sử dụng template
-
-| Phần | Bắt buộc? | Yêu cầu tối thiểu | Ghi chú |
-| --- | --- | --- | --- |
-| `name` | Tùy chọn | kebab-case, ≤30 ký tự | Nếu bỏ, AI lấy tên thư mục |
-| `description` | **BẮT BUỘC** | ≥30 ký tự, có trigger words | Yếu tố #1 quyết định AI dùng skill |
-| `# Goal` | **BẮT BUỘC** | 1 câu duy nhất | Trả lời "Skill tồn tại để làm gì?" |
-| `# Instructions` | **BẮT BUỘC** | ≥3 bước, đánh số, actionable | Có rẽ nhánh + error handling |
-| `# Examples` | Khuyến khích mạnh | ≥2 ví dụ, có Input + Output | Happy path + Edge case |
-| `# Constraints` | Khuyến khích | ≥1 "KHÔNG ĐƯỢC" | Nghĩ: "Điều tệ nhất?" → Cấm nó |
-
----
-
-## Checklist trước khi finalize
-
-- [ ] Description trả lời 3 câu: Làm gì? Cho ai? Khi nào kích hoạt?
-- [ ] Goal đọc xong KHÔNG cần hỏi thêm "cụ thể hơn?"
-- [ ] Mỗi step trong Instructions có HÀNH ĐỘNG cụ thể (không phải "xử lý", "kiểm tra")
-- [ ] Logic rẽ nhánh viết TƯỜNG MINH (Nếu X → Y, Nếu Z → W)
-- [ ] Có ≥1 step VERIFY (kiểm tra kết quả)
-- [ ] Có ≥1 step error handling (xử lý khi lỗi)
-- [ ] Ví dụ 1: Happy path với dữ liệu THẬT
-- [ ] Ví dụ 2: Edge case (thiếu data / input lỗi / trường hợp đặc biệt)
-- [ ] Có ít nhất 1 "KHÔNG ĐƯỢC" trong Constraints
-- [ ] Không có từ mơ hồ (xử lý, kiểm tra, tối ưu, phù hợp, tốt)
-
-> Xem thêm: `resources/prompt_engineering.md` cho 10 nguyên tắc viết chuẩn xác.
-> Xem thêm: `resources/anti_patterns.md` cho 15 lỗi phổ biến cần tránh.