Scripts, References, Assets & Hooks

Nếu cùng input luôn phải tạo cùng output và một chương trình có thể làm đáng tin cậy hơn, ưu tiên script: parse report, validate schema, render artifact, normalize data. Nếu quyết định phụ thuộc intent, risk hoặc evidence không hoàn chỉnh, giữ nó trong prose để model suy luận.

Đừng chuyển mọi thứ thành script. Code tăng dependency, permission surface và maintenance. Script chỉ đáng có khi giảm variance, token cost hoặc lỗi thao tác đủ lớn.

SKILL.md phải nói working directory, command, input, output, exit codes, files được phép ghi và cách xử lý failure. Script phải validate input trước side effect, ghi diagnostic ra stderr, structured result ra stdout và không in secret.

Không dùng script để lách approval hoặc sandbox. Skill text không thể cấp quyền; harness vẫn phải authorize command và target.

Luồng đầy đủ có ít nhất sáu ranh giới: model đọc instruction; model quyết định cần executable; model phát tool call; harness kiểm tra command và permission; operating system tạo process; stdout, stderr và exit code quay lại thành observation. scripts/ chỉ là convention tổ chức file, không phải auto-run directory.

Điểm này giải thích vì sao cùng một skill có thể chạy trên hai harness nhưng hành vi khác nhau. Model có thể đưa ra cùng command, song harness A cho network còn harness B chặn; harness A yêu cầu approval còn harness B chỉ cho đọc. Skill ảnh hưởng proposal, harness quyết định capability thực tế.

Reference được đọc vào context giống evidence. Nó có thể thay đổi kết luận, branch hoặc tool call tiếp theo, nhưng không tự ghi file hay gọi API. Tác động gián tiếp vẫn lớn: tài liệu sai có thể khiến model đề xuất hành động sai, nên reference cần owner, version và điều kiện đọc.

Pointer nên nói rõ trigger, path và mục tiêu. Ví dụ: “Nếu diff thay đổi authentication, đọc references/auth-threat-model.md để tạo checklist” tốt hơn “đọc references khi cần”. Cách viết này vừa giảm context vừa tạo được eval case quan sát rõ file nào đáng lẽ phải được mở.

stdout nên ổn định và machine-readable khi model phải parse kết quả; stderr dành cho diagnostic; exit 0 nghĩa là command hoàn thành theo contract, không nhất thiết business result là “pass”. Non-zero phải phân biệt invalid input, dependency thiếu và execution failure nếu workflow cần recovery khác nhau.

Một script tốt còn định nghĩa idempotency và write set. Chạy lại có ghi đè an toàn không? File nào được tạo? Partial failure để lại artifact nào? Không trả lời được các câu này thì agent khó retry và harness khó review side effect.

Skill dựa vào activation và model compliance. Hook chạy tại event do runtime định nghĩa, phù hợp với formatting sau edit, secret scan trước commit hoặc telemetry sau tool call. Nếu một constraint không được phép bỏ sót, đừng chỉ viết nó thành lời nhắc.

Hook cũng cần budget và failure policy. Một hook fail-closed tăng an toàn nhưng có thể khóa workflow; fail-open giữ availability nhưng phải tạo alert và evidence.