Cách tối ưu hóa mô tả skill

Làm thế nào để cải thiện mô tả skill của bạn để nó được kích hoạt một cách đáng tin cậy khi có yêu cầu phù hợp?

Một skill chỉ hữu ích khi nó được kích hoạt. Trường mô tả trong phần đầu của file SKILL.md là cơ chế chính mà các agent sử dụng để quyết định xem có nên load skill đó cho một tác vụ nhất định hay không. Mô tả không đầy đủ nghĩa là skill sẽ không được kích hoạt khi cần; mô tả quá chung chung có nghĩa là nó được kích hoạt khi không cần.

Hướng dẫn này sẽ trình bày cách kiểm tra và cải thiện mô tả skill của bạn một cách có hệ thống để đảm bảo độ chính xác khi kích hoạt.

Cách thức hoạt động của việc kích hoạt skill

Các agent sử dụng phương pháp tiết lộ dần dần để quản lý ngữ cảnh. Khi khởi động, chúng chỉ load name và description của mỗi skill có sẵn - vừa đủ để quyết định khi nào một skill có thể phù hợp. Khi tác vụ của người dùng khớp với mô tả, agent sẽ đọc toàn bộ file SKILL.md vào ngữ cảnh và làm theo hướng dẫn của nó.

Điều này có nghĩa là mô tả chịu toàn bộ trách nhiệm kích hoạt. Nếu mô tả không truyền đạt được thời điểm skill hữu ích, agent sẽ không biết để sử dụng nó.

Một điểm quan trọng cần lưu ý: Các agent thường chỉ tham khảo skill cho những tác vụ yêu cầu kiến ​​thức hoặc khả năng vượt quá khả năng xử lý của chúng. Một yêu cầu đơn giản, một bước như “đọc file PDF này” có thể không kích hoạt skill đọc PDF ngay cả khi mô tả hoàn toàn khớp, bởi vì agent có thể xử lý nó bằng các công cụ cơ bản. Những tác vụ liên quan đến kiến ​​thức chuyên môn - một API không quen thuộc, một quy trình làm việc đặc thù theo lĩnh vực hoặc một định dạng không phổ biến - là nơi mà một mô tả được viết tốt có thể tạo ra sự khác biệt.

Viết mô tả hiệu quả

Trước khi thử nghiệm, việc biết một mô tả tốt trông như thế nào là rất hữu ích. Có một vài nguyên tắc:

• Sử dụng câu mệnh lệnh. Định dạng mô tả như một hướng dẫn cho agent: “Sử dụng skill này khi…” thay vì “skill này thực hiện…” agent đang quyết định có hành động hay không, vì vậy hãy cho nó biết khi nào cần hành động.
• Tập ​​trung vào ý định của người dùng, không phải cách triển khai. Mô tả những gì người dùng đang cố gắng đạt được, không phải cơ chế bên trong của skill. Agent sẽ khớp với những gì người dùng yêu cầu.
• Nên đưa ra mô tả mang tính thúc ép. Liệt kê rõ ràng các ngữ cảnh mà skill được áp dụng, bao gồm cả những trường hợp người dùng không nêu trực tiếp domain: “ngay cả khi chúng không đề cập rõ ràng đến ‘CSV’ hoặc ‘phân tích’”.
• Hãy giữ cho nội dung ngắn gọn. Một vài câu đến một đoạn ngắn thường là phù hợp - đủ dài để bao quát phạm vi của skill, đủ ngắn để không làm phình to ngữ cảnh của agent trên nhiều skill. Đặc tả quy định giới hạn cứng là 1024 ký tự.

Thiết kế các truy vấn đánh giá kích hoạt

Để kiểm tra việc kích hoạt, bạn cần một tập hợp các truy vấn đánh giá - những prompt thực tế của người dùng được gắn nhãn xem chúng có nên kích hoạt skill của bạn hay không.

[
  { "query": "Tôi có một bảng tính trong ~/data/q4_results.xlsx với doanh thu ở cột C và chi phí ở cột D — bạn có thể thêm cột tỷ suất lợi nhuận và highlight bất kỳ khoản nào dưới 10% không?", "should_trigger": true },
  { "query": "cách nhanh nhất để chuyển đổi file JSON này sang YAML là gì", "should_trigger": false }
]

Hãy đặt mục tiêu khoảng 20 truy vấn: 8 - 10 truy vấn nên kích hoạt và 8 - 10 truy vấn không nên kích hoạt.

Các truy vấn nên kích hoạt

Những truy vấn này kiểm tra xem mô tả có nắm bắt được phạm vi của skill hay không. Hãy thay đổi chúng theo một số khía cạnh:

• Cách diễn đạt: Một số trang trọng, một số thân mật, một số có lỗi chính tả hoặc viết tắt.
• Tính rõ ràng: Một số nêu trực tiếp tên lĩnh vực của skill (“phân tích file CSV này”), những truy vấn khác mô tả nhu cầu mà không nêu tên (“sếp tôi muốn một biểu đồ từ file dữ liệu này”).
• Chi tiết: Kết hợp các prompt ngắn gọn với những prompt nhiều ngữ cảnh - một prompt ngắn gọn “phân tích file CSV bán hàng của tôi và tạo biểu đồ” cùng với một thông điệp dài hơn có đường dẫn file, tên cột và bối cảnh.
• Độ phức tạp: Thay đổi số bước và điểm quyết định. Bao gồm các tác vụ một bước cùng với những quy trình làm việc nhiều bước để kiểm tra xem nhân viên có thể nhận ra skill đó có liên quan hay không khi tác vụ mà nó giải quyết nằm trong một chuỗi lớn hơn.

Các truy vấn nên kích hoạt hữu ích nhất là những truy vấn mà skill đó sẽ hữu ích nhưng mối liên hệ không rõ ràng chỉ từ truy vấn. Đây là những trường hợp mà cách diễn đạt mô tả tạo nên sự khác biệt - nếu truy vấn đã hỏi chính xác những gì skill đó làm, bất kỳ mô tả hợp lý nào cũng sẽ kích hoạt.

Các truy vấn không nên kích hoạt

Các trường hợp kiểm thử tiêu cực có giá trị nhất là những trường hợp gần đúng - các truy vấn có chung từ khóa hoặc khái niệm với skill của bạn nhưng thực tế cần một thứ khác. Những trường hợp này kiểm tra xem mô tả có chính xác hay không, chứ không chỉ chung chung.

Đối với skill phân tích CSV, các ví dụ có chút tiêu cực sẽ là:

• "Viết một hàm Fibonacci" - rõ ràng là không liên quan, không kiểm tra gì cả.
• "Thời tiết hôm nay thế nào?" - không có từ khóa trùng lặp, quá dễ.

Các ví dụ cực kỳ tiêu cực:

• "Tôi cần cập nhật các công thức trong bảng tính ngân sách Excel của mình" - chia sẻ các khái niệm "bảng tính" và "dữ liệu", nhưng cần chỉnh sửa Excel, không phải phân tích CSV.
• "Bạn có thể viết một kịch bản Python đọc CSV và upload từng hàng lên cơ sở dữ liệu PostgreSQL của chúng tôi không?" - liên quan đến CSV, nhưng nhiệm vụ là ETL cơ sở dữ liệu, không phải phân tích.

Mẹo để thực tế hơn

Các prompt của người dùng thực chứa ngữ cảnh mà những truy vấn kiểm thử chung chung thiếu. Bao gồm:

• Đường dẫn file (~/Downloads/report_final_v2.xlsx)
• Ngữ cảnh cá nhân ("Quản lý yêu cầu tôi...")
• Chi tiết cụ thể (tên cột, tên công ty, giá trị dữ liệu)
• Ngôn ngữ thông thường, viết tắt và đôi khi có lỗi chính tả​

Kiểm tra xem mô tả có kích hoạt hay không

Cách tiếp cận cơ bản: Chạy từng truy vấn thông qua agent của bạn với skill đã được cài đặt và quan sát xem agent có gọi nó hay không. Đảm bảo skill đã được đăng ký và có thể được agent của bạn tìm thấy - cách thức hoạt động này khác nhau tùy thuộc vào client (ví dụ: thư mục skill, file cấu hình hoặc flag CLI).

Hầu hết các agent client cung cấp một số hình thức quan sát - nhật ký thực thi, lịch sử gọi công cụ hoặc đầu ra chi tiết - cho phép bạn xem skill nào đã được tham khảo trong quá trình chạy. Kiểm tra tài liệu của client để biết chi tiết. Skill được kích hoạt nếu agent load file SKILL.md của skill; nó không được kích hoạt nếu agent tiếp tục mà không tham khảo file đó.

Một truy vấn “thành công” nếu:

• should_trigger là true và skill được kích hoạt, hoặc
• should_trigger là false và skill không được kích hoạt.

Chạy nhiều lần

Hành vi của mô hình không mang tính xác định - cùng một truy vấn có thể kích hoạt skill trong một lần chạy nhưng lần tiếp theo thì không. Chạy mỗi truy vấn nhiều lần (3 là điểm khởi đầu hợp lý) và tính toán tỷ lệ kích hoạt: tỷ lệ các lần chạy mà skill được kích hoạt.

Một truy vấn nên kích hoạt sẽ thành công nếu tỷ lệ kích hoạt của nó cao hơn ngưỡng (0,5 là giá trị mặc định hợp lý). Một truy vấn không nên kích hoạt sẽ thành công nếu tỷ lệ kích hoạt của nó thấp hơn ngưỡng đó.

Với 20 truy vấn, mỗi truy vấn chạy 3 lần, tổng cộng là 60 lần kích hoạt. Bạn sẽ cần viết script cho việc này. Đây là cấu trúc chung - thay thế logic kích hoạt và phát hiện claude trong check_triggered bằng bất cứ thứ gì mà agent client cung cấp:

#!/bin/bash
QUERIES_FILE="${1:?Usage: $0 <queries.json>}"
SKILL_NAME="my-skill"
RUNS=3

# Ví dụ này sử dụng đầu ra JSON của Claude Code để kiểm tra các lệnh gọi công cụ Skill.
# Thay thế hàm này bằng logic phát hiện dành cho agent client của bạn.
# Nên trả về 0 (thành công) nếu skill được kích hoạt, ngược lại trả về 1.
check_triggered() {
  local query="$1"
  claude -p "$query" --output-format json 2>/dev/null \
    | jq -e --arg skill "$SKILL_NAME" \
      'any(.messages[].content[]; .type == "tool_use" and .name == "Skill" and .input.skill == $skill)' \
      > /dev/null 2>&1
}

count=$(jq length "$QUERIES_FILE")
for i in $(seq 0 $((count - 1))); do
  query=$(jq -r ".[$i].query" "$QUERIES_FILE")
  should_trigger=$(jq -r ".[$i].should_trigger" "$QUERIES_FILE")
  triggers=0

  for run in $(seq 1 $RUNS); do
    check_triggered "$query" && triggers=$((triggers + 1))
  done

  jq -n \
    --arg query "$query" \
    --argjson should_trigger "$should_trigger" \
    --argjson triggers "$triggers" \
    --argjson runs "$RUNS" \
    '{query: $query, should_trigger: $should_trigger, triggers: $triggers, runs: $runs, trigger_rate: ($triggers / $runs)}'
done | jq -s '.'

♦ Nếu agent client của bạn hỗ trợ tính năng này, bạn có thể dừng quá trình chạy sớm khi kết quả đã rõ ràng - agent hoặc đã tham khảo skill hoặc bắt đầu làm việc mà không cần skill đó. Điều này có thể giảm đáng kể thời gian và chi phí chạy toàn bộ tập dữ liệu đánh giá.

Tránh hiện tượng quá khớp (overfitting) với việc chia tập huấn luyện/kiểm chứng

Nếu tối ưu hóa mô tả cho tất cả các truy vấn của mình, bạn có nguy cơ bị quá khớp - tạo ra một mô tả hoạt động tốt với những cách diễn đạt cụ thể này nhưng lại thất bại với các cách diễn đạt mới.

Giải pháp là chia tập truy vấn của bạn:

• Tập huấn luyện (~60%): Các truy vấn bạn sử dụng để xác định lỗi và hướng dẫn cải tiến.
• Tập ​​kiểm chứng (~40%): Các truy vấn bạn để riêng và chỉ sử dụng để kiểm tra xem những cải tiến có được khái quát hóa hay không.

Hãy đảm bảo cả hai tập đều chứa một tỷ lệ cân đối giữa các truy vấn nên kích hoạt và không nên kích hoạt - đừng vô tình đặt tất cả những kết quả tích cực vào một tập. Trộn ngẫu nhiên và giữ nguyên tỷ lệ chia trong suốt các lần lặp để bạn đang so sánh những thứ tương đồng. Nếu đang sử dụng một script như trên, bạn có thể chia các truy vấn của mình thành hai file - train_queries.json và validation_queries.json - và chạy script đó trên từng file riêng biệt.

Vòng lặp tối ưu hóa

1. Đánh giá mô tả hiện tại trên cả tập huấn luyện và tập xác thực. Kết quả huấn luyện sẽ hướng dẫn các thay đổi của bạn; kết quả xác thực cho bạn biết liệu những thay đổi đó có mang tính khái quát hay không.

2. Xác định các lỗi trong tập huấn luyện: những truy vấn nào đáng lẽ phải kích hoạt nhưng không được kích hoạt? Những truy vấn nào không nên kích hoạt nhưng lại được kích hoạt?

• Chỉ sử dụng các lỗi trong tập huấn luyện để hướng dẫn những thay đổi của bạn - cho dù bạn đang tự sửa đổi mô tả hay sử dụng LLM, hãy loại bỏ kết quả của tập xác thực khỏi quy trình.

3. Sửa đổi mô tả. Tập trung vào tính khái quát:

• Nếu các truy vấn đáng lẽ phải kích hoạt bị lỗi, mô tả có thể quá hẹp. Mở rộng phạm vi hoặc thêm ngữ cảnh về thời điểm skill này hữu ích.
• Nếu các truy vấn không nên kích hoạt gây ra lỗi, mô tả có thể quá rộng. Thêm chi tiết về những gì skill này không làm, hoặc làm rõ ranh giới giữa skill này và các khả năng liền kề. Tránh thêm các từ khóa cụ thể từ các truy vấn thất bại - đó là hiện tượng quá khớp (overfitting). Thay vào đó, hãy tìm danh mục hoặc khái niệm chung mà các truy vấn đó đại diện và tập trung vào đó.
• Nếu bạn gặp khó khăn sau vài lần thử, hãy thử một cách tiếp cận khác về cấu trúc cho phần mô tả thay vì chỉ tinh chỉnh nhỏ. Một cách diễn đạt hoặc cấu trúc câu khác có thể mang lại hiệu quả vượt trội hơn so với việc tinh chỉnh thông thường.
• Kiểm tra xem phần mô tả có nằm trong giới hạn 1024 ký tự hay không - phần mô tả có xu hướng dài ra trong quá trình tối ưu hóa.

4. Lặp lại các bước 1-3 cho đến khi tất cả các truy vấn trong tập huấn luyện đều vượt qua hoặc bạn không còn thấy sự cải thiện đáng kể.

5. Chọn phiên bản tốt nhất dựa trên tỷ lệ vượt qua kiểm định - tỷ lệ các truy vấn trong tập kiểm định đã vượt qua. Lưu ý rằng mô tả tốt nhất có thể không phải là mô tả cuối cùng bạn tạo ra; một phiên bản trước đó có thể có tỷ lệ vượt qua kiểm định cao hơn so với những phiên bản sau này bị quá khớp với tập huấn luyện.

5 lần thử thường là đủ. Nếu hiệu suất không được cải thiện, vấn đề có thể nằm ở các truy vấn (quá dễ, quá khó hoặc được gắn nhãn kém) chứ không phải ở phần mô tả.

Áp dụng kết quả

Sau khi bạn đã chọn mô tả tốt nhất:

1. Cập nhật trường mô tả trong phần frontmatter của SKILL.md.
2. Xác minh mô tả không vượt quá giới hạn 1024 ký tự.
3. Xác minh mô tả kích hoạt như mong đợi. Hãy thử một vài prompt thủ công để kiểm tra nhanh. Để kiểm tra kỹ lưỡng hơn, hãy viết 5 - 10 truy vấn mới (kết hợp giữa truy vấn nên kích hoạt và không nên kích hoạt) và chạy chúng qua script đánh giá - vì những truy vấn này chưa từng là một phần của quy trình tối ưu hóa, chúng sẽ cho bạn một sự kiểm tra trung thực về việc mô tả có tính khái quát hay không.

So sánh trước và sau:

# Trước
description: Xử lý các file CSV.

# Sau
description: >
  Phân tích các file dữ liệu CSV và dạng bảng - tính toán số liệu thống kê tóm tắt,
  thêm các cột dẫn xuất, tạo biểu đồ và làm sạch dữ liệu lộn xộn. Sử dụng skill này
  khi người dùng có file CSV, TSV hoặc Excel và muốn
  khám phá, chuyển đổi hoặc trực quan hóa dữ liệu, ngay cả khi họ không
  đề cập rõ ràng đến "CSV" hoặc "phân tích".

Phần mô tả được cải tiến cụ thể hơn về chức năng của skill (thống kê tóm tắt, cột dẫn xuất, biểu đồ, làm sạch dữ liệu) và bao quát hơn về phạm vi áp dụng (CSV, TSV, Excel; ngay cả khi không có từ khóa rõ ràng).