antigravity-ide 4.1.28 → 4.1.30

package/.agent/scripts/update-docs.js

@@ -0,0 +1,115 @@
+/**
+ * @script update-docs.js
+ * @version 4.2.0
+ * @layer internal
+ * @protocol unified-protocol-v1
+ * @description Tự động cập nhật số liệu thống kê trong các file tài liệu hướng dẫn.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Đường dẫn các file cần cập nhật
+const DOCS_FILES = {
+    README_VI: 'README.vi.md',
+    README_EN: 'README.md',
+    SKILLS_GUIDE: 'docs/SKILLS_GUIDE.vi.md',
+    RULES_GUIDE: 'docs/RULES_GUIDE.vi.md',
+    WORKFLOW_GUIDE: 'docs/WORKFLOW_GUIDE.vi.md'
+};
+
+// Đếm số lượng Skills
+function countSkills() {
+    const skillsDir = path.join(process.cwd(), '.agent', 'skills');
+    if (!fs.existsSync(skillsDir)) return 0;
+    
+    try {
+        const items = fs.readdirSync(skillsDir, { withFileTypes: true });
+        return items.filter(item => item.isDirectory()).length;
+    } catch (err) {
+        logError(err, "Failed to read skills directory");
+        return 0;
+    }
+}
+
+// Đếm số lượng Workflows
+function countWorkflows() {
+    const workflowsDir = path.join(process.cwd(), '.agent', 'workflows');
+    if (!fs.existsSync(workflowsDir)) return 0;
+    
+    const items = fs.readdirSync(workflowsDir);
+    return items.filter(item => item.endsWith('.md')).length;
+}
+
+// Đếm số lượng Rules
+function countRules() {
+    const rulesDir = path.join(process.cwd(), '.agent', 'rules');
+    if (!fs.existsSync(rulesDir)) return 0;
+    
+    const items = fs.readdirSync(rulesDir);
+    return items.filter(item => item.endsWith('.md')).length;
+}
+
+// Cập nhật số liệu trong README
+function updateCounts() {
+    const skills = countSkills();
+    const workflows = countWorkflows();
+    const rules = countRules();
+    
+    console.log('📊 Current Statistics:');
+    console.log(`   Skills: ${skills}`);
+    console.log(`   Workflows: ${workflows}`);
+    console.log(`   Rules: ${rules}`);
+    
+    return { skills, workflows, rules };
+}
+
+// Main function
+async function main() {
+    console.log('🚀 Auto-Update Documentation System\n');
+    
+    const stats = updateCounts();
+    
+    console.log('\n✅ Statistics collected successfully!');
+    console.log('💡 Tip: Use this data to update README.md and other docs manually for now.');
+    console.log('   Future versions will support automatic text replacement.');
+}
+
+function logError(error, context) {
+    const errorLogPath = path.join(process.cwd(), 'ERRORS.md');
+    const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 16);
+    const entry = `
+## [${timestamp}] - Update-Docs Script Failure
+
+- **Type**: Runtime
+- **Severity**: Low
+- **File**: \`.agent/scripts/internal/update-docs.js\`
+- **Agent**: Senior Documentation Engine
+- **Root Cause**: ${context}
+- **Error Message**: 
+  \`\`\`
+  ${error.message || error}
+  \`\`\`
+- **Fix Applied**: N/A
+- **Prevention**: Ensure file system permissions are correct
+- **Status**: Investigating
+
+---
+`;
+    fs.appendFileSync(errorLogPath, entry);
+}
+
+// Run if called directly
+if (require.main === module) {
+    try {
+        main().catch(err => {
+            logError(err, "Async main execution failed");
+            console.error(err);
+        });
+    } catch (err) {
+        logError(err, "Sync main execution failed");
+        console.error(err);
+    }
+}
+
+module.exports = { countSkills, countWorkflows, countRules, updateCounts };

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
 
 # 🛰️ AntiGravity IDE
-### *Advanced Edition • v4.1.28 Meta-Engine*
+### *Advanced Edition • v4.1.30 Meta-Engine*
 
 <!-- BADGES: Spaced & Tightly Wrapped to prevent Underlines -->
 <p align="center">
@@ -52,7 +52,7 @@ npx antigravity-ide [project-name]
 
 ---
 
-## ✨ The Premium Edge (v4.1.28)
+## ✨ The Premium Edge (v4.1.30)
 
 Why choose AntiGravity over standard AI wrappers?
 

package/README.vi.md

@@ -1,7 +1,7 @@
 <div align="center">
 
 # 🛰️ AntiGravity IDE
-### *Phiên bản Nâng cao • v4.1.28 Meta-Engine*
+### *Phiên bản Nâng cao • v4.1.30 Meta-Engine*
 
 <!-- BADGES: Spaced & Tightly Wrapped to prevent Underlines -->
 <p align="center">
@@ -52,7 +52,7 @@ npx antigravity-ide [ten-du-an]
 
 ---
 
-## ✨ Điểm khác biệt (Phiên bản v4.1.28)
+## ✨ Điểm khác biệt (Phiên bản v4.1.30)
 
 Tại sao nên chọn AntiGravity thay vì các AI wrapper thông thường?
 

package/cli/create.js

@@ -250,6 +250,12 @@ async function copyModularStructure(projectPath, config, rulesList, agentsList)
         await fs.copy(path.join(sourceAgentDir, '.shared'), path.join(destAgentDir, '.shared'), { filter });
     }
 
+    // 1b. Copy Root Concept Files (Architecture, Start Here, etc.) - FIX for v4.1.30
+    const rootFiles = fs.readdirSync(sourceAgentDir).filter(f => f.endsWith('.md') && f !== 'GEMINI.md'); // GEMINI.md is generated
+    for (const file of rootFiles) {
+        await fs.copy(path.join(sourceAgentDir, file), path.join(destAgentDir, file));
+    }
+
     // 2. Copy Rules (SELECTIVE)
     const rulesDest = path.join(destAgentDir, 'rules');
     fs.mkdirSync(rulesDest, { recursive: true });

package/cli/repair.js

@@ -48,6 +48,16 @@ async function repairProject(projectPath, options, config) {
         }
         spinner.succeed('Shared DNA synchronized to v' + require('../package.json').version);
 
+        // 1b. Restore Root Concepts (Architecture, Concepts, etc.) - FIX v4.1.30
+        const rootFiles = fs.readdirSync(sourceAgentDir).filter(f => f.endsWith('.md') && f !== 'GEMINI.md');
+        for (const file of rootFiles) {
+            const srcFile = path.join(sourceAgentDir, file);
+            const destFile = path.join(agentDir, file);
+            if (!fs.existsSync(destFile) || options.force) {
+                await fs.copy(srcFile, destFile, { overwrite: options.force });
+            }
+        }
+
         // 2. Restore/Update Rules
         spinner.start('Verifying Rules & Compliance...');
         const rulesSourceDir = path.join(sourceAgentDir, 'rules');

package/docs/AGENTS_GUIDE.vi.md

@@ -0,0 +1,61 @@
+# 🕵️ Hướng Dẫn Về "Hệ Thống Agent" (Digital Employees)
+
+> **Antigravity** không chỉ là công cụ, mà là một **Hệ điều hành Nhân sự AI**. Mọi Agent đều đã được nâng cấp lên chuẩn **Senior Principal Personnel** với khả năng phối hợp hệ sinh thái và kỷ luật vận hành tuyệt đối.
+
+---
+
+## 1. Biệt Đội Chuyên Gia (The Squad)
+
+Dưới đây là danh sách các nhân viên ảo sẽ phục vụ bạn:
+
+### 1. Nhóm Kỹ Thuật Cốt Lõi (Engineering Core)
+*   **`backend-specialist`**: Chuyên gia xây dựng API, System Architecture và xử lý Logic Server.
+*   **`frontend-specialist`**: Chuyên gia UI/UX, React/Next.js và tối ưu trải nghiệm người dùng.
+*   **`database-architect`**: Thiết kế Schema, tối ưu truy vấn SQL/NoSQL và Data Modeling.
+*   **`mobile-developer`**: Phát triển ứng dụng iOS/Android đa nền tảng (React Native/Flutter).
+*   **`devops-engineer`**: Quản lý Docker, CI/CD Pipeline, Kubernetes và hạ tầng Cloud.
+*   **`cloud-architect`**: Thiết kế kiến trúc đám mây (AWS/Azure), Serverless và Scalability.
+*   **`performance-optimizer`**: Chuyên gia tối ưu tốc độ tải trang, giảm độ trễ và Memory Leak.
+
+### 2. Nhóm Sản Phẩm & Chiến Lược (Product & Strategy)
+*   **`orchestrator`**: Tổng chỉ huy, điều phối các Agent khác phối hợp nhịp nhàng.
+*   **`product-manager`**: Quản lý lộ trình sản phẩm (Roadmap), ưu tiên tính năng.
+*   **`product-owner`**: Đại diện tiếng nói người dùng, định nghĩa yêu cầu nghiệp vụ (User Stories).
+*   **`project-planner`**: Lập kế hoạch thực thi, chia nhỏ task và ước lượng thời gian.
+
+### 3. Nhóm Chất Lượng & Bảo Mật (Quality & Security)
+*   **`security-auditor`**: Rà soát mã nguồn, phát hiện lỗ hổng bảo mật (OWASP) và tuân thủ đạo đức AI (Fabric).
+*   **`penetration-tester`**: Tấn công thử nghiệm (Red Team) để tìm điểm yếu hệ thống.
+*   **`quality-inspector`**: Kiểm tra tiêu chuẩn code (Linting, Convention) và độ ổn định.
+*   **`test-engineer`**: Viết và chạy các kịch bản kiểm thử (Unit/Integration Test).
+*   **`qa-automation-engineer`**: Tự động viết và chạy kịch bản kiểm thử E2E (Playwright MCP).
+
+### 4. Nhóm Hỗ Trợ & Phân Tích (Support & Analysis)
+*   **`documentation-writer`**: Soạn thảo tài liệu kỹ thuật, API Docs và Hướng dẫn sử dụng.
+*   **`seo-specialist`**: Tối ưu hóa công cụ tìm kiếm, Meta tags và cấu trúc nội dung.
+*   **`game-developer`**: Chuyên gia phát triển Logic Game, Physics và Đồ họa.
+*   **`explorer-agent`**: Thám hiểm các công nghệ mới, tìm kiếm giải pháp sáng tạo.
+*   **`code-archaeologist`**: "Nhà khảo cổ" chuyên đọc và giải thích các mã nguồn cũ (Legacy Code).
+*   **`debugger`**: Thám tử điều tra lỗi, phân tích Log và tìm nguyên nhân gốc rễ.
+
+### 🤝 Giao thức Phối hợp (Ecosystem Protocol)
+Mỗi Agent hiện nay không làm việc cô lập. Họ tuân thủ:
+- **Handoff**: Chuyển giao ngữ cảnh (API docs, PRD, Test logs) cho Agent tiếp theo.
+- **Socratic Gatekeeping**: Biết dừng lại hỏi ý kiến người dùng hoặc đồng nghiệp khi thấy rủi ro.
+- **DNA Linkage**: Luôn kiểm tra `GEMINI.md` và `MASTER_GUIDE.md` trước khi hành động.
+
+---
+
+## 2. Cách các Agent phối hợp
+
+Khác với chat thông thường, các Agent này biết **"chia sẻ não bộ"** cho nhau:
+
+1.  Bạn ra lệnh: *"Làm tính năng Đăng nhập"*.
+2.  **Project Planner** nhảy vào trước: *"Ok, cần trang Login, API Auth, và Bảng User"*.
+3.  Sau đó nó giao việc:
+    *   Viết UI -> Giao cho **Frontend Specialist**.
+    *   Viết API -> Giao cho **Backend Specialist**.
+    *   Tạo Bảng -> Giao cho **DB Architect**.
+4.  Cuối cùng **Test Engineer** sẽ vào kiểm tra xem mọi thứ có chạy đúng không.
+
+> **Điều này đảm bảo code của bạn luôn có cấu trúc chặt chẽ, không bị "đầu voi đuôi chuột".**

package/docs/CONTRIBUTING.vi.md

@@ -0,0 +1,55 @@
+# Hướng Dẫn Đóng Góp (Contributing)
+
+Cảm ơn bạn đã quan tâm đến dự án AntiGravity IDE! Chúng tôi luôn chào đón mọi sự đóng góp từ cộng đồng để cùng xây dựng một hệ sinh thái mã nguồn mở vững mạnh. 
+
+> [!NOTE]
+> Khi đóng góp, vui lòng tôn trọng bản quyền và các nguồn tham khảo (References) chính của dự án.
+
+## 🤝 Quy Tắc Ứng Xử
+Khi tham gia dự án, vui lòng giữ thái độ tôn trọng, lịch sự và chuyên nghiệp.
+
+## 🚀 Cách Thức Đóng Góp
+
+### 1. Báo Lỗi (Bug Report)
+-   Kiểm tra [Hướng Dẫn Khắc Phục Lỗi](./TROUBLESHOOTING.vi.md) xem lỗi đã biết chưa.
+-   Tạo Issue mới với tiêu đề rõ ràng.
+-   Mô tả các bước để tái hiện lỗi (Reproduce steps).
+
+### 2. Đề Xuất Tính Năng
+-   Tạo Issue gắn tag `enhancement`.
+-   Giải thích *tại sao* tính năng này lại hữu ích cho cộng đồng.
+
+### 3. Gửi Code (Pull Request)
+-   **Fork** dự án và tạo branch từ nhánh `develop`.
+-   **Tên Branch**: `feat/ten-tinh-nang` hoặc `fix/ten-loi`.
+-   **Commit Message**: Tuân thủ chuẩn [Conventional Commits](https://www.conventionalcommits.org/).
+    -   `feat: them workflow moi`
+    -   `fix: sua loi cai dat npm`
+    -   `docs: cap nhat tai lieu`
+-   **Kiểm thử**: Đảm bảo chạy `npm test` thành công.
+-   **Lint Code**: Chạy `npm run lint` để code sạch đẹp.
+
+### 4. Quy trình đăng ký Skill/Workflow mới
+Để một Skill hoặc Workflow mới xuất hiện trong Setup Wizard, bạn cần:
+1.  **Skill**: Thêm định dạng vào `cli/logic/skill-definitions.js`.
+2.  **Workflow**: Thêm tên vào `cli/logic/workflow-manager.js`.
+3.  **Lựa chọn (Scale)**: Cấu hình quy mô xuất hiện (Instant/SME/Creative) trong `cli/logic/manifest-manager.js`.
+
+## 🛠️ Cài Đặt Môi Trường Dev
+
+1.  Clone fork của bạn:
+    ```bash
+    git clone https://github.com/your-username/antigravity-ide.git
+    cd antigravity-ide
+    ```
+2.  Cài đặt thư viện:
+    ```bash
+    npm install
+    ```
+3.  Link để test lệnh CLI:
+    ```bash
+    npm link
+    ```
+
+## 📜 Bản Quyền
+Mọi đóng góp của bạn sẽ tuân theo giấy phép MIT License của dự án.

package/docs/FAQ.vi.md

@@ -0,0 +1,45 @@
+# ❓ Câu Hỏi Thường Gặp (FAQ)
+
+## Chung (General)
+
+### Q: AntiGravity IDE có phải là một phần mềm cài đặt vào máy không?
+**A**: Không hẳn. Nó hoạt động như một lớp bổ trợ (layer) thông minh chạy trên nền Node.js. Bạn có thể gọi nó bất cứ lúc nào qua `npx` mà không cần cài đặt nặng nề như Visual Studio hay Android Studio.
+
+### Q: Tôi có thể dùng nó với dự án có sẵn không (Brownfield Project)?
+**A**: **Có!** Hãy cd vào thư mục dự án của bạn và chạy `npx antigravity-ide`. Nó sẽ tự động phát hiện dự án và chỉ thêm bộ não `.agent/` vào mà không làm hỏng code cũ của bạn.
+
+### Q: Nó có miễn phí không?
+**A**: Mã nguồn AntiGravity là **Open Source**. Tuy nhiên, để AI hoạt động thông minh, bạn cần API Key của các mô hình LLM (như Gemini, GPT-4, Claude) - phần này có thể tốn phí tùy nhà cung cấp.
+
+---
+
+## Kỹ thuật (Technical)
+
+### Q: Tại sao lại cần Python?
+**A**: Chế độ "Advanced" sử dụng các thư viện Data Science và AI mạnh mẽ (như Pandas, Scikit-learn) chỉ có trên Python. Tuy nhiên, nếu bạn chỉ làm Web/App cơ bản (Standard Mode), bạn **KHÔNG** cần Python.
+
+### Q: 600+ Chiến thuật (AI Patterns) là gì?
+**A**: Đó không phải là 600 file, mà là tổng hợp các mẫu thiết kế (Design Patterns), Checklist kiểm thử, và Quy tắc bảo mật nằm *bên trong* 72 bộ Master Skills. Ví dụ: Skill "Mobile Design" chứa hơn 50 patterns về UX, Performance và Security cho iOS/Android.
+
+### Q: File `GEMINI.md` là gì?
+**A**: Đó là "CMND/CCCD" của AI Agent. Nó chứa danh tính, nhiệm vụ và các quy tắc ứng xử. AI sẽ đọc file này đầu tiên để biết "mình là ai".
+
+### Q: Tôi lỡ tay ghi đè file cấu hình, có lấy lại được không?
+**A**: Nếu chưa commit git -> Rất tiếc là không. Nếu đã dùng cờ `--force`, file cũ đã bị xóa vĩnh viễn. Hãy tập thói quen dùng Git!
+
+---
+
+## Vận hành (Operations)
+
+### Q: Làm sao để Agent biết tôi vừa sửa code?
+**A**: Agent hiện đại (như trong Cursor/Windsurf) thường tự đọc context. Nếu dùng CLI truyền thống, bạn cần nhắc Agent đọc lại file: "Đọc lại file X giúp tôi".
+
+### Q: Tôi muốn tạo Agent riêng chuyên về Game thì làm sao?
+**A**: Khi chạy `init`, ở bước chọn **Project Scale**, hãy chọn **Creative**. Sau đó chọn **AI Agent**. Hệ thống sẽ load bộ Skill `game-development` vào cho bạn.
+
+---
+
+## Đóng góp (Contribution)
+
+### Q: Tôi muốn thêm Skill mới cho cộng đồng?
+**A**: Tuyệt vời! Hãy Fork repo trên GitHub, tạo folder skill mới trong `sdk/skills/` và gửi Pull Request. Xem thêm [CONTRIBUTING.vi.md](./CONTRIBUTING.vi.md).

package/docs/GEMINI_USAGE.md

@@ -0,0 +1,294 @@
+# Using Antigravity IDE with Google Gemini
+
+**All 72 Master Skills (600+ AI Patterns) are fully compatible with Google Gemini AI!**
+
+## Why Antigravity IDE + Gemini?
+
+### 🎯 **Perfect Synergy**
+
+| Feature | Benefit for Gemini |
+|---------|-------------------|
+| **72 Master Skills** | Instant expertise in 8 domains (Standard v4.0.8) |
+| **Universal Format** | No vendor lock-in, works with any Gemini model |
+| **Large Context** | Gemini 1.5 Pro (2M tokens) loads multiple skills easily |
+| **Multimodal Support** | Skills cover text, vision, audio - all Gemini capabilities |
+| **Production-Tested** | Battle-tested with Claude/GPT, validated for Gemini |
+
+---
+
+## 🚀 Quick Start
+
+### 1. Create Project
+
+```bash
+npx antigravity-ide my-gemini-agent
+```
+
+### 2. Configure for Gemini
+
+```javascript
+// .agent/config.js
+export default {
+  model: {
+    provider: "google",
+    name: "gemini-2.0-flash-exp",
+    apiKey: process.env.GEMINI_API_KEY
+  },
+  skills: {
+    loadFrom: ".agent/skills",
+    categories: ["ai", "development", "data"]
+  }
+}
+```
+
+### 3. Use Skills in Code
+
+```javascript
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import fs from "fs";
+
+const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
+
+// Load skills
+const skills = fs.readdirSync(".agent/skills")
+  .map(dir => fs.readFileSync(`.agent/skills/${dir}/SKILL.md`, "utf-8"))
+  .join("\n\n---\n\n");
+
+const model = genAI.getGenerativeModel({ 
+  model: "gemini-2.0-flash-exp",
+  systemInstruction: `You are an AI agent with these skills:\n\n${skills}`
+});
+
+// Chat with skills!
+const chat = model.startChat();
+const result = await chat.sendMessage("Build a RAG system with TypeScript");
+```
+
+---
+
+## 📁 Resource Inheritance (NEW)
+
+This workspace is **Global-Powered**. Do not repeat standard rules/skills in local files.
+1.  **Primary Source**: `~/.antigravity/` (Global Master Skills & Rules)
+2.  **Secondary Source**: `.agent/` (Project-specific Overrides only)
+
+If a workflow/skill is found in Global, use it as the default.
+
+## 🧠 Recommended Skills for Gemini
+
+### Core AI Skills
+
+| Skill | Best For | Why for Gemini? |
+|-------|----------|----------------|
+| `ai-engineer` | LLM apps, RAG systems | Gemini-specific patterns |
+| `prompt-engineer` | Prompt optimization | Leverage Gemini's reasoning |
+| `rag-engineer` | Vector search, embeddings | Use Gemini's large context |
+| `langchain-architecture` | Agent frameworks | LangChain supports Gemini |
+| `agent-orchestration` | Multi-agent systems | Gemini Experimental 1206 |
+
+### Development Skills
+
+| Skill | Use Case |
+|-------|----------|
+| `nextjs-react-expert` | Frontend with structured outputs |
+| `typescript-pro` | Type-safe Gemini SDK usage |
+| `fastapi-pro` | Backend API for Gemini |
+| `python-pro` | Gemini Python SDK |
+
+### Data & Analytics
+
+| Skill | Use Case |
+|-------|----------|
+| `data-engineer` | Process data for Gemini |
+| `database-architect` | Design data stores |
+| `vector-database-engineer` | Embeddings + Gemini |
+
+---
+
+## 📊 Skill Categories Breakdown
+
+```
+Total: 27 Master Skills (600+ capabilities) across 8 categories
+
+Development (180+ skills)
+├── Frontend (React, Next.js, Vue, Svelte)
+├── Backend (Node.js, Python, Go, Rust)
+├── Mobile (React Native, Flutter, iOS, Android)
+└── Full-Stack
+
+Infrastructure (90+ skills)
+├── Cloud (AWS, Azure, GCP)
+├── Kubernetes & Containers
+├── CI/CD & GitOps
+└── IaC (Terraform, CDK)
+
+Database (60+ skills)
+├── SQL (PostgreSQL, MySQL)
+├── NoSQL (MongoDB, Redis)
+├── Vector DBs (Pinecone, Qdrant)
+└── Data Engineering
+
+AI & ML (70+ skills) ⭐ Perfect for Gemini!
+├── LLM Applications
+├── RAG Engineering
+├── Prompt Engineering
+├── Agent Orchestration
+└── ML Pipeline
+
+Security (80+ skills)
+├── Penetration Testing
+├── Security Auditing
+├── Vulnerability Scanning
+└── Compliance
+
+Design (40+ skills)
+├── UI/UX Patterns
+├── Mobile Design
+├── Accessibility
+└── Design Systems
+
+Business (20+ skills)
+├── SEO & Marketing
+├── Product Management
+├── Startup Analysis
+└── Content Strategy
+
+Tools (10+ skills)
+├── Automation
+├── CLI Development
+└── DevOps Tools
+```
+
+---
+
+## 🎓 Learning Path: Gemini + Skills
+
+### Beginner (Week 1)
+1. Load `clean-code` skill
+2. Load `ai-engineer` skill
+3. Build simple chatbot with Gemini
+
+### Intermediate (Week 2-3)
+1. Add `rag-engineer` skill
+2. Build knowledge base with Gemini + vector DB
+3. Use `prompt-engineer` to optimize
+
+### Advanced (Week 4+)
+1. Load `agent-orchestration` + `langgraph`
+2. Build multi-agent system
+3. Deploy with `deployment-engineer` skill
+
+---
+
+## 💡 Best Practices
+
+### Skill Loading Strategy
+
+**Option 1: Load All (Gemini Pro)**
+```javascript
+// Gemini 1.5 Pro has 2M token context
+// Can load multiple Master Skills!
+const allSkills = loadAllSkills(".agent/skills");
+```
+
+**Option 2: Selective (Gemini Flash)**
+```javascript
+// Gemini 2.0 Flash - load specific categories
+const skills = loadSkills(".agent/skills", {
+  categories: ["ai", "development", "data"]
+});
+```
+
+**Option 3: Dynamic (Best)**
+```javascript
+// Load skills based on task
+function loadRelevantSkills(task) {
+  if (task.includes("RAG")) return ["rag-engineer", "database-architect"];
+  if (task.includes("frontend")) return ["nextjs-react-expert", "typescript-pro"];
+  // ...
+}
+```
+
+### Performance Tips
+
+1. **Cache Loaded Skills** - Don't reload on every request
+2. **Use Gemini Flash** - For most tasks, Flash is enough
+3. **Selective Loading** - Load only needed skill categories
+4. **Structured Outputs** - Use Gemini's JSON mode with skills
+
+---
+
+## 🔧 Troubleshooting
+
+### Issue: "Gemini doesn't follow skill instructions"
+
+**Solution:** Use structured prompts
+```javascript
+const prompt = `
+Task: ${userTask}
+Available Skills: ${skillNames.join(", ")}
+Instructions: Use the [skill-name] skill to complete this task.
+
+Apply best practices from the loaded skills.
+`;
+```
+
+### Issue: "Context too long"
+
+**Solution:** Use skill categorization
+```javascript
+// Load only relevant categories
+const categories = detectCategories(userTask);
+const skills = loadSkillsByCategory(categories);
+```
+
+### Issue: "Skills conflict"
+
+**Solution:** Prioritize skills
+```javascript
+// Load skills in priority order
+const skills = [
+  "clean-code",        // Base principles
+  "ai-engineer",       // Core AI skill
+  "specific-skill"     // Task-specific
+];
+```
+
+---
+
+## 📚 Resources
+
+- **All Skills**: See [SKILLS.md](./SKILLS.md)
+- **Skill Source**: [antigravity-awesome-skills](https://github.com/Dokhacgiakhoa/antigravity-ide)
+- **Gemini Docs**: [Google AI Studio](https://ai.google.dev/)
+- **Examples**: Check `/lab` directory
+
+---
+
+## 🎯 Example: RAG with Gemini + Skills
+
+```javascript
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import { loadSkill } from "./utils/skillLoader.js";
+
+// Load relevant skills
+const ragSkill = loadSkill("rag-engineer");
+const dbSkill = loadSkill("database-architect");
+
+const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
+const model = genAI.getGenerativeModel({ 
+  model: "gemini-1.5-pro",
+  systemInstruction: `${ragSkill}\n\n${dbSkill}\n\nYou are a RAG expert.`
+});
+
+// Now Gemini can build production RAG systems!
+const result = await model.generateContent(
+  "Design a RAG system for 100M documents with hybrid search"
+);
+
+console.log(result.response.text());
+```
+
+---
+
+**Ready to build with Gemini + 27 Master Skills? Let's go! 🚀**