Những phương pháp tốt nhất dành cho người tạo skill

Đây là cách viết các skill được xác định rõ ràng và phù hợp với nhiệm vụ!

Bắt đầu từ chuyên môn thực tế

Một lỗi thường gặp trong việc tạo skill là yêu cầu LLM tạo ra skill mà không cung cấp ngữ cảnh cụ thể về lĩnh vực - chỉ dựa vào kiến ​​thức đào tạo chung của LLM. Kết quả là các quy trình mơ hồ, chung chung (“xử lý lỗi một cách thích hợp”, “tuân theo những thực tiễn tốt nhất để xác thực”) thay vì các mẫu API cụ thể, những trường hợp ngoại lệ và các quy ước dự án làm cho skill trở nên có giá trị.

Các skill hiệu quả được xây dựng dựa trên chuyên môn thực tế. Chìa khóa là cung cấp ngữ cảnh cụ thể về lĩnh vực vào quá trình tạo skill.

Trích xuất từ ​​một nhiệm vụ thực tế

Hoàn thành một nhiệm vụ thực tế trong cuộc trò chuyện với một agent, cung cấp ngữ cảnh, chỉnh sửa và sở thích trong suốt quá trình. Sau đó, trích xuất mẫu có thể tái sử dụng thành một skill. Hãy chú ý đến:

• Các bước đã hiệu quả - trình tự những hành động dẫn đến thành công
• Những chỉnh sửa bạn đã thực hiện - những nơi bạn đã hướng dẫn cách tiếp cận của agent (ví dụ: “sử dụng thư viện X thay vì Y”, “kiểm tra trường hợp ngoại lệ Z”)
• Định dạng đầu vào/đầu ra - dữ liệu đầu vào và đầu ra trông như thế nào
• Ngữ cảnh bạn đã cung cấp - các sự kiện, quy ước hoặc ràng buộc cụ thể của dự án mà agent chưa biết​

Tổng hợp từ các tài liệu dự án hiện có

Khi có một lượng kiến ​​thức hiện có, bạn có thể đưa nó vào LLM và yêu cầu nó tổng hợp một skill. Một skill về đường dẫn dữ liệu được tổng hợp từ các báo cáo sự cố và sổ tay vận hành thực tế của nhóm bạn sẽ hoạt động tốt hơn một skill được tổng hợp từ một bài viết chung chung về “các thực tiễn tốt nhất về kỹ thuật dữ liệu”, bởi vì nó nắm bắt được lược đồ, những chế độ lỗi và quy trình phục hồi của bạn. Điều quan trọng là tài liệu cụ thể của dự án, không phải tài liệu tham khảo chung chung. Nguồn tài liệu tốt bao gồm:

• Tài liệu nội bộ, sổ tay vận hành và hướng dẫn phong cách
• Thông số kỹ thuật API, lược đồ và file cấu hình
• Nhận xét đánh giá code và công cụ theo dõi sự cố (ghi lại các mối quan ngại thường xuyên và kỳ vọng của người đánh giá)
• Lịch sử kiểm soát phiên bản, đặc biệt là những bản vá lỗi và sửa lỗi (tiết lộ các mẫu thông qua những gì thực sự đã thay đổi)
• Các trường hợp lỗi thực tế và cách giải quyết chúng

Tinh chỉnh bằng cách thực thi thực tế

Bản nháp đầu tiên của một skill thường cần được tinh chỉnh. Chạy skill đó với các tác vụ thực tế, sau đó đưa kết quả - tất cả, không chỉ các lỗi - trở lại quy trình tạo. Hãy tự hỏi: điều gì đã gây ra kết quả dương tính giả? Điều gì đã bị bỏ sót? Điều gì có thể được loại bỏ?

Ngay cả một lần chạy thử rồi sửa đổi cũng cải thiện đáng kể chất lượng, và các lĩnh vực phức tạp thường được hưởng lợi từ nhiều lần chạy như vậy.

Để có cách tiếp cận có cấu trúc hơn cho quá trình lặp lại, bao gồm các trường hợp thử nghiệm, khẳng định và chấm điểm.

Sử dụng ngữ cảnh một cách khôn ngoan

Sau khi một skill được kích hoạt, toàn bộ nội dung SKILL.md của nó sẽ được load vào cửa sổ ngữ cảnh của agent cùng với lịch sử hội thoại, ngữ cảnh hệ thống và các skill đang hoạt động khác. Mỗi từ trong skill của bạn đều cạnh tranh sự chú ý của agent với mọi thứ khác trong cửa sổ đó.

Thêm những gì agent còn thiếu, bỏ qua những gì đã biết

Tập trung vào những gì agent sẽ không biết nếu không có skill của bạn: Các quy ước cụ thể của dự án, những quy trình cụ thể theo lĩnh vực, các trường hợp ngoại lệ không rõ ràng và những công cụ hoặc API cụ thể cần sử dụng. Bạn không cần phải giải thích PDF là gì, HTTP hoạt động như thế nào hoặc việc di chuyển cơ sở dữ liệu làm gì.

<!-- Quá dài dòng - agent đã biết PDF là gì -->
## Trích xuất văn bản từ PDF

File PDF (Portable Document Format) là một định dạng file phổ biến chứa
văn bản, hình ảnh và các nội dung khác. Để trích xuất văn bản từ PDF, bạn cần
sử dụng thư viện. pdfplumber được khuyến nghị vì nó xử lý tốt hầu hết các trường hợp.

<!-- Tốt hơn - bỏ qua phần mà agent không tự biết -->
## Trích xuất văn bản từ PDF

Sử dụng pdfplumber để trích xuất văn bản. Đối với tài liệu được scan, hãy sử dụng
pdf2image với pytesseract.

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Hãy tự hỏi bản thân về từng nội dung: “Liệu agent có làm sai việc này nếu không có hướng dẫn không?” Nếu câu trả lời là không, hãy loại bỏ nó. Nếu bạn không chắc chắn, hãy kiểm tra lại. Và nếu agent đã xử lý toàn bộ nhiệm vụ tốt mà không cần skill đó, thì skill đó có thể không mang lại giá trị.

Thiết kế các đơn vị mạch lạc

Việc quyết định một skill nên bao gồm những gì cũng giống như việc quyết định một chức năng nên làm gì: Bạn muốn nó bao hàm một đơn vị công việc mạch lạc, kết hợp tốt với các skill khác. Các skill có phạm vi quá hẹp buộc nhiều skill phải được load cho một nhiệm vụ duy nhất, dẫn đến nguy cơ lãng phí tài nguyên và xung đột hướng dẫn. Các skill có phạm vi quá rộng trở nên khó kích hoạt chính xác. Một skill để truy vấn cơ sở dữ liệu và định dạng kết quả có thể là một đơn vị mạch lạc, trong khi một skill cũng bao gồm quản trị cơ sở dữ liệu có lẽ đang cố gắng làm quá nhiều việc.

Hướng đến mức độ chi tiết vừa phải

Các skill quá toàn diện có thể gây hại nhiều hơn là có lợi - agent sẽ khó trích xuất những gì liên quan và có thể theo đuổi những con đường không hiệu quả do các hướng dẫn không áp dụng cho nhiệm vụ hiện tại gây ra. Hướng dẫn ngắn gọn, từng bước kèm ví dụ thực tế thường hiệu quả hơn tài liệu quá chi tiết. Khi bạn thấy mình đang phải xử lý mọi trường hợp ngoại lệ, hãy cân nhắc xem liệu hầu hết các trường hợp đó có thể được xử lý tốt hơn bằng phán đoán của agent hay không.

Cấu trúc các skill lớn với việc tiết lộ dần dần

Thông số kỹ thuật khuyến nghị giữ SKILL.md dưới 500 dòng và 5.000 token - chỉ những hướng dẫn cốt lõi mà agent cần trong mỗi lần chạy. Khi một skill thực sự cần nhiều nội dung hơn, hãy chuyển tài liệu tham khảo chi tiết sang các file riêng biệt trong thư mục references/ hoặc những thư mục tương tự.

Điều quan trọng là phải cho agent biết khi nào cần load từng file. “Đọc references/api-errors.md nếu API trả về mã trạng thái khác 200” hữu ích hơn là câu chung chung “xem references/ để biết chi tiết”. Điều này cho phép agent load ngữ cảnh theo yêu cầu chứ không phải ngay từ đầu, đó là cách mà việc tiết lộ dần dần được thiết kế để hoạt động.

Điều chỉnh quyền kiểm soát

Không phải mọi phần của một skill đều cần cùng mức độ chi tiết. Hãy điều chỉnh độ cụ thể của hướng dẫn cho phù hợp với mức độ nhạy cảm của nhiệm vụ.

Phù hợp giữa tính cụ thể và tính dễ bị ảnh hưởng

Cho phép agent tự do hành động khi có nhiều phương pháp hợp lệ và nhiệm vụ cho phép sự biến đổi. Đối với các hướng dẫn linh hoạt, việc giải thích lý do có thể hiệu quả hơn những chỉ thị cứng nhắc - một agent hiểu được mục đích đằng sau hướng dẫn sẽ đưa ra các quyết định phụ thuộc vào ngữ cảnh tốt hơn. Skill xem xét code có thể mô tả những gì cần tìm mà không cần quy định các bước chính xác:

## Quy trình kiểm tra code

1. Kiểm tra tất cả các truy vấn cơ sở dữ liệu xem có lỗi tấn công SQL injection hay không (sử dụng truy vấn tham số hóa)
2. Xác minh kiểm tra xác thực trên mọi endpoint
3. Tìm kiếm các điều kiện tranh chấp trong những đường dẫn code đồng thời
4. Xác nhận thông báo lỗi không làm lộ thông tin nội bộ

Hãy đưa ra hướng dẫn cụ thể khi các hoạt động dễ bị ảnh hưởng, tính nhất quán là điều quan trọng hoặc cần tuân theo một trình tự cụ thể:

## Di chuyển cơ sở dữ liệu

Chạy chính xác chuỗi lệnh sau:

```bash
python scripts/migrate.py --verify --backup
```

Không được sửa đổi lệnh hoặc thêm các flag bổ sung.

Hầu hết các skill đều cần sự kết hợp của nhiều yếu tố. Hãy điều chỉnh từng phần một cách độc lập.

Cung cấp các thiết lập mặc định, không phải menu

Khi có nhiều công cụ hoặc phương pháp có thể hiệu quả, hãy chọn một thiết lập mặc định và đề cập ngắn gọn đến các phương án thay thế thay vì trình bày chúng như những lựa chọn ngang nhau.

<!-- Quá nhiều tùy chọn -->
Bạn có thể sử dụng pypdf, pdfplumber, PyMuPDF hoặc pdf2image...

<!-- Xóa tùy chọn mặc định bằng phím tắt -->
Sử dụng pdfplumber để trích xuất văn bản:

```python
import pdfplumber
```

Đối với các file PDF được scan cần nhận dạng ký tự quang học (OCR), hãy sử dụng pdf2image với pytesseract.

Ưu tiên quy trình hơn là tuyên bố

Một skill nên dạy người học cách tiếp cận một nhóm vấn đề, chứ không phải dạy họ phải tạo ra sản phẩm gì cho một trường hợp cụ thể. So sánh:

<!-- Câu trả lời cụ thể - chỉ hữu ích cho nhiệm vụ này -->
Kết nối bảng `orders` với bảng `customers` dựa trên `customer_id`, lọc theo điều kiện
`region = 'EMEA'`, và tính tổng cột `amount`.

<!-- Phương pháp có thể tái sử dụng - hoạt động với bất kỳ truy vấn phân tích nào -->
1. Đọc lược đồ từ `references/schema.yaml` để tìm các bảng liên quan
2. Kết nối các bảng bằng cách sử dụng quy ước foreign key `_id`
3. Áp dụng bất kỳ bộ lọc nào từ yêu cầu của người dùng dưới dạng mệnh đề WHERE
4. Tổng hợp các cột số khi cần và định dạng thành bảng markdown

Điều này không có nghĩa là các skill không thể bao gồm những chi tiết cụ thể - các mẫu định dạng đầu ra, những ràng buộc như “không bao giờ xuất thông tin nhận dạng cá nhân”, và các hướng dẫn cụ thể cho từng công cụ đều rất có giá trị. Vấn đề là phương pháp tiếp cận nên mang tính tổng quát ngay cả khi các chi tiết riêng lẻ rất cụ thể.

Các mẫu hướng dẫn hiệu quả

Đây là các kỹ thuật có thể tái sử dụng để cấu trúc nội dung skill. Không phải mọi skill đều cần tất cả chúng - hãy sử dụng những skill phù hợp với nhiệm vụ của bạn.

Các phần lưu ý quan trọng

Nội dung có giá trị cao nhất trong nhiều skill là danh sách các vấn đề khó lường - những sự thật cụ thể về môi trường đi ngược lại các giả định hợp lý. Đây không phải là lời khuyên chung chung (“xử lý lỗi một cách thích hợp”) mà là các biện pháp khắc phục cụ thể cho những sai lầm mà agent sẽ mắc phải nếu không được hướng dẫn khác đi:

## Những điểm cần lưu ý

- Bảng `users` sử dụng xóa mềm. Các truy vấn phải bao gồm
`WHERE deleted_at IS NULL` nếu không kết quả sẽ bao gồm các tài khoản đã bị vô hiệu hóa.
- ID người dùng là `user_id` trong cơ sở dữ liệu, `uid` trong dịch vụ xác thực,
và `accountId` trong API thanh toán. Cả ba đều tham chiếu đến cùng một giá trị.
- Endpoint `/health` trả về mã trạng thái 200 miễn là máy chủ web đang chạy,
ngay cả khi kết nối cơ sở dữ liệu bị ngắt. Sử dụng `/ready` để kiểm tra đầy đủ
tình trạng hoạt động của dịch vụ.

Hãy lưu trữ các lỗi thường gặp (gotchas) trong file SKILL.md để agent đọc chúng trước khi gặp phải tình huống. Một file tham chiếu riêng biệt cũng có tác dụng nếu bạn cho agent biết khi nào cần load nó, nhưng đối với các vấn đề không rõ ràng, agent có thể không nhận ra yếu tố kích hoạt.

Template định dạng đầu ra

Khi bạn cần agent tạo ra đầu ra ở định dạng cụ thể, hãy cung cấp một template. Điều này đáng tin cậy hơn so với việc mô tả định dạng bằng văn xuôi, vì các agent khớp mẫu tốt với những cấu trúc cụ thể. Các template ngắn có thể được lưu trực tiếp trong SKILL.md; đối với những template dài hơn hoặc các template chỉ cần thiết trong một số trường hợp nhất định, hãy lưu trữ chúng trong thư mục assets/ và tham chiếu chúng từ SKILL.md để chúng chỉ được load khi cần thiết.

## Cấu trúc báo cáo

Sử dụng template này, điều chỉnh các phần khi cần thiết cho phân tích cụ thể:

```markdown
# [Tiêu đề phân tích]

## Tóm tắt
[Tổng quan một đoạn về các phát hiện chính]

## Các phát hiện chính
- Phát hiện 1 kèm dữ liệu hỗ trợ
- Phát hiện 2 kèm dữ liệu hỗ trợ

## Kiến nghị
1. Kiến nghị cụ thể có thể thực hiện
2. Kiến nghị cụ thể có thể thực hiện
```

Danh sách kiểm tra cho quy trình làm việc nhiều bước

Một danh sách kiểm tra rõ ràng giúp người thực hiện theo dõi tiến độ và tránh bỏ sót các bước, đặc biệt khi những bước có sự phụ thuộc hoặc các bước kiểm tra xác thực.

## Quy trình xử lý biểu mẫu

Tiến độ:
- [ ] Bước 1: Phân tích biểu mẫu (chạy `scripts/analyze_form.py`)
- [ ] Bước 2: Tạo ánh xạ trường (chỉnh sửa `fields.json`)
- [ ] Bước 3: Xác thực ánh xạ (chạy `scripts/validate_fields.py`)
- [ ] Bước 4: Điền biểu mẫu (chạy `scripts/fill_form.py`)
- [ ] Bước 5: Kiểm tra kết quả (chạy `scripts/verify_output.py`)

Vòng lặp xác thực

Hướng dẫn agent tự xác thực công việc của mình trước khi tiếp tục. Mô hình là: Thực hiện công việc, chạy trình xác thực (một script, danh sách kiểm tra tham chiếu hoặc tự kiểm tra), khắc phục mọi sự cố và lặp lại cho đến khi quá trình xác thực thành công.

## Quy trình chỉnh sửa

1. Thực hiện chỉnh sửa
2. Chạy kiểm tra hợp lệ: `python scripts/validate.py output/`
3. Nếu kiểm tra hợp lệ thất bại:
  - Xem lại thông báo lỗi
  - Khắc phục sự cố
  - Chạy kiểm tra hợp lệ lại
4. Chỉ tiếp tục khi kiểm tra hợp lệ thành công

Tài liệu tham khảo cũng có thể đóng vai trò là “công cụ kiểm định” - hướng dẫn agent kiểm tra công việc của mình so với tài liệu tham khảo trước khi hoàn tất.

Lập kế hoạch - Kiểm định - Thực thi

Đối với các thao tác hàng loạt hoặc thao tác phá hủy, hãy để agent tạo một kế hoạch trung gian ở định dạng có cấu trúc, kiểm định nó so với nguồn thông tin chính xác, và chỉ sau đó mới thực thi.

## Điền biểu mẫu PDF

1. Trích xuất các trường biểu mẫu: `python scripts/analyze_form.py input.pdf` → `form_fields.json`
    (liệt kê tên, loại và trạng thái bắt buộc của từng trường)
2. Tạo `field_values.json` ánh xạ từng tên trường với giá trị tương ứng
3. Xác thực: `python scripts/validate_fields.py form_fields.json field_values.json`
    (kiểm tra xem mọi tên trường có tồn tại trong biểu mẫu, loại tương thích và
    không thiếu các trường bắt buộc)
4. Nếu xác thực thất bại, hãy sửa đổi `field_values.json` và xác thực lại
5. Điền biểu mẫu: `python scripts/fill_form.py input.pdf field_values.json output.pdf`

Thành phần quan trọng là bước 3: Một script xác thực kiểm tra kế hoạch (field_values.json) so với nguồn dữ liệu chính xác (form_fields.json). Các lỗi như “Không tìm thấy trường ‘signature_date’ - các trường khả dụng: customer_name, order_total, signature_date_signed” cung cấp cho agent đủ thông tin để tự sửa lỗi.

Đóng gói các script có thể tái sử dụng

Khi lặp lại quá trình phát triển một skill, hãy so sánh dấu vết thực thi của agent trên các trường hợp thử nghiệm. Nếu bạn nhận thấy agent tự động tạo lại cùng một logic trong mỗi lần chạy - xây dựng biểu đồ, phân tích cú pháp một định dạng cụ thể, xác thực đầu ra - đó là tín hiệu cho thấy cần viết một script đã được kiểm thử một lần và đóng gói nó trong thư mục scripts/.