AgentKit v3 có gì mới? Không phải bản "thêm tính năng", mà là bản đổi móng nhà

Bài 1/20 trong bộ onboarding AgentKit v3. Đọc khoảng 10 phút.

Ngày 29/10/2026, tag v3.0.0 lên GitHub với 101 asset: kit cho 8 runtime, ak CLI cho macOS/Linux/Windows (amd64 và arm64) kèm SBOM, app desktop ak-gui, checksums.txt và release-provenance.json. Release note dài như cái sớ, khoảng 300 gạch đầu dòng feature với fix 😂

Đọc hết thì mệt, nên tui gom lại thành 5 thay đổi bạn sẽ thật sự cảm nhận được.

1/ Cấu trúc mới: một hệ thống, nhiều runtime ✅

Hồi ClaudeKit, mọi thứ xoay quanh Claude Code. Tới v3, kit được build ra thành gói runtime-native cho từng agent:

Mỗi gói đi kèm file .sha256 và manifest.json, nên CLI kiểm tra được gói tải về có bị chỉnh sửa hay không trước khi cài.

Cái này nghĩa là gì với bạn? Đổi agent không phải làm lại từ đầu. Hôm nay xài Claude Code, mai thử Codex, workflow vẫn y chang. v3 có 2 workflow chính: /ak-plan → /ak-cook → /ak-ship cho model nhỏ hơn, và /ak-brainstorm → /ak-advise → /ak-vibe --ship cho model mạnh như Opus 5.5, Fable hay GPT-Astra. Chọn cái nào, và vì sao đôi khi câu trả lời đúng là "khỏi build", xem bài 12. Chi tiết runtime nào "chín" tới đâu, đọc bài 4 (tui có bảng chứng nhận thật, không tô hồng).

2/ Skill: một cái tên duy nhất ak-<slug>, 4 skill mới, nhiều skill được làm lại ✅

Một tên duy nhất

Ở v2, skill có hai kiểu tên: thư mục là ak-cook nhưng tên gọi lại là ak:cook. v3 gom về một tên duy nhất ak-<slug> cho mọi runtime:

• Claude Code: /ak-cook, /ak-plan, /ak-ship, /ak-debug...

• Codex: $ak-cook, $ak-plan...

Lý do đơn giản: dấu : không phải runtime nào cũng chịu, và máy bạn có thể cài skill từ nhiều nguồn (của tui, của Anthropic, của cộng đồng). Prefix ak- giữ cho hai skill tên cook khỏi đá nhau. v3 còn có preflight kiểm tra alias collision trước khi ghi file, trùng là dừng chứ không ghi đè bừa.

4 skill mới so với v2.19.0

Tui đếm thẳng thư mục skill trong hai tag v2.19.0 và v3.0.0: Engineer từ 64 lên 65, Marketing từ 43 lên 44, Core giữ 40 (thêm 2, bớt 1).

Bị gỡ đúng một skill: ak:ak (vận hành chính CLI ak). Phần đó giờ do ak-agentkit gánh luôn, nên bạn không mất gì.

Đính chính cho ai đọc bản trước: ak-advise không phải skill mới của v3, nó đã có từ v2.

Skill được làm lại nhiều nhất

Tui xếp theo số dòng thay đổi giữa v2.19.0 và v3.0.0, bỏ qua mấy thay đổi chung như đổi tên:

Thêm một thay đổi chung cho toàn bộ skill: mô tả được rút gọn và tách riêng phần when_to_use, để catalog dài cỡ nào vẫn lọt vào giới hạn hiển thị của từng runtime (Cursor từng cắt bớt danh sách skill khi catalog quá dài).

3/ --ssot: kho skill một nguồn sự thật 🧪 (opt-in)

Đây là thay đổi kiến trúc lớn nhất, nhưng mặc định đang tắt. Bạn chủ động bật mới có.

ak update --ssot chuyển skill từ kiểu "copy vào từng thư mục runtime" sang một content-addressed skill store nằm trong ~/.agentkit. Mỗi cây skill có digest SHA-256 riêng, ghi có journal chống crash, rồi được "chiếu" (project) vào thư mục của từng runtime.

Lợi ích:

• Một skill, nhiều runtime, một bản gốc duy nhất. Hết cảnh Claude Code chạy bản mới mà Codex còn bản cũ.

• Bật luôn SkillX (cài skill có chữ ký, personal kit, đồng bộ nhiều máy), xem bài 5.

• Có snapshot trước khi đổi, lỡ có gì thì ak rollback --to v2.

Luôn chạy thử trước:

ak update --ssot --dry-run

Thấy ổn thì:

ak update --ssot --yes

Tui để opt-in vì một lý do: không ai muốn sáng mở máy ra thấy cấu trúc thư mục bị đổi mà mình hổng hề đồng ý.

4/ Quản lý model cho từng agent ✅

Trước đây muốn đổi model của subagent code-reviewer từ Opus sang Sonnet, bạn phải mở file agent ra sửa tay, rồi lần update sau bị ghi đè mất tiêu. Thốn!

v3 có nguyên nhóm lệnh ak agents model:

ak agents model list
ak agents model set kongming --runtime codex --model gpt-5.5 --effort high
ak agents model explain kongming --runtime claude-code
ak agents model inherit explore --runtime claude-code
ak agents model reset kongming --runtime codex

Mấy điểm tui thích:

• Theo lớp (layered): model được quyết định theo thứ tự kit default → adapter default → config user → config project → file runtime. explain nói rõ lớp nào đang thắng.

• Không mất khi update: override nằm trong config (agent_models.<runtime>.agents.<agent>.model và reasoning_effort), không nằm trong file bị ghi đè.

• Sửa tay vẫn được: nếu bạn sửa thẳng file agent, ak giữ nguyên và báo là drift. Muốn chốt thì ak agents model adopt.

• Có giao diện: app desktop có trang Subagents → Models.

Hỗ trợ Claude Code, Codex, Oh My Pi, Pi (theo release note: "Reconcile OMP and Pi agent model edits").

5/ Lệnh "biết nói chuyện": agent-native CLI và feedback ✅

Breaking change đáng giá nhất của v3: ak được thiết kế để agent gọi, không chỉ người gõ.

• Gần như mọi lệnh có --json và --no-interactive, exit code được khai báo rõ ràng (ví dụ 3 là chỉ preview, 15 là cần gia hạn).

• ak describe in ra "hợp đồng" của từng lệnh: có ghi gì không, mức rủi ro, có cần xác nhận không, có snapshot không, có gọi mạng không.

ak describe kit install --json

Agent đọc cái này là biết lệnh nào an toàn để tự chạy, lệnh nào phải hỏi bạn trước. Đây là cách tui hiểu "agent experience" (AX): con agent cũng là một user, phải được đối xử tử tế.

Còn khi có lỗi hoặc ý tưởng, gửi thẳng từ terminal:

ak feedback --type bug --title "Update failed" --attach-diagnostics

--attach-diagnostics kèm bản tóm tắt ak doctor đã redact. Muốn xem trước khi gửi thì --export feedback.md.

Nói thật: phần thông báo lỗi vẫn còn chỗ "cụt lủn" kiểu Error: Command failed., phải thêm --verbose mới thấy lý do. Tui ghi vào báo cáo gap rồi, sẽ sửa.

Còn gì nữa? (điểm nhanh)

Vì sao tui làm v3 kiểu này?

Có người hỏi: "Sao không cứ thêm skill mới cho lẹ, đụng chi tới móng nhà?"

Vì thêm skill trên móng yếu thì càng thêm càng sập. Hồi v2, tui nhận đủ loại report: skill trùng tên, update ghi đè file người dùng sửa, đổi máy là phải cài lại từ đầu, agent tự chạy lệnh nguy hiểm vì không biết lệnh đó nguy hiểm. Mấy cái đó hổng sửa bằng cách viết thêm skill được.

v3 là bản tui chấp nhận chậm lại vài tháng để những thứ bạn xây trên AgentKit sống được lâu. Kit của bạn, config của bạn, skill bạn tự viết, đều phải sống sót qua mọi lần update. Đó là lời hứa.

Bài tiếp: Update lên v3, rollback, auto-update và gỡ rối →

Nguồn

• GitHub release v3.0.0: https://github.com/bestagentkits/agentkit/releases/tag/v3.0.0 (published 2026-10-29T11:05:07Z)

• So sánh skill: git ls-tree thư mục kits/{core,engineer,marketing}/skills và git diff --numstat v2.19.0 v3.0.0, cùng commit acb50a358 "use ak-<slug> as the single skill name" (#2634) trong repo bestagentkits/agentkit

• Hướng dẫn migration nội bộ: agentkit/docs/guides/v2-to-v3-migration.md (tag v3.0.0)

• Output thật: ak --version, ak self-update --check, ak update --ssot --dry-run, ak agents model list, ak describe --help, ak feedback --help (ak 3.0.0, 02/11/2026)