Sử dụng và viết Skill

Giao việc cho agent

Kiểm ứng dụng đã nhận diện skill và môi trường có tool cần thiết. Cách gọi trực tiếp khác nhau theo ứng dụng; dùng cơ chế chọn skill của ứng dụng hoặc yêu cầu agent áp dụng tên skill đang có, rồi kiểm thông báo kích hoạt.

Giao việc cùng dữ kiện và giới hạn cụ thể:

Áp dụng skill diagnose để điều tra timeout của API /orders.
Đầu vào: log đã ẩn dữ liệu cá nhân và test tái hiện kèm theo.
Phạm vi: chỉ sửa service xử lý đơn hàng; không thay đổi dữ liệu thật.
Kết quả: nguyên nhân, bản sửa nhỏ và kết quả test regression.
Nếu thiếu quyền hoặc dữ kiện để kiểm, ghi rõ phần chưa xác minh.

Chọn dữ kiện nào đưa vào lời giao việc (log, code, diff, ví dụ) và bỏ gì: xem Chọn context khi sửa code.

Đọc đầu ra và diff. Câu “đã chạy test” cần đi kèm lệnh, exit code và kết quả đủ để kiểm lại; cách viết tiêu chí để có bằng chứng như vậy: xem Tiêu chí hoàn tất có thể kiểm chứng. Với việc đo hiệu năng, giữ dataset, cấu hình và điều kiện chạy nhất quán.

Một lượt làm việc

Chốt kết quả mong muốn, quyền thực thi và vùng được sửa.
Chọn một skill chính; bổ sung chuyên môn khi task thật sự cần.
Đọc điều kiện môi trường, script và nguồn của skill trước khi chạy.
Làm từng phần nhỏ; kiểm kết quả quan sát được sau mỗi phần.
Review tổng thể, ghi phần còn thiếu và lưu bước tiếp theo nếu chưa xong.

Ví dụ với database-management: agent có thể đề xuất migration và kiểm trên database thử nghiệm. Chạy migration production cần quyền và quy trình vận hành riêng; skill không thay thế việc đó.

Viết skill nhỏ

Bắt đầu từ một thao tác lặp đã rõ đầu vào và đầu ra. Ví dụ dưới đây là mẫu tự chứa về review API; không cần script hoặc tài nguyên riêng.

Tạo thư mục review-api-contract, đặt file SKILL.md trong đó:

---
name: review-api-contract
description: Rà soát hợp đồng API và thay đổi tương thích. Dùng khi thêm endpoint hoặc đổi request/response.
---

# Rà soát hợp đồng API

## Đầu vào

Spec API hiện tại, diff và hành vi mong muốn.

## Quy trình

1. Đối chiếu method, route, status code và schema.
2. Xác định client bị ảnh hưởng bởi field đổi hoặc bị bỏ.
3. Kiểm validation, phân quyền và định dạng lỗi.
4. Chạy contract test được dự án cung cấp nếu môi trường cho phép.
5. Báo finding theo mức ảnh hưởng và vị trí cụ thể.

## Đầu ra

Finding có bằng chứng; lệnh test và kết quả; điểm chưa xác minh.
Không tự sửa spec hoặc deploy khi yêu cầu chỉ là review.

Theo đặc tả Agent Skills, name và description là trường bắt buộc. Tên phải khớp thư mục; mô tả giúp agent nhận ra lúc cần dùng. Đặt tài liệu dài ở references/, script ở scripts/, mẫu ở assets/ khi cần. Hỗ trợ các trường mở rộng phụ thuộc ứng dụng.

Kiểm skill trước khi dùng rộng

Ca đúng trigger: yêu cầu review API phải tạo finding có căn cứ.
Ca ngoài phạm vi: yêu cầu sửa giao diện không được kéo vào quy trình review API.
Thiếu đầu vào: thiếu spec hoặc log phải nêu dữ kiện còn thiếu.
Thiếu tool: không chạy được test phải ghi chưa kiểm, không tự báo đạt.
Ca giới hạn quyền: task chỉ review không được tự sửa hoặc deploy.

Validator định dạng không đo đủ chất lượng quy trình. Chạy thử các tình huống trên và review hành động của agent để phát hiện chỉ dẫn mơ hồ.

Skill từ bên ngoài

Đọc cả SKILL.md, script, tài liệu được dẫn và hook đi kèm. Kiểm hành động đọc credential, gửi mạng, tải/chạy mã hoặc sửa cấu hình agent; đối chiếu với chức năng mong muốn. Thử trong môi trường cô lập với dữ liệu giả và quyền tối thiểu. Scanner hỗ trợ tìm dấu hiệu; không có finding vẫn cần review.

Khi skill không hoạt động như mong muốn

Hiện tượng	Kiểm tra	Cách xử lý
Không được nhận diện	Vị trí cài và metadata theo ứng dụng	Sửa cấu trúc, tải lại theo tài liệu ứng dụng
Được nhận diện nhưng không kích hoạt	Description và yêu cầu có khớp không	Nêu loại việc cụ thể hoặc chọn skill trực tiếp
Agent làm sai phạm vi	Trigger quá rộng hoặc hướng dẫn xung đột	Thu hẹp phạm vi, thêm tình huống kiểm
Script thất bại	Dependency, đường dẫn, quyền và exit code	Sửa nguyên nhân, chạy lại verifier
Test đạt nhưng chưa đúng yêu cầu	Tiêu chí có bỏ sót ý định không	Bổ sung tiêu chí từ yêu cầu rồi kiểm lại
Quy trình đã cũ	Phiên bản tool và nguồn tham chiếu	Rà soát nguồn, sửa hướng dẫn, thử lại

Giữ skill gắn với công việc lặp thật. Khi nhiều skill cùng giải một vấn đề, xem lại ranh giới hoặc hợp nhất; khi quy trình đổi, cập nhật skill cùng bằng chứng kiểm mới.

Keyboard shortcuts