MCP, Rules, Skills & Workflows trong Antigravity IDE

Hướng dẫn đầy đủ về bốn cơ chế mở rộng của Antigravity — từ khái niệm đến cách phối hợp trong dự án SwiftUI thực tế.

Mục lục

1. Tổng quan — bốn cơ chế mở rộng
2. MCP — bàn tay của agent
3. Rules — luật hành vi
4. Skills — chuyên gia theo yêu cầu
5. Workflows — người điều phối
6. So sánh và điểm giao
7. Mô hình phối hợp
8. Thiết lập thực tế cho SwiftUI
9. Những điều cần biết

1. Tổng quan

Antigravity cung cấp bốn cơ chế để mở rộng khả năng của AI agent: MCP, Rules, Skills, và Workflows. Chúng không phải là bốn cách khác nhau để làm cùng một việc — mỗi cơ chế có vai trò riêng biệt và cách phối hợp cụ thể.

Phép ẩn dụ toàn cảnh: Tưởng tượng một đội phẫu thuật: MCP là bộ dụng cụ, Rules là giao thức y tế phải luôn tuân thủ, Skills là chuyên khoa của từng bác sĩ, Workflows là quy trình phẫu thuật được lên kế hoạch trước.

2. MCP — Model Context Protocol

MCP là giao thức chuẩn mở cho phép AI agent kết nối với công cụ bên ngoài theo cách nhất quán. Trong Antigravity, agent sử dụng MCP để thực sự làm việc — không chỉ đề xuất code.

Hai kiến trúc triển khai

Local stdio — phổ biến nhất cho iOS/macOS dev. Antigravity spawn một child process trên máy, giao tiếp qua stdin/stdout. Không cần server từ xa, không cần internet:

Antigravity IDE  ──stdio──▶  npx xcodebuildmcp  ──▶  xcodebuild / Xcode
(MCP client)                 (MCP server, local)       (actual tool)

Remote URL — dùng cho cloud services. Giao tiếp qua HTTP/SSE với server thật ở xa:

Antigravity IDE  ──HTTP/SSE──▶  gcal.mcp.claude.com  ──▶  Google API
(MCP client)                    (MCP server, remote)        (external service)

Các MCP thiết yếu cho SwiftUI

Cấu hình mcp_config.json

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    },
    "xcode-native": {
      "command": "xcrun",
      "args": ["mcpbridge"]
    },
    "apple-docs": {
      "command": "npx",
      "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
    },
    "swift-mcp": {
      "command": "npx",
      "args": ["-y", "swift-mcp"]
    }
  }
}

⚠️ Lưu ý: Antigravity không hỗ trợ ${workspaceFolder}. Luôn dùng đường dẫn tuyệt đối trong mọi cấu hình MCP.

Cách kích hoạt

Sau khi cấu hình, agent tự động gọi tool khi cần. Bạn cũng có thể gọi thủ công bằng @ten-mcp trong chat, hoặc cài qua MCP Store (... → MCP Servers → MCP Store).

3. Rules — Luật hành vi

Rules là văn bản hướng dẫn được inject vào context của agent. Chúng định hình cách agent viết code, kiến trúc, và style mà không cần nhắc lại mỗi lần.

Ba loại trigger

always_on — Inject vào context mọi lúc, dù hỏi gì. Dùng thật tiết kiệm, chỉ cho quy tắc cực kỳ quan trọng (ví dụ: "không bao giờ commit secret key"):

# .agent/rules/swift-standards.md
---
trigger: always_on
---
# Quy tắc Swift toàn cục
Luôn dùng Swift 6 concurrency.
Không dùng DispatchQueue trực tiếp.

model_decision — Agent đọc description và tự quyết định có load rule không dựa trên yêu cầu hiện tại. Đây là cách dùng phổ biến nhất:

# .agent/rules/mvvm-rules.md
---
trigger: model_decision
description: Quy tắc kiến trúc MVVM cho SwiftUI.
             Dùng khi tạo ViewModel, state management.
---
# MVVM Rules
Dùng @Observable thay ObservableObject.
Không import SwiftUI trong ViewModel.

file_match — Chỉ bật khi người dùng đang mở file khớp pattern:

# .agent/rules/swift-files.md
---
trigger: file_match
glob: "**/*.swift"
---
# Swift file rules
Dùng guard let cho early returns.
Ưu tiên struct trước class.

Model Decision — cơ chế thông minh: Khi bạn hỏi về ViewModel, agent thấy description khớp và load rule. Khi hỏi về build error, agent bỏ qua — tiết kiệm context window. Đây là phiên bản nhẹ hơn của Skills: chỉ text, không có scripts hay assets.

Vị trí file

4. Skills — Chuyên gia theo yêu cầu

Skills là gói kiến thức chuyên sâu được load vào context chỉ khi cần. Agent đọc metadata của tất cả skills, rồi tự quyết định load cái nào dựa trên intent của người dùng — không cần slash command, không cần mention tên.

Cấu trúc thư mục

.agent/skills/
└── mvvm-swiftui/
    ├── SKILL.md            ← bắt buộc, brain của skill
    ├── scripts/
    │   └── gen_viewmodel.sh    ← script tùy chọn
    └── resources/
        └── templates/          ← template tùy chọn

Ví dụ SKILL.md

---
name: mvvm-swiftui
description: Kiến trúc MVVM cho SwiftUI với @Observable,
             SwiftData, và async/await. Dùng khi tạo
             ViewModel, state management, data flow.
---

# MVVM SwiftUI Skill

## ViewModel pattern
- Dùng @Observable macro (không ObservableObject)
- Không import SwiftUI trong ViewModel
- Chỉ import Foundation và domain types
- Mark class với @MainActor nếu cần async work

## State management
- @State: local UI state trong View
- @Bindable: truyền ViewModel vào child View
- Environment: dependency injection toàn app

## Ví dụ chuẩn

```swift
@Observable
class LoginViewModel {
    var email = ""
    var password = ""
    var isLoading = false

    private let authService: AuthServiceProtocol

    init(authService: AuthServiceProtocol) {
        self.authService = authService
    }

    func login() async { ... }
}

> **Progressive Disclosure:** Mỗi session, Antigravity chỉ load *metadata* (name + description) của tất cả skills — không phải toàn bộ nội dung. Khi bạn hỏi về MVVM, agent mới load đầy đủ `SKILL.md`. Điều này giữ context window gọn, tránh "tool bloat".

### Skills có thể làm gì ngoài kiến thức?

Khi có thư mục `scripts/`, agent có thể thực thi script bash/python để thực hiện hành động thực tế — đọc schema database, gọi API nội bộ, generate file từ template. Đây là điểm khác biệt lớn với Rules (chỉ là text).

### Vị trí file

| Phạm vi | Đường dẫn |
|---|---|
| Global (tất cả project) | `~/.gemini/antigravity/skills/` |
| Per-workspace | `.agent/skills/` |

---

## 5. Workflows — Người điều phối

Workflows là chuỗi bước có thứ tự cố định, được kích hoạt khi người dùng gõ slash command. Chúng đóng vai trò orchestrator — điều phối Skills, MCP tools, và lệnh terminal.

### Bốn cú pháp cốt lõi (AgentKit 2.0)

| Cú pháp | Chức năng | Ghi chú |
|---|---|---|
| `// turbo 'lệnh'` | Chạy lệnh terminal tự động, không hỏi | Không có `turbo` → agent hỏi trước |
| `// run workflow: name` | Gọi sub-workflow | Sub-workflow vẫn chạy độc lập được |
| `// parallel … // end parallel` | Chạy các bước đồng thời | Dùng cho bước độc lập nhau |
| `// if [điều kiện] … // end if` | Rẽ nhánh có điều kiện | Agent đánh giá ở runtime |

### Ví dụ workflow đầy đủ

```markdown
---
description: CI pipeline cho SwiftUI — lint, test, build, deploy
---

1. Resolve Swift packages // turbo 'swift package resolve'

// parallel
2. Chạy SwiftLint // turbo 'swiftlint lint'
3. Chạy unit tests // turbo 'xcodebuild test -scheme MyApp'
// end parallel

// if có lỗi lint hoặc test fail
4. Dừng và báo cáo lỗi chi tiết
// end if

5. Dùng mvvm-swiftui skill để review ViewModel trong diff

// run workflow: build-archive

// if branch là main
// run workflow: publish-testflight
// end if

Vị trí file

6. So sánh và điểm giao

Bảng so sánh

Điểm giao và cách phân biệt

Skills và Workflows đều có thể chứa các bước tuần tự. Ranh giới nằm ở hai trục:

Ai kích hoạt?

• Người dùng chủ động gọi → Workflow
• Agent tự phát hiện → Skill

Nội dung là gì?

• "Cách tư duy, pattern, kiến thức" → Skill
• "Chuỗi lệnh cụ thể, thứ tự cứng" → Workflow

⚠️ Dấu hiệu cần tách ra: Nếu bạn đang viết lệnh terminal trong Skill, hoặc viết kiến thức MVVM dài trong Workflow — đó là dấu hiệu cần tách ra đúng chỗ.

7. Mô hình phối hợp

Chiều orchestration được thiết kế một chiều: Workflow gọi Skill, không phải ngược lại. Đây là thiết kế có chủ đích — Skill là chuyên gia thụ động, không phải actor điều phối.

Luồng chính thức:
Workflow  ──gọi──▶  Skill A          ✓ chính thức
Workflow  ──gọi──▶  Skill B          ✓ chính thức
Workflow  ──gọi──▶  Workflow          ✓ qua // run workflow:
Skill     ──chạy──▶ script.sh         ✓ chính thức

Không chính thức (workaround):
Skill     ──"gợi ý"──▶ Workflow       △ semantic, agent có thể không làm theo

Best practice: Workflow là orchestrator, Skill là specialist

# .agent/workflows/ship-feature.md
---
description: Ship một feature hoàn chỉnh — review, build, publish
---

1. Kiểm tra không có uncommitted changes // turbo 'git status'

// parallel
2. Lint và format // turbo 'swiftlint lint && swift-format .'
3. Chạy test suite // turbo 'xcodebuild test'
// end parallel

4. Dùng mvvm-swiftui skill để review ViewModel mới
5. Dùng accessibility-audit skill để kiểm tra View mới

// if tất cả passed
// run workflow: build-archive
// run workflow: publish-testflight
// end if

Khi nào dùng cái gì

8. Thiết lập thực tế cho SwiftUI

Cấu trúc thư mục đề xuất

project-root/
├── .agent/
│   ├── rules/
│   │   ├── swift-standards.md      ← always_on: Swift 6, async/await
│   │   ├── mvvm-rules.md           ← model_decision: MVVM patterns
│   │   └── swift-files.md          ← file_match: **/*.swift
│   │
│   ├── skills/
│   │   ├── mvvm-swiftui/           ← @Observable, ViewModel, state
│   │   ├── swiftdata-patterns/     ← SwiftData, migrations
│   │   ├── swift-concurrency/      ← async/await, actors
│   │   └── accessibility-audit/    ← VoiceOver, Dynamic Type
│   │
│   └── workflows/
│       ├── scaffold.md             ← /scaffold: tạo View + VM + Tests
│       ├── review.md               ← /review: lint + MVVM check
│       ├── build-archive.md        ← /build-archive
│       ├── publish-testflight.md   ← /publish-testflight
│       └── ci.md                   ← /ci: gọi review + build + publish
│
└── mcp_config.json                 ← XcodeBuildMCP, Apple Docs, swift-mcp

Workflow /scaffold — ví dụ thực tế

---
description: Tạo SwiftUI View + ViewModel + Preview + Tests cho một feature mới
---

1. Hỏi tên feature và mô tả ngắn (nếu chưa có trong prompt)

2. Dùng mvvm-swiftui skill để thiết kế ViewModel trước khi code

// parallel
3. Tạo {FeatureName}ViewModel.swift trong Models/
4. Tạo {FeatureName}View.swift trong Views/
// end parallel

5. Tạo {FeatureName}Tests.swift với ít nhất 3 test cases

6. Build để kiểm tra compile // turbo 'xcodebuild build -scheme MyApp'

// if build thất bại
7. Phân tích lỗi và fix tự động
// end if

Workflow /review — tích hợp skill vào pipeline

---
description: Code review SwiftUI trước khi merge — lint, MVVM, accessibility
---

// parallel
1. Chạy SwiftLint // turbo 'swiftlint lint'
2. Build kiểm tra compile // turbo 'xcodebuild build'
// end parallel

3. Dùng mvvm-swiftui skill để đánh giá ViewModel trong diff
4. Dùng accessibility-audit skill để kiểm tra View mới

5. Tổng hợp và report những vấn đề cần fix theo mức độ ưu tiên

9. Những điều cần biết

Workflow không deterministic

Workflow là instruction cho LLM, không phải bash script. Agent có thể diễn giải khác đi tùy context. Khi cần kết quả chính xác, dùng // turbo với lệnh cụ thể thay vì instruction tự nhiên mơ hồ.

❌ Mơ hồ:

3. Kiểm tra xem code có vấn đề gì không

✅ Cụ thể:

3. Chạy SwiftLint và báo cáo violations // turbo 'swiftlint lint --reporter json'

Workflow không có memory giữa các lần chạy

Mỗi lần gõ /ten-workflow là session mới hoàn toàn. Agent không nhớ lần trước kết quả ra sao, lỗi gì đã xảy ra. Nếu muốn giữ context, lưu vào file trong project hoặc truyền qua prompt.

// turbo và quyền tự chủ

Không có // turbo → agent dừng hỏi bạn trước khi chạy lệnh. Có // turbo → agent tự động thực thi. Khuyến nghị: bắt đầu không có turbo cho tất cả bước quan trọng cho đến khi bạn tin tưởng workflow.

Rules: dùng always_on thật ít

always_on inject rule vào mọi request, kể cả khi không liên quan — tốn token, tăng latency. Ưu tiên model_decision với description rõ ràng. Agent đủ thông minh để tự chọn đúng.

Skills là "living documents"

Khi skill không hoạt động đúng, đừng fix thủ công — nhờ agent tìm giải pháp rồi cập nhật SKILL.md. Skill sẽ học từ lần sửa đó và không lặp lại sai lầm tương tự.

Tóm lại

MCP         → Tool ngoài: XcodeBuildMCP, Apple Docs MCP
Rules       → "Luôn dùng @Observable, async/await, guard let"
Skills      → mvvm-swiftui/ (load khi hỏi về ViewModel/state)
Workflows   → /scaffold, /review, /ci, /ship-feature