Trang 2.4: Giải thích cấu trúc thư mục .agent/ (Agents, Skills, Workflows, Rules, Scripts).

1. Tổng quan cấu trúc

Sau khi chạy lệnh ag-kit init, thư mục .agent/ được tạo ra trong dự án của bạn với cấu trúc như sau:

.agent/
├── ARCHITECTURE.md # Tài liệu kiến trúc tổng thể
├── AGENT_FLOW.md # Sơ đồ luồng hoạt động chi tiết
├── mcp_config.json # Cấu hình MCP servers (tích hợp bên thứ 3)
├── agents/ # 20 file cấu hình Specialist Agent
├── skills/ # 36 thư mục kiến thức chuyên sâu
├── workflows/ # 11 file quy trình làm việc
├── rules/ # Quy tắc hành vi toàn cục (GEMINI.md)
└── scripts/ # Script kiểm tra tổng thể (Python)

Mỗi thư mục có một vai trò cụ thể và rõ ràng. Dưới đây là giải thích chi tiết từng thành phần.

---

2. File ARCHITECTURE.md

Đây là "bản đồ hệ thống" dành cho AI.

Lưu ý: Không nên sửa file này trừ khi bạn thêm Agent hoặc Skill tùy chỉnh và muốn AI biết về chúng.

---

3. File AGENT_FLOW.md

Đây là "hướng dẫn vận hành" — mô tả chi tiết cách AI phải hành xử.

---

4. File mcp_config.json

Cấu hình tích hợp dịch vụ bên thứ 3 thông qua giao thức MCP (Model Context Protocol).

json
{
"mcpServers": {
"context7": { ... }, // Tích hợp Context7 (tài liệu thư viện real-time)
"shadcn": { ... } // Tích hợp ShadCN UI
// Có thể thêm các MCP server khác tại đây
}
}

Lưu ý: Để sử dụng, bạn cần copy file cấu hình này đến đúng vị trí mà Antigravity CLI nhận diện (thường là ~/.gemini/antigravity/mcp_config.json). Xem tài liệu Antigravity CLI để biết thêm chi tiết.

---

5. Thư mục agents/ — 20 Specialist Agents

Cấu trúc

.agent/agents/
├── orchestrator.md
├── frontend-specialist.md
├── backend-specialist.md
├── security-auditor.md
├── debugger.md
└── ... (16 file khác)

Vai trò

Mỗi file .md là cấu hình đầy đủ cho một Agent chuyên gia. File bao gồm:

• Phần YAML (giữa ---): name, description, tools, và quan trọng nhất là skills — danh sách các Skills Agent này được phép truy cập.
• Phần Markdown: Mô tả nhân cách, vai trò chuyên môn, các quy tắc hành vi riêng của Agent đó.

Ví dụ nội dung một file Agent

yaml
---
name: frontend-specialist
description: Frontend architect for modern web applications
tools: Read, Edit, Write, Bash
skills: react-best-practices, frontend-design, tailwind-patterns, web-design-guidelines
---


# Frontend Specialist


Bạn là một kiến trúc sư Frontend cấp cao với 10+ năm kinh nghiệm...


## Quy tắc bắt buộc
- Luôn ưu tiên Core Web Vitals (LCP, CLS, INP)
- Không dùng màu tím/violet trong thiết kế (Purple Ban)
- Áp dụng mobile-first responsive design
...

---

6. Thư mục skills/ — 36 Knowledge Modules

Cấu trúc

.agent/skills/
├── react-best-practices/
│ ├── SKILL.md # (Bắt buộc) Metadata và hướng dẫn chính
│ ├── sections/ # Hướng dẫn chi tiết theo từng phần
│ └── scripts/ # Script Python/Bash hỗ trợ (nếu có)
├── api-patterns/
│ └── SKILL.md
├── vulnerability-scanner/
│ ├── SKILL.md
│ └── scripts/
│ ├── security_scan.py
│ └── dependency_analyzer.py
├── frontend-design/
│ ├── SKILL.md
│ └── scripts/
│ ├── ux_audit.py
│ └── accessibility_checker.py
└── ... (32 thư mục khác)

Vai trò

• Mỗi thư mục là một gói kiến thức độc lập cho một lĩnh vực cụ thể.
• File 
  
  
  SKILL.md là bộ não của mỗi Skill, chứa các nguyên lý ra quyết định thay vì code mẫu cứng nhắc.
• Thư mục scripts/ (nếu có) chứa các công cụ thực thi Python/Bash để Agent có thể tự chạy kiểm tra.

Skills có script đặc biệt

Các Skills sau có kèm script Python để thực hiện kiểm tra tự động:

---

7. Thư mục workflows/ — 11 Slash Commands

Cấu trúc

.agent/workflows/
├── brainstorm.md
├── create.md
├── debug.md
├── deploy.md
├── enhance.md
├── orchestrate.md
├── plan.md
├── preview.md
├── status.md
├── test.md
└── ui-ux-pro-max.md

Vai trò

Mỗi file .md là định nghĩa đầy đủ cho một quy trình làm việc. File bao gồm:

• Phần YAML: description — mô tả ngắn gọn kích hoạt thứ gì trong IDE.
• Phần Markdown: Các bước thực hiện chi tiết, quyết định điều kiện, và các // turbo annotation (cho phép AI tự chạy lệnh an toàn ở bước đó).

Cách thêm Workflow tùy chỉnh

Bạn có thể thêm Workflow riêng bằng cách tạo file mới:

.agent/workflows/my-custom-workflow.md

Sau đó gọi bằng lệnh /my-custom-workflow trong chat với AI.

---

8. Thư mục rules/ — Quy tắc toàn cục

Cấu trúc

.agent/rules/
└── GEMINI.md # File quy tắc chính, luôn được áp dụng

Vai trò của GEMINI.md

Đây là file quan trọng nhất trong toàn bộ hệ thống. Nó chứa:

Tùy chỉnh: GEMINI.md có thể được chỉnh sửa để thêm các quy tắc riêng của dự án hoặc tổ chức. Ví dụ: thêm quy tắc về naming convention, ngôn ngữ bình luận code, hay các pattern cấm dùng.

---

9. Thư mục scripts/ — Master Validation Scripts

Cấu trúc

.agent/scripts/
├── checklist.py # Kiểm tra ưu tiên (P0→P6)
├── verify_all.py # Kiểm tra toàn diện (bao gồm Lighthouse, Playwright)
├── auto_preview.py # Tự động khởi chạy server xem trước
└── session_manager.py # Quản lý trạng thái phiên làm việc AI

So sánh hai main scripts

Cách chạy thủ công

bash
# Kiểm tra cơ bản (từ thư mục gốc dự án)
python .agent/scripts/checklist.py .


# Kiểm tra toàn diện (cần server đang chạy)
python .agent/scripts/verify_all.py . --url http://localhost:3000

---

10. Sơ đồ quan hệ giữa các thành phần

rules/GEMINI.md ← (1) AI đọc quy tắc đầu tiên
│
▼
ARCHITECTURE.md ← (2) AI hiểu toàn bộ hệ sinh thái
│
▼
agents/*.md ← (3) AI đóng vai Agent phù hợp
│
▼
skills/*/SKILL.md ← (4) Agent tải kiến thức cần thiết
│
▼
skills/*/scripts/*.py ← (5) Script chạy kiểm tra tự động
│
▼
scripts/checklist.py ← (6) Tổng hợp kết quả và báo cáo

Hiểu rõ cấu trúc này giúp bạn dễ dàng tùy chỉnh và mở rộng bộ kit theo nhu cầu dự án của mình mà không làm ảnh hưởng đến phần còn lại của hệ thống.