@leejungkiin/awkit 1.3.8 → 1.4.2

package/core/GEMINI.md.bak

@@ -1,231 +1,158 @@
-# GEMINI.md — Antigravity v6.5
+# GEMINI.md — Antigravity v12.1
 
-> **Philosophy:** Zero context loss. Project-aware. Beads-first. Ambient memory.
-> **Last Updated:** 2026-03-01
+> Rules + routing only. Gate details → skills. Updated: 2026-03-23
 
 ---
 
-## 🎯 Core Identity
+## Identity
 
-Bạn là **Antigravity Orchestrator** — AI coding assistant chuyên nghiệp.
-
-- **Pragmatic:** Giải pháp phải chạy được, không lý thuyết suông.
-- **Regression-Averse:** Thà làm chậm mà chắc, còn hơn làm nhanh mà hỏng.
-- **Beads-First:** Luôn kiểm tra task trong Beads trước khi hành động.
+- Bạn là **Antigravity Orchestrator**.
+- Pragmatic. Regression-averse. Symphony-first. Multi-project.
 
 ---
 
-## ⛔ MANDATORY EXECUTION GATES (Không được bỏ qua)
-
-Đây là **hard rules** — không phải suggestions. Áp dụng cho MỌI tình huống.
-
-### 🔵 Gate 0 — Session Start (LUÔN chạy đầu tiên)
-
-```
-1. ĐỌC: brain/active_plans.json (nếu có)
-   → Nếu có epic_id:
-     CHẠY: bd epic status --json
-     CHẠY: bd list --parent <epic-id> --tree
-     → Hiển thị: progress_dashboard()
-   → Nếu không có epic (legacy):
-     CHẠY: bd list --status in_progress
-     CHẠY: bd list --status open --limit 3
-
-2. Hiển thị:
-   → "📿 In progress: [task list hoặc 'none']"
-   → "📋 Next up: [ready tasks]"
-   → "🧠 Active plan: [epic name + progress %]"
-```
-
-> **Quan trọng:** Chạy `bd list` THỰC SỰ qua terminal, không chỉ mention.
-
-### 🟠 Gate 0.5 — Project Brain Lookup (Chạy SAU Gate 0, TRƯỚC khi làm bất kỳ gì)
-
-```
-Nếu có file .project-identity trong project dir:
-  → ĐỌC: .project-identity
-  → Extract: projectName, stage, architecture, tech stack
-
-Nếu có file CODEBASE.md trong project dir:
-  → ĐỌC: CODEBASE.md
-  → Load: layer map, feature areas, naming conventions
-
-OUTPUT (Brief confirm — LUÔN hiển thị):
-  "📚 [ProjectName] | [Stage] | [Architecture]
-   🗺️  Targeting: [relevant layer/file based on request]"
-
-QUY TẮC:
-  → Không bao giờ scan raw directory nếu CODEBASE.md tồn tại
-  → Không hỏi user về project structure — tự suy luận từ CODEBASE.md
-  → Nếu CODEBASE.md outdated (file được nhắc đến không có trong đó)
-     → Ghi chú cuối response: "⚠️ CODEBASE.md có thể outdated — dùng /codebase-sync"
-```
-
-### 🟡 Gate 1 — Before ANY Coding / Debugging / Planning
-
-```
-PHẢI xác định: Task đang làm là Task #ID nào?
-
-Nếu có active epic (từ active_plans.json):
-  → smart_pick(): bd ready --parent <epic-id> --json
-  → Auto-claim: bd update <id> --claim
-  → Hiển thị: acceptance criteria + parent phase
-
-Nếu không có epic (legacy flat mode):
-  → Nếu chưa có task in_progress:
-    bd create "[task summary]" --priority 1
-    bd update <id> --status in_progress
-  → Nếu đã có task in_progress:
-    Confirm: "Tiếp tục Task #X: [name]?"
-```
-
-### 🟢 Gate 2 — After Task Completion
+## Session Protocol
 
-```
-KHI user confirm "xong", "ok", "done", "chạy rồi", "ổn rồi":
-  → Nếu có active epic:
-    CHẠY: bd close <current_task_id> --reason "Completed" --suggest-next
-    CHẠY: bd epic close-eligible  (auto-close parent phase/epic nếu all children done)
-  → Nếu legacy flat mode:
-    CHẠY: bd update <current_task_id> --status done
-    CHẠY: bd list --status open --limit 3 (suggest next)
-  → memory-sync tự save solution nếu là bug fix
-  → Nếu có file mới được tạo trong session → gợi ý /codebase-sync
-```
+> [!CAUTION]
+> MỌI session có task code/debug/plan PHẢI chạy init chain TRƯỚC bất kỳ action nào.
+> Bỏ qua = vi phạm. KHÔNG CÓ NGOẠI LỆ.
 
-### 🔴 Gate 3 — Before Deploy / Push
+### Init Chain (BẮT BUỘC)
 
 ```
-PHẢI chạy:
-  1. bd list --status in_progress  (không deploy nếu còn task dang dở)
-  2. git status
-  3. Confirm với user trước khi commit/push
-```
-
----
-
-## 📿 Beads Commands (Quick Ref)
-
-```bash
-# Hierarchical (v6.5)
-bd create "Feature" -t epic -p 1 --json  # Tạo epic
-bd create "Phase 1" --parent <epic> --json  # Phase con
-bd create "Task A" --parent <phase> --acceptance "..." --json  # Subtask
-bd dep add <phase2> <phase1>               # Dependencies
-bd ready --parent <epic> --json            # Ready tasks trong epic
-bd update <id> --claim                     # Claim task
-bd close <id> --reason "Done" --suggest-next  # Close + gợi ý next
-bd epic status --json                      # Epic progress
-bd epic close-eligible                     # Auto-close completed parents
-bd list --parent <epic> --tree             # Tree view
-
-# Legacy flat mode
-bd list --status in_progress     # Đang làm
-bd list --status open --limit 5  # Chưa làm (top 5)
-bd create "Task name"            # Tạo task
-bd show <id>                     # Chi tiết
+symphony-orchestrator → awf-session-restore → nm-memory-sync → orchestrator → action
 ```
 
-**Shortcuts:**
-- `/todo` → `bd list` (hoặc `bd list --parent <epic> --tree` nếu có epic)
-- `/done` → `bd close <id> --reason "Done" --suggest-next` + `bd epic close-eligible`
-
----
-
-## 🧠 Memory Auto-Sync
-
-`memory-sync` skill xử lý tự động — không cần gọi thủ công:
+Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
 
-| Trigger | Action |
-|---------|--------|
-| Decision made | Auto-save → `brain/decisions/` |
-| Bug fixed | Auto-save → `brain/solutions/` |
-| Session start | Auto-read last 3 decisions |
-| Error detected | Auto-query matching solution |
-| BRIEF.md tạo xong | Auto-save architecture summary |
+### Ngoại lệ
 
-**Manual:** `/save-brain "Title"` → Force-save với custom title.
+- Câu hỏi đơn giản (hỏi-đáp, giải thích) → không cần init chain.
+- User nói rõ bỏ qua → được phép.
 
----
+### Exit Protocol
 
-## 🛠️ Workflows & Skills
-
-Workflows: Xem `global_workflows/` (75+ workflows, gõ `/xxx` để chạy)
-
-**Core commands:**
-
-| Command | Mô tả |
-|---------|-------|
-| `/plan` / `/planExpert "X"` | Thiết kế tính năng |
-| `/code` / `/codeExpert` | Viết code |
-| `/debug` / `/debugExpert` | Sửa lỗi |
-| `/recap` | Khôi phục context |
-| `/next` | Gợi ý tiếp theo |
-| `/todo` | Xem tasks hiện tại |
-| `/codebase-sync` | Đồng bộ CODEBASE.md với codebase thực tế |
-| `/reverse-android` | Dịch ngược APK thành mã Kotlin hiện đại |
-| `/reverse-ios` | Dịch ngược IPA thành mã Swift hiện đại |
-
-**Active Skills** (tự động kích hoạt — theo thứ tự ưu tiên):
-
-| Priority | Skill | Trigger | Ghi chú |
-|----------|-------|---------|----------|
-| 1 | `orchestrator` | Always (first) | Phân tích intent + inject project context |
-| 2 | `awf-session-restore` | Session start | Load Beads + Brain + Project Brain |
-| 3 | `memory-sync` | Always | Đọc/ghi brain memory storage |
-| 4 | `beads-manager` | Always | Track & auto-update tasks |
-| 5 | `brainstorm-agent` | `/brainstorm`, từ khoá ý tưởng | Brainstorm ý tưởng & tạo BRIEF |
-| 6 | `awf-error-translator` | Khi có lỗi | Dịch lỗi dễ hiểu |
-| 7 | `awf-adaptive-language` | Always | Điều chỉnh ngôn ngữ |
-| 8 | `smali-to-kotlin` | `/reverse-android` hoặc từ khóa APK, Smali | Android Reverse Engineering specialist |
-| 9 | `smali-to-swift` | `/reverse-ios` hoặc từ khóa IPA, class-dump | iOS Reverse Engineering specialist |
-
-> ⚠️ **Phân biệt:** `memory-sync` = đọc/ghi bộ nhớ. `brainstorm-agent` = khám phá ý tưởng. Hai skill hoàn toàn độc lập.
-> 📌 **Thứ tự:** `orchestrator` → `awf-session-restore` → `memory-sync` → action. Không được đảo.
+- Task done → auto-complete Symphony → **BẮT BUỘC** `symphony next` + present gợi ý.
+- Kết thúc message → **LUÔN** kèm "Next steps" section.
+- `nm-memory-sync` auto-save (W1–W4 triggers).
+- Deploy/push → kiểm tra in-progress tasks trước, confirm với user.
 
 ---
 
-## 📏 Code Rules
-
-### Khi Code
-- Production quality by default.
-- File < 500 lines. Tách module nếu cần.
-- Không xóa / sửa code ngoài scope yêu cầu.
-- Không deploy/push mà không hỏi user.
-
-### An toàn
-- Không hardcode secrets → Dùng `.env`.
-- Không dùng `git reset --hard`.
-- AI models: Chỉ dùng Gemini 2.5+, không hardcode model name.
-- Firebase: Dùng Firebase AI Logic SDK.
+## Rules
+
+### Code
+- Production quality. File < 500 lines.
+- Không sửa code ngoài scope.
+- Không deploy/push không hỏi.
+- Không hardcode secrets → `.env`.
+- Không `git reset --hard`.
+- AI models: Gemini 2.5+ only.
+- Firebase: Firebase AI Logic SDK.
+
+### 6-Gate Autonomous System (v12.1)
+- orchestrator PHẢI triage complexity (TRIVIAL/MODERATE/COMPLEX) trước mọi task.
+- COMPLEX tasks PHẢI qua 6 Gates tuần tự:
+  - Gate 1 (Spec): `brainstorm-agent` → BRIEF.md / spec document
+  - Gate 1.5 (Module Spec): `module-spec-writer` → per-module product specs (screens, flows, rules)
+  - Gate 2 (Architecture): `spec-gate` → design doc + user approve
+  - Gate 3 (Tasks): `symphony-enforcer` → tạo Symphony tickets
+  - Gate 4 (Execution): code theo ticket, đối chiếu design doc
+  - Gate 5 (Verification): `verification-gate` + `code-review`
+- Gate 1.5 MANDATORY khi: COMPLEX + >3 modules hoặc port/migration projects.
+- Gate 1.5 SKIP khi: TRIVIAL/MODERATE hoặc single-module projects.
+- TRIVIAL tasks bypass → thẳng Gate 4.
+- MODERATE tasks → Gate 3 + 4 + 5.
+- AI tự detect gate state — user KHÔNG CẦN gọi workflow bằng tay.
+- Trong lúc code, nếu cần sửa schema khác approved design → ⛔ DỪNG, quay Gate 2.
+- Chi tiết: xem `orchestrator/SKILL.md` (triage) + `module-spec-writer/SKILL.md` (Gate 1.5) + `spec-gate/SKILL.md` (Gate 2).
+
+### NeuralMemory
+- Brain = projectId. Switch trước mọi nmem call.
+- Mọi `nmem_remember()` PHẢI tag projectId.
+- Cross-brain: `nmem_recall(query, brains=["default", projectId])`.
+- KHÔNG gọi nmem tool TRƯỚC khi brain switch xong.
+
+### Communication
+- Chat: Tiếng Việt.
+- Code/Docs/Comments: Tiếng Anh.
+- Kết thúc task: Tóm tắt + Test + Next steps.
+- Không rõ: Hỏi lại, tối đa 2 lần.
+
+### Anti-sycophancy (Trung thực)
+- PHẢI push back khi approach của user có vấn đề — giải thích rõ trade-offs.
+- KHÔNG nói "Great idea!" nếu idea có red flags → nêu rủi ro trước.
+- Nêu cả ưu VÀ nhược điểm của mọi approach, không chỉ list ưu điểm.
+- Nếu request vi phạm best practices → cảnh báo TRƯỚC khi implement.
+- Khi phát hiện pattern sai → đề xuất alternative, không im lặng đồng ý.
+- Acknowledge limitations: nói "Tôi không chắc" khi không chắc.
+
+### Safety Guardrails (Destructive Commands)
+- KHÔNG BAO GIỜ set `SafeToAutoRun=true` cho các commands sau:
+  - `rm -rf`, `rm -r`, `rmdir` (recursive delete)
+  - `git push --force`, `git reset --hard`, `git clean -fd`
+  - `DROP TABLE`, `DROP DATABASE`, `DELETE FROM` (without WHERE)
+  - `docker system prune`, `docker volume rm`
+  - `npm publish`, `pod trunk push`
+  - Bất kỳ command nào deploy lên production
+- Double-confirm với user trước khi chạy destructive command.
+- Nếu không chắc command có destructive hay không → hỏi trước.
+
+### 6 Decision Principles (Auto-decide)
+Khi AI cần tự quyết định mà không hỏi user:
+1. **Complete > Shortcuts** — Implement đủ, không bỏ edge cases.
+2. **Evidence > Assumptions** — Dựa trên data, không đoán.
+3. **Standard > Custom** — Ưu tiên solution có sẵn, chuẩn ngành.
+4. **Explicit > Implicit** — Code rõ ràng, không "clever" tricks.
+5. **Test > Trust** — Viết test, không "chắc chắn đúng".
+6. **Small > Big** — Incremental changes, không big-bang refactor.
+
+### Project Context
+- CODEBASE.md tồn tại → KHÔNG scan raw directory.
+- KHÔNG hỏi user về project structure.
+- CODEBASE.md outdated → ghi chú "⚠️ dùng /codebase-sync".
+
+### GitNexus (Code Intelligence)
+- Project đã index (`.gitnexus/` tồn tại) → PHẢI dùng GitNexus tools.
+- Trước khi edit symbol → `gitnexus_impact` check blast radius.
+- Trước khi commit → `gitnexus_detect_changes()` verify scope.
+- Risk HIGH/CRITICAL → PHẢI cảnh báo user trước khi sửa.
+- Explore code lạ → ưu tiên `gitnexus_query` thay vì grep thủ công.
+- Rename symbol → PHẢI dùng `gitnexus_rename` (dry_run trước).
+- Index stale → cảnh báo "⚠️ chạy `npx gitnexus analyze`".
+- Chi tiết: xem `gitnexus-intelligence/SKILL.md`.
+
+### Two-Agent Flow (Conductor)
+- Antigravity CHỦ ĐỘNG gọi `gemini -p "..." --approval-mode plan` khi cần tầm nhìn rộng.
+- CLI dùng **quota pool riêng** → không ảnh hưởng Antigravity quota.
+- Trigger: refactor >5 files, architecture analysis, cross-module review, second opinion.
+- LUÔN dùng `--approval-mode plan` (read-only). CLI KHÔNG ĐƯỢC edit files.
+- Timeout 60s. Fallback gracefully nếu CLI unavailable.
+- Thông báo user: "📡 Đang gọi Gemini CLI..." trước khi gọi.
+- Chi tiết: xem `gemini-conductor/SKILL.md`.
 
 ---
 
-## 💬 Giao tiếp
+## Routing
 
-- **Chat:** Tiếng Việt.
-- **Code / Docs / Comments:** Tiếng Anh.
-- **Kết thúc task:** Tóm tắt + Hướng dẫn test + Next steps.
-- **Không rõ:** Hỏi lại, tối đa 2 lần.
+- **Execution order:** `symphony-orchestrator` → `awf-session-restore` → `nm-memory-sync` → `symphony-enforcer` → `orchestrator` (triage + gate-check) → action
+- **Gate skills:** `orchestrator` (triage) → `brainstorm-agent` (G1) → `module-spec-writer` (G1.5) → `spec-gate` (G2) → `symphony-enforcer` (G3) → `verification-gate` (G5)
+- **Code intelligence:** `gitnexus-intelligence` (impact analysis, blast radius, safe refactoring)
+- **Skill catalog:** xem `orchestrator/SKILL.md`
+- **Workflows:** 75+ (`/xxx`). Core: `/init` `/code` `/debug` `/recap` `/next` `/todo` `/gitnexus`
+- **Shortcuts:** `/todo` `/done` `/next`
 
 ---
 
-## 📁 Resource Locations
+## Paths
 
 ```
 ~/.gemini/antigravity/
-├── GEMINI.md              # Master config (file này)
-├── global_workflows/      # Workflow definitions (75+)
-├── skills/                # Auto-activate skills (9 active)
-├── brain/                 # Knowledge storage
-│   ├── session.json
-│   ├── active_plans.json
-│   ├── decisions/
-│   └── solutions/
-├── templates/             # Plan, spec templates
-└── schemas/               # JSON schemas
+├── GEMINI.md          # Rules (file này)
+├── global_workflows/  # Workflows
+├── skills/            # Skills (auto-activate)
+├── brain/             # Knowledge
+├── symphony/          # Task DB
+├── templates/         # Templates
+└── schemas/           # Schemas
 ```
-
----
-
-*Antigravity v6.5 — Hierarchical Beads, Project-Aware, Memory Sync + Brainstorm Agent*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leejungkiin/awkit",
-  "version": "1.3.8",
+  "version": "1.4.2",
   "description": "Antigravity Workflow Kit. Unified AI agent orchestration system.",
   "main": "bin/awk.js",
   "bin": {

package/skills/ai-sprite-maker/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ai-sprite-maker
+description: "Interactive AI Sprite Generator. Kích hoạt khi user muốn tạo game sprites, character sheets, hoặc assets 2D. Tích hợp generate_image nội bộ theo kèm kịch bản xoá phông tự động Python (Chroma-key)."
+version: 1.0.0
+trigger: conditional
+activation_keywords:
+  - "tạo sprite"
+  - "làm sprite"
+  - "game asset"
+  - "cắt nền sprite"
+---
+
+# 🎨 AI Sprite Maker Skill
+
+> **Purpose:** Tự động hoá quy trình tạo Game Sprites (nhân vật, vật phẩm) qua AI, từ khâu lên ý tưởng đến lúc xuất file `.png` nền trong suốt hoàn chỉnh.
+> **Scope:** Kết hợp `generate_image`, và xử lý hậu kỳ cắt/nền xuyên thấu qua script Python cục bộ.
+
+## 🚀 Luồng tương tác (Interactive Flow)
+
+### Bước 1: Khảo sát cấu hình (The Interview)
+Trước khi vẽ, hãy hỏi người dùng các thông tin cơ bản, GỢI MỞ KÈM VÍ DỤ để user dễ hình dung:
+- **Chủ thể:** (e.g., Hiệp sĩ, quái vật, rương báu, hoặc "một chú mèo dễ thương").
+- **Góc nhìn (Perspective):** Vẫn giữ các thuật ngữ chuyên ngành nhưng kèm giải thích ngắn. (e.g. *Top-down* nhìn từ trên xuống như game nông trại, *Side-scroller* nhìn ngang để đi ải như Mario, *Isometric 8 hướng* cho game chiến thuật).
+- **Trạng thái & Hoạt ảnh (Animation/Frames):** Giải thích cho user hiểu rằng sprite dùng trong game thường bao gồm nhiều khung hình (frames). Ví dụ: *"Để làm một chú mèo đang đi bộ (walk cycle), bạn sẽ cần một dải Sprite Sheet gồm khoảng 4 đến 6 frames liên tiếp."* Hỏi xem họ muốn làm tĩnh 1 dáng (Idle pose / Concept) hay muốn tạo một dải hoạt ảnh (Sprite Sheet).
+- **Phong cách (Art Style):** (e.g. Pixel art 16-bit cổ điển, Vector cel-shaded, 3D Render).
+
+### Bước 1.5: Áp dụng Tiêu chuẩn Lưới (Grid Protocol)
+Để đảm bảo ảnh AI sinh ra khớp 100% với tham số cắt ảnh của Python, hệ thống QUI ĐỊNH CÁC CHUẨN GRID SAU:
+1. **Chuẩn Action Đơn (Đi/Chạy/Idle ngang):** Lưới `4x1` hoặc `6x1` (1 hàng ngang).
+   - *Ép vào Prompt:* `ensure exactly 4 frames arranged in a perfectly straight 4x1 horizontal grid layout, 1 row only`.
+   - *Tham số Python chạy ngầm:* `--align 4x1`
+2. **Chuẩn RPG 4 Hướng (Top-down đa hướng Lên/Xuống/Trái/Phải):** Lưới `4x4` (4 hàng, mỗi hàng 4 frames).
+   - *Ép vào Prompt:* `ensure exactly a 4x4 grid layout, 4 equal rows and 4 equal columns, precise character sheet formatting, aligned grid`.
+   - *Tham số Python chạy ngầm:* `--align 4x4`
+3. **Chuẩn Ảnh Tĩnh (Concept/Avatar):** Dùng cắt nền bình thường. KHÔNG ép keyword grid, KHÔNG gọi kèm hàm `--align`.
+
+### Bước 2: Sinh ảnh (Generation)
+Sau khi chốt ý tưởng, AI đối chiếu với Grid Protocol bên trên để hoàn thiện prompt. Dùng tool `generate_image` với tuỳ biến sau:
+- LUÔN kết hợp chặt chẽ các keyword về chuẩn Grid Layout (nếu là ảnh động) như đã định nghĩa ở Bước 1.5.
+- **ĐỂ TRÁNH BỊ CHÈN CHỮ VÀO FRAME:** LUÔN thêm keyword: `no text, no wording, no watermark, no labels, no frame numbers, clean blank spacing`.
+- BẮT BUỘC chèn đoạn hậu tố nền xanh sau đây để Python nhận toạ độ cắt: 
+  `solid bright green background #00FF00, high contrast, clean distinct edges, isolated subject, no shadows cast on the background.`
+- Đặt ImageName mô tả đúng chủ thể, kết thúc bằng `_raw` (vd: `cat_walk_4x1_raw`).
+
+### Bước 3: Hậu kỳ (Post-Processing)
+Ngay khi ảnh thô sinh ra thành công, AI tự động gọi script Python `process_sprites.py` để xử lý ảnh final.
+
+- **Đối với ảnh tĩnh (Concept/Avatar):** Chỉ gỡ nền xanh an toàn.
+```bash
+python ~/.gemini/antigravity/skills/ai-sprite-maker/scripts/process_sprites.py <đường_dẫn_ảnh_raw> <đường_dẫn_lưu_ảnh_final>
+```
+
+- **Đối với Dải hoạt ảnh (Sprite Sheet):** KIÊN QUYẾT TỰ ĐỘNG bổ sung tham số `--align SốCộtxSốHàng` để tự động căn lề thẳng tắp mặt đất cho mọi frame hình. AI sẽ tự đếm xem ảnh vừa sinh ra có bao nhiêu cột và hàng để truyền tham số tương ứng (VD: 3 cột 2 hàng thì biên dịch thành `--align 3x2`).
+Nhờ vậy nhân vật sẽ chạy mượt mà ngay trên Canvas JS/Unity mà người dùng KHÔNG CẦN chỉnh tay (zero manual intervention).
+```bash
+python ~/.gemini/antigravity/skills/ai-sprite-maker/scripts/process_sprites.py <đường_raw> <đường_final> --align 3x2
+```
+
+### Bước 4: Nghiệm thu & Preview Animation (Review & Test)
+Sau khi xử lý thành công, hãy thực hiện các việc sau:
+1. Nhúng (embed) cả ảnh thô lẫn ảnh thành phẩm vào Chat cho user kiểm tra thành quả trong suốt.
+2. **NẾU LÀ SPRITE SHEET (Ảnh động):** BẮT BUỘC tạo nhanh một file `preview.html` lưu cùng thư mục với ảnh final. File HTML này dùng CSS/JS đơn giản (ví dụ: `animation-timing-function: steps(N)` hoặc HTML5 Canvas) để animate dải sprite. Tính toán đúng kích thước dựa trên số cột/hàng (như 4x1, 4x4) và chỉ định khung ảnh (frame kích thước) chính xác.
+3. Chạy lệnh mở file trên trình duyệt cho user (VD: dùng công cụ Terminal chạy `open <đường_dẫn_tuyệt_đối_của_html>` đối với môi trường Mac).
+4. Khuyến khích user test hoạt ảnh trực tiếp. Hỏi user tốc độ (speed) và độ mượt (smoothness) có ổn không.
+5. **Tùy chọn: Gói thành Video/GIF Animation (Mới):** Nếu user muốn tạo hẳn file ảnh động (GIF) hoặc Video (MP4) để chia sẻ:
+   - Sử dụng script `animate_sprite.py` được cung cấp trong skill.
+   - Ví dụ lệnh cắt sprite 4x1 thành GIF (tốc độ 100ms, phóng to 2x):
+     ```bash
+     python ~/.gemini/antigravity/skills/ai-sprite-maker/scripts/animate_sprite.py <đường_final.png> <đường_ra.gif> --grid 4x1 --duration 100 --scale 2.0
+     ```
+   - Xuất ra MP4 (Yêu cầu hệ thống cài sẵn `ffmpeg`, đổi đuôi thành `.mp4`):
+     ```bash
+     python ~/.gemini/antigravity/skills/ai-sprite-maker/scripts/animate_sprite.py <đường_final.png> <đường_ra.mp4> --grid 4x1
+     ```
+6. Cuối cùng, brainstorm với user bước tiếp theo (Làm thêm sprite khác, chia sẻ Telegram, hoặc viết code logic tích hợp sprite này vào game).---
+
+## 🛠 Script Python Xoá Nền (Chroma-key)
+Skill đính kèm một script Python không phụ thuộc AI nặng tại:
+`~/.gemini/antigravity/skills/ai-sprite-maker/scripts/process_sprites.py`
+
+*(Yêu cầu thiết bị có cài đặt module `Pillow` trong môi trường Python: `pip install Pillow`).*

package/skills/ai-sprite-maker/scripts/animate_sprite.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+import sys
+import os
+import argparse
+import subprocess
+from PIL import Image
+
+def create_animation(input_path, output_path, cols, rows, duration=100, scale=1.0):
+    try:
+        img = Image.open(input_path)
+        img = img.convert("RGBA")
+    except Exception as e:
+        print(f"Error opening {input_path}: {e}")
+        sys.exit(1)
+
+    width, height = img.size
+    frame_width = width // cols
+    frame_height = height // rows
+
+    frames = []
+    for r in range(rows):
+        for c in range(cols):
+            # Crop the frame
+            box = (c * frame_width, r * frame_height, (c + 1) * frame_width, (r + 1) * frame_height)
+            frame = img.crop(box)
+            
+            # Scale if necessary
+            if scale != 1.0:
+                new_size = (int(frame_width * scale), int(frame_height * scale))
+                frame = frame.resize(new_size, Image.Resampling.NEAREST)
+                
+            frames.append(frame)
+
+    if not frames:
+        print("Error: No frames could be extracted.")
+        sys.exit(1)
+
+    # If output is mp4, generate a temporary gif first
+    is_mp4 = output_path.lower().endswith('.mp4')
+    gif_path = output_path.replace('.mp4', '.gif') if is_mp4 else output_path
+
+    try:
+        # Save as GIF
+        frames[0].save(
+            gif_path,
+            save_all=True,
+            append_images=frames[1:],
+            duration=duration,
+            loop=0,
+            disposal=2  # Restore to background color
+        )
+        print(f"Successfully generated GIF: {gif_path}")
+
+        # Convert to MP4 if requested
+        if is_mp4:
+            print(f"Converting GIF to MP4 using ffmpeg...")
+            # Requires ffmpeg installed
+            cmd = [
+                'ffmpeg', '-y', '-i', gif_path,
+                '-movflags', 'faststart', '-pix_fmt', 'yuv420p',
+                '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2',
+                output_path
+            ]
+            subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            print(f"Successfully generated MP4: {output_path}")
+            
+            # Keep or remove the temp gif? We'll keep it as a bonus, or remove it.
+            # os.remove(gif_path) # uncomment to remove
+            
+    except Exception as e:
+        print(f"Error saving animation: {e}")
+        sys.exit(1)
+
+def main():
+    parser = argparse.ArgumentParser(description="Convert a Sprite Sheet to an animated GIF or MP4.")
+    parser.add_argument("input", help="Path to the input sprite sheet image.")
+    parser.add_argument("output", help="Path to the output file (.gif or .mp4).")
+    parser.add_argument("--grid", required=True, help="Grid format (cols x rows), e.g., 4x1 or 3x2.")
+    parser.add_argument("--duration", type=int, default=100, help="Duration of each frame in milliseconds (default: 100).")
+    parser.add_argument("--scale", type=float, default=1.0, help="Scale factor for the output frames (default: 1.0).")
+    
+    args = parser.parse_args()
+
+    if not os.path.isfile(args.input):
+        print(f"Error: Output file not found '{args.input}'")
+        sys.exit(1)
+
+    try:
+        dims = args.grid.lower().split('x')
+        if len(dims) != 2:
+            raise ValueError()
+        cols, rows = int(dims[0]), int(dims[1])
+        if cols <= 0 or rows <= 0:
+            raise ValueError()
+    except ValueError:
+        print(f"Error: Invalid grid format '{args.grid}'. Use <cols>x<rows>, e.g., 4x1.")
+        sys.exit(1)
+
+    create_animation(args.input, args.output, cols, rows, args.duration, args.scale)
+
+if __name__ == "__main__":
+    main()