Personal kit và `/ak-dogfood`: tự chỉnh skill mà update không đè mất

Bài 20 trong bộ onboarding AgentKit v3. Đọc khoảng 10 phút. Bài này đi sâu phần personal kit đã giới thiệu ở bài 5.

Ai xài kit lâu cũng gặp cảnh này: skill ak-plan chạy ổn, nhưng team bạn có một quy ước riêng mà nó cứ quên. Bạn mở SKILL.md ra sửa, chạy ngon lành. Tuần sau ak update, bản sửa bay màu 😂

v3 giải bài toán đó bằng hai thứ:

• Personal kit: một lớp "của bạn" phủ lên kit gốc. Kit gốc update thì bạn rebase, không phải sửa lại từ đầu.

• /ak-dogfood: soi lại session vừa làm, chỉ ra skill nào làm agent đi lòng vòng, rồi đề xuất sửa đúng chỗ đó.

Ghép hai cái lại là ra một vòng lặp: làm việc → dogfood → ghi bản sửa vào personal kit → làm việc tiếp với skill tốt hơn.

🧪 Toàn bộ lệnh ak skills kit ..., ak skills improve và ak skills evolution ... trong bài là preview trong ak 3.0.0. Phần publish/sync lên SkillX còn nằm sau cờ phía server (xem bài 5, mục 5). Mọi lệnh dưới đây được dán từ --help thật của bản 3.0.0.

1/ Ba loại skill, ba cách sửa

Trước khi sửa skill nào, hỏi một câu: skill này của ai? Câu trả lời quyết định bạn được sửa ở đâu.

Riêng skill ak-*: nếu bạn sửa thẳng file trong ~/.claude/skills/ak-plan/, lần update sau AgentKit coi đó là file bị người dùng chỉnh, và bạn sẽ phải tự xử lý. Personal kit sinh ra để bạn khỏi phải chơi trò đó.

2/ Personal kit là gì, nói cho dễ hiểu

Hình dung kit Engineer là một cuốn sách in. Personal kit là xấp giấy note bạn dán lên trên: trang nào muốn sửa thì dán note lên trang đó, sách gốc vẫn nguyên. Nhà xuất bản in lại bản mới, bạn bóc note ra dán lên bản mới (rebase), chỗ nào trang bị đổi nhiều thì nó báo xung đột để bạn tự quyết.

Cụ thể, personal kit là một thư mục AGENTKIT_HOME/kits/personal/<tên>/ với file personal-kit.yaml:

schema: agentkit.personal-kit/v1
name: mine
extends:
  - kit: engineer
    version: 0.2.0          # đúng một phiên bản, không dùng khoảng ^ hay ~
overlays:
  - identity: "@agentkit/plan"
    dir: overlays/plan
forks:
  - from: "@agentkit/brainstorm"
    identity: "@local/my-brainstorm"
    alias: my-brainstorm    # không được bắt đầu bằng ak-
    overlay: overlays/my-brainstorm

Hai kiểu chỉnh:

• Overlay: sửa một skill riêng của kit (ví dụ ak-plan của Engineer). Tên skill giữ nguyên.

• Fork: dùng cho skill dùng chung (skill nằm trong kits/core, hoặc có mặt ở hơn một kit). Loại này không cho overlay, vì sửa nó là sửa luôn cho kit khác. Bạn fork ra một tên mới không có tiền tố ak-, ví dụ my-brainstorm.

Thư mục overlay chỉ chứa phần bạn đổi, theo 4 kiểu:

• files/<đường-dẫn>: nội dung mới nguyên file;

• patches/<đường-dẫn>.diff: một unified diff chính xác;

• delete.txt: file cần xoá;

• modes.txt: đổi quyền file.

File nào trùng y chang bản gốc thì bị bỏ qua. Tên file lạ, symlink hay file không phải file thường đều bị từ chối, để một lỗi gõ nhầm không âm thầm làm mất bản sửa.

3/ Tạo và cập nhật personal kit, từng bước

Bước 1: tạo kit. Kit phải kế thừa đúng một phiên bản kit gốc.

ak skills kit init mine --extends engineer@0.2.0 --dry-run   # xem manifest trước
ak skills kit init mine --extends engineer@0.2.0

Nếu thư mục mine đã tồn tại thì lệnh từ chối, không ghi đè gì hết.

Bước 2: thêm overlay hoặc fork bằng cách sửa personal-kit.yaml và tạo thư mục overlay như mục 2. Cách dễ hơn là để /ak-dogfood làm giùm (mục 4).

Bước 3: xem trước.

ak skills kit inspect mine
ak skills kit status mine

Bước 4: áp vào runtime.

ak skills kit apply mine --dry-run
ak skills kit apply mine

apply đẩy toàn bộ skill của kit vào thư mục skill của runtime (Claude Code, Codex...). Nếu kế hoạch có điểm cần xem lại (đổi script, quyền, license...), nó chỉ chạy khi bạn truyền --plan <token> lấy từ bản --dry-run. Nghĩa là: thay đổi nhạy cảm phải được bạn nhìn thấy trước rồi mới áp.

Bước 5: khi kit gốc ra bản mới thì rebase.

ak skills kit rebase mine --to engineer@0.3.0 --dry-run

Xung đột được ghi rõ, không tự chọn bên thắng. Rebase xong, nhớ cập nhật version trong personal-kit.yaml, vì apply sẽ từ chối nếu manifest còn ghim bản cũ (lỗi personal_kit.pin_behind).

Lỡ tay thì quay lại:

ak skills kit revisions mine
ak skills kit rollback mine --dry-run
ak skills kit rollback mine

4/ /ak-dogfood: biến lỗi trong session thành bản sửa skill

"Dogfooding" là tự ăn đồ ăn chó mình làm, tức là tự xài sản phẩm của mình để thấy chỗ dở. /ak-dogfood làm đúng chuyện đó với skill: cuối session, nó đọc lại session vừa chạy và trả lời: skill nào làm tốn thời gian, tốn token, phải làm lại, hay bị bạn sửa lưng?

Với mỗi chỗ như vậy, nó đề xuất bản sửa nhỏ nhất vào đúng dòng trong skill, kèm bằng chứng, hiệu quả kỳ vọng và rủi ro.

Các chế độ

--apply và --ask không đi chung. Lỡ gõ cả hai thì nó chọn --ask, an toàn hơn.

Nó phân loại lỗi trước khi đề xuất

Không phải lỗi nào cũng là lỗi của skill. Mỗi phát hiện được xếp vào một trong bốn loại:

1. Skill có lỗi (hướng dẫn sai, thiếu, mơ hồ);

2. Agent làm sai mà skill có thể chặn trước;

3. Lỗi môi trường hay công cụ (mạng rớt, CLI hỏng...);

4. Chuyện một lần.

Chỉ loại 1 và 2 mới thành đề xuất sửa skill. Loại 3 và 4 chỉ được ghi một dòng. Chỗ này tui thích: nó không đổ hết lỗi lên skill rồi sửa lung tung.

Bản sửa đi đâu?

Đây là chỗ nối với personal kit. Với skill ak-* mà bạn không có quyền push vào repo AgentKit, dogfood đi theo đường personal fork:

# 1. lấy brief: bằng chứng đã che thông tin nhạy cảm + layout overlay
ak skills improve ak-plan --session latest --dry-run --brief --json

# 2. agent viết bản nháp overlay vào một thư mục trống, rồi biên dịch và chấm điểm
ak skills improve ak-plan --session latest --candidate ./draft --dry-run
ak skills improve ak-plan --session latest --candidate ./draft

# 3. xem và áp candidate vào personal kit
ak skills evolution list
ak skills evolution apply <candidateId>          # xem trước
ak skills evolution apply <candidateId> --yes    # áp thật

# 4. đẩy personal kit vào runtime
ak skills kit apply mine

Muốn gỡ: ak skills evolution rollback <candidateId>.

Mấy điểm đáng tiền trong đường này:

• ak không gọi model nào. Agent của bạn viết bản nháp, còn ak chỉ biên dịch, kiểm tra và chấm điểm offline, có kết quả xác định.

• Chấm điểm thật, không cảm tính. Candidate được so với bản gốc trên chính các task trong bằng chứng. Skill khác được đem ra làm đối chứng, để bản sửa không làm hỏng chỗ khác. Kết quả là một trong bốn: improved, inconclusive, regressed, blocked. Hai loại sau thì không áp được.

• Bảo mật chặn cứng. Bản nháp có secret hoặc đường dẫn tuyệt đối trên máy bạn thì bị từ chối thẳng. Đổi script, quyền hay license thì thành điểm cần duyệt.

• Che thông tin nhạy cảm (redact) là best-effort. --help nói rõ: secret có dạng lạ vẫn có thể lọt, nên đọc lại bản preview trước khi chia sẻ cho ai.

• Ghi lại không có nghĩa là áp. improve chỉ ghi candidate. Phải qua evolution apply mới vào personal kit, rồi kit apply mới tới runtime. Publish lên SkillX lại là một lệnh riêng nữa: ak skills kit publish mine --private.

Nếu bạn là contributor có quyền push vào repo AgentKit, dogfood đi đường contributor: sửa thẳng source trong kits/, kiểm tra, mở PR vào dev. Quyền push được kiểm tra thật bằng gh, không đoán.

5/ Vòng lặp tui xài mỗi ngày

làm việc với agent
  → cuối session: /ak-dogfood --ask
  → chọn đề xuất đáng áp
  → candidate vào personal kit "mine"
  → ak skills kit apply mine
  → session sau, skill đã tốt hơn

Vài kinh nghiệm:

• Đừng --apply ngay từ đầu. Chạy dry-run mấy lần cho quen cách nó nghĩ, rồi mới --ask. --apply để dành khi bạn đã tin nó.

• Một lỗi không đáng sửa skill. Lỗi lặp lại mới đáng. Mỗi cuối tuần chạy --all --since <tuần trước> để thấy lỗi nào lặp nhiều nhất.

• Personal kit mỏng thôi. Overlay càng ít thì rebase càng nhẹ. Thấy một bản sửa hữu ích cho mọi người thì mở issue hoặc làm contributor, để nó vào kit gốc luôn.

Tóm lại

1/ Đừng sửa thẳng file skill ak-* đã cài. Ghi bản sửa vào personal kit.

2/ Personal kit = manifest personal-kit.yaml + overlay (skill riêng của kit) hoặc fork (skill dùng chung, tên mới không có ak-).

3/ Vòng đời: init → inspect → apply → rebase khi kit gốc lên bản mới → rollback khi lỡ tay.

4/ /ak-dogfood đọc session, phân loại lỗi, đề xuất bản sửa nhỏ nhất. Mặc định chỉ đề xuất.

5/ Bản sửa đi qua ak skills improve → evolution apply → kit apply, được chấm điểm offline và chặn secret. Tất cả vẫn là preview trong 3.0.0.

Nguồn

• ak skills improve --help, ak skills evolution --help, ak skills evolution apply --help, ak skills kit init|apply|rebase|rollback|revisions|publish --help (ak 3.0.0, chạy trong HOME tạm).

• Skill ak-dogfood v1.2.0: SKILL.md, references/apply-lanes.md.

• Đặc tả personal kit: agentkit/docs/specs/personal-kit-contract.md.