Cài đặt và lần chạy đầu

Cuối tutorial này, skill flow đã được cài vào agent home, agent đã restart, và harness đã trả về trạng thái, một việc kế tiếp, hoặc kết quả gate.

Thời gian: một lệnh, một restart, rồi một kiểm tra cơ học. Phần đào sâu tùy chọn (hai số version và transcript gate từ chối) mất khoảng mười phút — đó là phần thêm, không phải mức bắt buộc.

Trước khi bắt đầu

Cần Node.js 22.14 trở lên và một coding agent được hỗ trợ (Claude Code, Codex CLI, Cursor, Antigravity, hoặc Agents home). Khi chạy, skill còn cần bash — trên Windows nghĩa là Git Bash. python3 được khuyến nghị nhưng không bắt buộc: thiếu nó thì gate vẫn chạy, chỉ lớp bền vững SQLite tắt.

Bước 1 — chạy installer

npx @manhquy/flow-skill@latest

Dùng @latest cho skill v0.34.4 (installer 0.7.11). Lệnh đứng một mình npx @manhquy/flow-skill có thể lấy từ cache npx và âm thầm chạy lại bản cũ.

Ba việc sẽ xảy ra:

npm tải installer GA hiện tại.
Installer hiển thị danh sách multi-select tương tác, gồm các agent mà nó nhận diện được trên máy.
Nó copy cây thư mục skill vào mỗi home bạn chọn, ví dụ ~/.claude/skills/flow.

Chọn agent bạn thực sự dùng. Chạy lại lệnh sau để thêm agent khác.

Bước 2 — restart agent

Skill là các file trên máy; agent đọc thư mục đó lúc khởi động. Chưa restart thì agent chưa nhận ra skill tồn tại.

Agent	Sau restart
Claude Code	gõ `/flow`
Codex CLI	restart một lần, rồi gõ `$flow`
Cursor / Agents home	reload tool, mở skill flow
Antigravity	restart IDE hoặc `agy`, rồi `/flow`

Bước 3 — kiểm môi trường

bash ~/.claude/skills/flow/runner/flow.sh doctor

Bạn cần thấy READY. doctor kiểm tra bash, python, grep, git trên macOS, Linux, Windows. Thiếu python3 thì nó báo lớp bền vững bị disabled. Đó là chế độ suy giảm (degraded), không phải fail. Còn lỗi nào khác, xem Khắc phục cài đặt.

Trên Windows PowerShell, gọi runner\flow.cmd thay vì bash. Lệnh bash đứng một mình trong PowerShell thường trỏ sang WSL, không đọc được path C:/... — khiến một bản cài đúng trông như bị hỏng.

Xác nhận hai số version (installer và skill) là phần đào sâu tùy chọn. Xem Hai số version.

In ra cả hai số version

npx @manhquy/flow-skill@latest --help
# expect: flow-skill v0.7.11 (ships skill v0.34.4)

Installer in ra version của chính nó và version của skill mà nó ship. Rồi đọc skill version từ file trên máy:

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1

Hai số đó độc lập với nhau. Đừng copy số version từ trang này.

Bước 4 — nói muốn build gì

Bạn không bắt buộc phải học verb. Trong một session agent mới, đứng trong thư mục project, gõ:

“Tôi muốn build app quản lý kho cho cửa hàng.”

Hoặc gõ /flow (Codex: $flow).

Concierge chạy lệnh status trước để lấy ground truth cơ học, hỏi một câu xin phép về việc ai sẽ soạn artifact, rồi đề xuất đúng một hành động kế tiếp. Lệnh /flow tường minh luôn được ưu tiên hơn routing chat.

Routing đáng tin cậy trên Claude. Trên Codex hoặc Antigravity, hãy coi chat routing chỉ là best-effort và gõ lệnh trực tiếp. Lưu ý đầy đủ có tại Dùng chat Concierge.

Thành công là một trong ba: trạng thái, việc kế tiếp, hoặc kết quả gate. Việc “concierge đồng ý” tự nó chưa phải là thành công.

Bạn đã có gì

Skill đã được cài trong ít nhất một agent home.
Agent đã restart nên đã nhận ra skill.
Một câu trả lời từ harness: trạng thái, việc kế tiếp, hoặc kết quả gate.

Bước tiếp theo

Làm một dự án thật, đi qua mọi gate planning trong Đi hết một dự án mẫu, hoặc đọc Harness hai lớp để hiểu thứ vừa phán xét file của bạn.

Xem gate từ chối

Đây là phần đào sâu tùy chọn — demo để xác nhận lớp cơ học còn sống. Loại (kill) tại gate cũng là kết quả hợp lệ.

Transcript file Idea trống

Tạo một thư mục trống, mở agent ở đó. Rồi yêu cầu stage đầu tiên:

/flow next

Runner tạo khung (scaffold) cho flow/00-idea.md rồi kiểm tra gate ngay. Vì bạn chưa viết gì, nó từ chối:

FAIL: gate for stage 00-idea is not clean.
  [x] unchecked gate boxes:
      L4:- [ ] The pitch below is 3 sentences, no more
  [x] unfilled [FILL] placeholders:
      L10:[FILL: sentence 1 — who has the problem]
Fix the above, then run '/flow next' again. (Kill at a gate is also valid.)

Đây là dấu hiệu cài đặt đang chạy đúng. Lớp cơ học đọc file, thấy ô chưa tick và [FILL] chưa điền, trả về exit code khác 0 kèm số dòng. Nó không điền hộ bạn — và sẽ không bao giờ điền hộ.