Agent skill: đừng fork, hãy gắn núm chỉnh

Muốn dùng lại agent skill giữa nhiều project? Hãy quản lý bằng config, guardrail và tiêu chí dừng thay vì fork prompt rồi sửa tay.

“Anh ơi, skill format commit của repo mobile khác repo backend một chút, em copy ra bản mới nhé?”

Câu này nghe vô hại cho tới khi team bạn có 7 repo, 3 convention commit, 2 bạn vừa đổi việc, và không ai nhớ bản git-commit-skill-final-v3-really-final đang sống ở đâu. Mình đã thấy kiểu này nhiều lần: agent skill ban đầu được viết như một mẩu hướng dẫn gọn gàng, sau vài tuần biến thành võ đường có quá nhiều đai màu nhưng không có luật đối luyện.

Luận điểm của bài này rất đơn giản: agent skill trong production không nên được quản lý như file prompt tĩnh. Nó nên có cấu hình, guardrail và tiêu chí dừng rõ ràng.

Nếu trước giờ bạn nghĩ “skill chạy được là xong”, sau bài này mình muốn bạn đổi sang câu hỏi khác: skill này có đổi hành vi theo project mà không cần fork không?

Đây là một lát cắt nhỏ của bài toán lớn hơn về agent production cần vòng kiểm soát: càng cho agent nhiều quyền, team càng cần tách rõ workflow, policy và điểm dừng.

Sơ đồ tóm tắt ý chính của bài viết.

Mục tiêu: biến skill thành thứ vận hành được

Agent skill, hiểu trong ngữ cảnh này, là một gói hướng dẫn để agent thực hiện một workflow lặp lại: format commit, review PR, tạo changelog, chuẩn hóa ticket, viết test case… Nó thường có một file kiểu SKILL.md mô tả khi nào dùng và dùng ra sao.

Vấn đề nằm ở chữ “lặp lại”. Workflow thì lặp, nhưng môi trường thì không.

• Repo A dùng Conventional Commits.
• Repo B thích prefix kiểu feat(api): nhưng cấm scope quá dài.
• Repo C muốn gitmoji.
• Team D không cho agent tự commit, chỉ được đề xuất message.

Nếu mỗi biến thể lại fork một skill, bạn đang tạo nợ vận hành. Lúc cần sửa guardrail, bạn phải vá nhiều bản. Lúc cần audit, bạn không biết bản nào đang được dùng. Lúc agent làm sai, bạn không phân biệt được lỗi do skill gốc, config project, hay người gọi task.

Nói thẳng ra thì: fork skill là cách nhanh để demo, nhưng là cách chậm để vận hành.

Checklist trước khi viết thêm skill mới

Trước khi team bạn tạo thêm một SKILL.md, dừng lại 10 phút và trả lời 5 câu này:

1. Phần nào là luật chung?

Ví dụ: commit message phải ngắn, có type, không bịa ticket ID.

1. Phần nào là tùy project?

Ví dụ: danh sách type hợp lệ, có dùng gitmoji không, có bắt buộc scope không.

1. Agent được phép làm gì?

Chỉ gợi ý message, hay được chạy git commit?

1. Khi thiếu thông tin thì dừng hay đoán?

Với production, câu trả lời thường nên là dừng và hỏi lại.

1. Làm sao biết skill đang chạy đúng?

Cần ít nhất vài case kiểm thử nhỏ: input diff giả, expected output, trường hợp thiếu ticket, trường hợp message quá dài.

Đây là thế thủ cơ bản trước khi cho agent lên sàn. Đai trắng cũng được, miễn là biết che cằm.

Playbook một buổi: thêm lớp config cho agent skill

Bạn có thể thử trong một buổi chiều với một skill nhỏ: git commit formatter. Mục tiêu không phải build framework hoành tráng, mà là chứng minh skill có thể đổi hành vi bằng config thay vì fork.

Bước 1: tách default ra khỏi hướng dẫn

Trong thư mục skill, tạo một file config.default.yaml. Chỉ cần vài núm chỉnh thật sự ảnh hưởng hành vi:

commit_formatter:
  mode: conventional
  allowed_types:
    - feat
    - fix
    - docs
    - refactor
    - test
  require_scope: false
  max_subject_length: 72
  allow_gitmoji: false
  can_run_git_commit: false

File này là “luật mặc định”. Nó không thay thế SKILL.md, mà làm cho các núm chỉnh hiện ra rõ ràng.

Trong SKILL.md, đừng hard-code mọi thứ. Hãy viết luật theo hướng: đọc config đã resolve trước, dùng mode để chọn Conventional Commits hay gitmoji, chỉ dùng allowed_types, hỏi lại khi require_scope=true mà thiếu scope, và nếu can_run_git_commit=false thì chỉ đề xuất command chứ không thực thi.

Điểm quan trọng: skill mô tả workflow, còn YAML mô tả policy theo project.

Bước 2: cho mỗi project một file override

Ở repo sử dụng skill, tạo .agent/skills.config.yaml để override phần khác biệt. Ví dụ frontend có thể dùng mode: gitmoji, require_scope: true, max_subject_length: 60, allow_gitmoji: true, nhưng vẫn giữ can_run_git_commit: false.

Ví dụ cụ thể: team frontend có thể bật gitmoji, team backend vẫn giữ Conventional Commits, nhưng cả hai cùng dùng một skill gốc. Khi skill cần sửa guardrail “không tự commit”, bạn sửa một nơi, không vá từng bản fork.

Bước 3: resolve config trước khi agent hành động

Bạn cần một bước resolve config trước khi agent hành động: đọc config.default.yaml, đọc .agent/skills.config.yaml nếu có, deep-merge hai object, rồi đưa phần config cuối cùng cho skill. Trong hệ thống thật, đặt bước này ở shared tooling, thêm schema validation, và log lại config đã resolve. Quan trọng nhất là agent không được tự chọn luật bằng trí nhớ hoặc suy đoán.

Bước 4: viết 5 case kiểm thử thay vì tranh luận cảm tính

Tạo một file cases.md hoặc test script đơn giản. Đừng cần CI ngay từ đầu; chỉ cần đủ để team cùng nhìn vào kết quả.

Năm case tối thiểu nên có: diff thêm endpoint mới phải ra feat; sửa bug null pointer phải ra fix; khi require_scope=true mà thiếu scope thì agent phải hỏi lại; khi allow_gitmoji=false thì không dùng emoji; khi can_run_git_commit=false thì chỉ đề xuất command, không chạy.

Đây là phần nhiều team bỏ qua. Skill không có test giống như tập đối luyện mà không ai ghi điểm: nhìn thì hăng, xong về không biết mình tiến bộ hay chỉ vung tay đẹp.

Guardrail: đừng để YAML thành cửa sau

Configurable skill giải quyết vấn đề fork, nhưng nó mở ra vấn đề mới: ai được chỉnh config, chỉnh tới đâu, và chỉnh xong có ai biết không?

Với builder, mình sẽ đặt tối thiểu 4 guardrail:

• Schema validation — kiểm tra cấu trúc config. Nếu mode chỉ nhận conventional hoặc gitmoji, giá trị lạ phải fail sớm.
• Permission boundary — ranh giới quyền. Những núm như can_run_git_commit, can_push, can_modify_files không nên bị bật tùy tiện trong repo con.
• Resolved config logging — ghi lại config sau khi merge. Khi agent làm sai, bạn cần biết nó đã đọc luật nào.
• Fail-closed behavior — khi thiếu config quan trọng, hệ thống dừng thay vì tự đoán. Đây là nguyên tắc “không rõ thì không đánh”.

Hình dung thế này: bạn có một skill review PR. Config cho phép chỉnh severity_level, style_guide_path, can_request_changes. Nếu project override nhầm can_request_changes: true, agent có thể chặn PR thật. Vấn đề không nằm ở model thông minh hay không; vấn đề là orchestration — cách điều phối nhiều bước và quyền hành động — chưa có hàng rào.

Nếu workflow đã chạm tới quyền thật như comment PR, gọi tool nội bộ hoặc tự chạy lệnh, hãy đọc nó như một phần của thiết kế guardrail cho agent production, không chỉ như một prompt tiện tay.

Tiêu chí scale hoặc dừng

Sau khi thử với một skill và vài repo, đừng vội biến mọi prompt thành configurable skill. Hãy dùng tiêu chí dừng rõ ràng.

Nên scale khi:

• Cùng một workflow xuất hiện ở ít nhất vài project.
• Khác biệt giữa project chủ yếu là policy, không phải logic hoàn toàn khác.
• Team có người chịu trách nhiệm versioning cho skill gốc.
• Bạn log được skill version, config version và output chính.
• Case kiểm thử bắt được lỗi quan trọng trước khi người dùng gặp.

Nên dừng hoặc giữ thủ công khi:

• Workflow còn thay đổi mỗi ngày.
• Mỗi project cần logic riêng quá sâu.
• Không ai review thay đổi trong .agent/skills.config.yaml.
• Skill có quyền ghi/xóa/chạy lệnh nhưng chưa có audit.
• Agent thường xuyên cần đoán ý người dùng để hoàn thành việc.

Điểm khó chịu nhưng cần nói: configurable skill không làm agent “an toàn” một cách tự động. Nó chỉ làm ranh giới rõ hơn để bạn kiểm soát được. Còn nếu bạn cho phép override mọi thứ mà không review, thì bạn chỉ chuyển hỗn loạn từ Markdown sang YAML.

Nếu là mình, mình sẽ bắt đầu thế này

Mình sẽ không bắt đầu bằng skill phức tạp như “agent tự xử lý ticket support từ đầu tới cuối”. Quá nhiều quyền, quá nhiều trạng thái, quá nhiều chỗ ngã.

Mình sẽ chọn một workflow nhỏ nhưng hay lặp:

• format commit message,
• tạo PR description,
• chuẩn hóa changelog,
• viết release note nội bộ,
• kiểm tra checklist trước merge.

Sau đó áp dụng khung 3 lớp:

1. Skill gốc giữ workflow: agent làm theo trình tự nào.
2. Default config giữ policy mặc định: luật chung của team.
3. Project config giữ khác biệt cục bộ: repo này cần biến thể gì.

Trong pull request, bắt review cả SKILL.md lẫn .agent/skills.config.yaml. Với những config đụng tới quyền hành động, yêu cầu tech lead approve. Nếu sau hai tuần skill vẫn cần fork, đó là tín hiệu workflow chưa được tách đúng: hoặc default quá cứng, hoặc các project thật ra không cùng một bài toán.

Takeaway của mình: đừng hỏi agent skill nào mạnh hơn; hãy hỏi skill nào đổi luật được mà không làm vỡ vận hành. Trong dojo production, người thắng không phải người đá cao nhất, mà là người biết lúc nào nên giữ thế thủ.

---
Bụi Wire — nghiện đọc release notes lúc 2 giờ sáng