Đánh giá chất lượng đầu ra skill

Hãy kiểm tra xem skill của bạn có tạo ra kết quả tốt hay không bằng cách sử dụng phương pháp lặp lại dựa trên đánh giá!

Bạn đã viết một skill, thử nghiệm nó với một prompt và dường như nó hoạt động. Nhưng liệu nó có hoạt động đáng tin cậy - trên nhiều prompt khác nhau, trong các trường hợp ngoại lệ, tốt hơn là không có skill nào cả? Chạy các đánh giá có cấu trúc (evals) sẽ trả lời những câu hỏi này và cung cấp cho bạn một vòng phản hồi để cải thiện skill một cách có hệ thống.

Thiết kế các trường hợp kiểm thử

Một trường hợp kiểm thử có 3 phần:

• Prompt: Một thông báo thực tế của người dùng - loại thông báo mà ai đó thực sự sẽ nhập.
• Kết quả mong đợi: Một mô tả dễ hiểu về những gì trông giống như thành công.
• File đầu vào (tùy chọn): Các file mà skill cần để hoạt động.

Lưu trữ các trường hợp kiểm thử trong evals/evals.json bên trong thư mục skill của bạn:

{
  "skill_name": "csv-analyzer",
  "evals": [
    {
      "id": 1,
      "prompt": "Tôi có một file CSV chứa dữ liệu doanh số bán hàng hàng tháng trong thư mục data/sales_2025.csv. Bạn có thể tìm ra 3 tháng có doanh thu cao nhất và tạo biểu đồ cột được không?",
      "expected_output": "Biểu đồ cột thể hiện doanh thu cao nhất trong 3 tháng, với trục và giá trị được ghi nhãn.",
      "files": ["evals/files/sales_2025.csv"]
    },
    {
      "id": 2,
      "prompt": "trong thư mục downloads của tôi có một file CSV tên là customers.csv, một số hàng bị thiếu email — bạn có thể chỉnh sửa và cho tôi biết có bao nhiêu hàng bị thiếu không?",
      "expected_output": "File CSV đã được làm sạch, trong đó các email bị thiếu đã được xử lý, cùng với số lượng email bị thiếu.",
      "files": ["evals/files/customers.csv"]
    }
  ]
}

Mẹo viết prompt kiểm thử tốt:

• Bắt đầu với 2 - 3 trường hợp kiểm thử. Đừng đầu tư quá nhiều trước khi bạn thấy kết quả vòng đầu tiên. Bạn có thể mở rộng tập hợp sau này.
• Đa dạng các prompt. Sử dụng các cách diễn đạt, mức độ chi tiết và mức độ trang trọng khác nhau. Một số prompt nên mang tính thông thường (“bạn có thể dọn dẹp file CSV này không?”), một số khác chính xác hơn (“Phân tích cú pháp file CSV tại data/input.csv, xóa các hàng có cột B rỗng và ghi kết quả vào data/output.csv”).
• Bao quát các trường hợp ngoại lệ. Bao gồm ít nhất một prompt kiểm tra điều kiện - đầu vào không đúng định dạng, yêu cầu bất thường hoặc trường hợp hướng dẫn của skill có thể không rõ ràng.
• Sử dụng ngữ cảnh thực tế. Người dùng thực tế đề cập đến đường dẫn file, tên cột và ngữ cảnh cá nhân. Các câu hỏi như “xử lý dữ liệu này” quá mơ hồ để kiểm tra bất cứ điều gì hữu ích.

Đừng lo lắng về việc xác định các kiểm tra đạt/không đạt cụ thể ngay bây giờ - chỉ cần các prompt và đầu ra dự kiến. Bạn sẽ thêm các kiểm tra chi tiết (gọi là cơ sở dẫn liệu) sau khi bạn thấy kết quả của lần chạy đầu tiên.

Chạy các bài kiểm thử đánh giá

Mô hình cốt lõi là chạy mỗi trường hợp kiểm thử hai lần: Một lần với skill và một lần không có skill đó (hoặc với phiên bản trước đó). Điều này cung cấp cho bạn một cơ sở để so sánh.

Cấu trúc không gian làm việc

Tổ chức kết quả đánh giá trong một thư mục không gian làm việc cùng với thư mục skill của bạn. Mỗi lần chạy qua vòng lặp đánh giá đầy đủ sẽ có thư mục iteration-N/ riêng. Bên trong đó, mỗi trường hợp kiểm thử sẽ có một thư mục eval với các thư mục con with_skill/ và without_skill/:

csv-analyzer/
├── SKILL.md
└── evals/
    └── evals.json
csv-analyzer-workspace/
└── iteration-1/
    ├── eval-top-months-chart/
    │   ├── with_skill/
    │   │   ├── outputs/       # Các file được tạo ra bởi quá trình chạy
    │   │   ├── timing.json    # Token và thời hạn
    │   │   └── grading.json   # Kết quả khẳng định
    │   └── without_skill/
    │       ├── outputs/
    │       ├── timing.json
    │       └── grading.json
    ├── eval-clean-missing-emails/
    │   ├── with_skill/
    │   │   ├── outputs/
    │   │   ├── timing.json
    │   │   └── grading.json
    │   └── without_skill/
    │       ├── outputs/
    │       ├── timing.json
    │       └── grading.json
    └── benchmark.json         # hống kê tổng hợp

File chính bạn tự viết là evals/evals.json. Các file JSON khác (grading.json, timing.json, benchmark.json) được tạo ra trong quá trình đánh giá - bởi agent, bởi những script hoặc bởi bạn.

Khởi tạo các lượt chạy

Mỗi lượt chạy đánh giá nên bắt đầu với một ngữ cảnh sạch - không có trạng thái còn sót lại từ các lượt chạy trước hoặc từ quá trình phát triển skill. Điều này đảm bảo agent chỉ làm theo những gì SKILL.md chỉ dẫn. Trong các môi trường hỗ trợ agent con (ví dụ: Claude Code), sự cô lập này diễn ra một cách tự nhiên: mỗi tác vụ con bắt đầu mới. Nếu không có agent con, hãy sử dụng một phiên riêng biệt cho mỗi lượt chạy.

Đối với mỗi lượt chạy, hãy cung cấp:

• Đường dẫn skill (hoặc không có skill cho đường cơ sở)
• Prompt kiểm thử
• Bất kỳ file đầu vào nào
• Thư mục đầu ra

Đây là một ví dụ về các hướng dẫn bạn sẽ cung cấp cho agent cho một lượt chạy có skill:

Thực hiện tác vụ này:
- Đường dẫn skill: /path/to/csv-analyzer
- Nhiệm vụ: Tôi có một file CSV chứa dữ liệu doanh số bán hàng hàng tháng trong thư mục data/sales_2025.csv.
Bạn có thể tìm ra 3 tháng có doanh thu cao nhất và tạo biểu đồ cột không?
- File đầu vào: evals/files/sales_2025.csv
- Lưu kết quả vào: csv-analyzer-workspace/iteration-1/eval-top-months-chart/with_skill/outputs/

Để thiết lập đường cơ sở, hãy sử dụng cùng một prompt nhưng không có đường dẫn skill, lưu vào without_skill/outputs/.

Khi cải thiện một skill hiện có, hãy sử dụng phiên bản trước đó làm đường cơ sở. Chụp ảnh màn hình trước khi chỉnh sửa (cp -r <đường dẫn skill> <không gian làm việc>/ảnh chụp màn hình skill/), trỏ quá trình chạy đường cơ sở đến ảnh chụp màn hình và lưu vào old_skill/outputs/ thay vì without_skill/.

Thu thập dữ liệu thời gian

Dữ liệu thời gian cho phép bạn so sánh thời gian và số token mà skill tiêu tốn so với đường cơ sở - một skill cải thiện đáng kể chất lượng đầu ra nhưng sử dụng gấp 3 lần token sẽ có sự đánh đổi khác so với một skill vừa tốt hơn vừa rẻ hơn. Khi mỗi lần chạy hoàn tất, hãy ghi lại số token và thời lượng:

{
  "total_tokens": 84852,
  "duration_ms": 23332
}

♦ Trong Claude Code, khi một tác vụ của agent phụ hoàn thành, thông báo hoàn thành tác vụ sẽ bao gồm total_tokens và duration_ms. Hãy lưu các giá trị này ngay lập tức - chúng không được lưu trữ ở bất kỳ nơi nào khác.

Viết các cơ sở dẫn liệu

Các cơ sở dẫn liệu là những câu lệnh có thể kiểm chứng được về những gì đầu ra nên chứa hoặc đạt được. Hãy thêm chúng sau khi bạn thấy vòng đầu tiên của các đầu ra - bạn thường không biết "tốt" trông như thế nào cho đến khi skill đã chạy xong.

Các cơ sở dẫn liệu tốt:

• "File đầu ra là JSON hợp lệ" - có thể kiểm chứng bằng lập trình.
• "Biểu đồ cột có trục được gắn nhãn" - cụ thể và có thể quan sát được.
• "Báo cáo bao gồm ít nhất 3 khuyến nghị" - có thể đếm được.

Các cơ sở dẫn liệu yếu:

• "Đầu ra tốt" - quá mơ hồ để đánh giá.
• "Đầu ra sử dụng chính xác cụm từ 'Tổng doanh thu: $X'" - quá dễ bị lỗi; đầu ra chính xác với cách diễn đạt khác sẽ bị lỗi.

Không phải mọi thứ đều cần một cơ sở dẫn liệu. Một số phẩm chất - phong cách viết, thiết kế trực quan, liệu đầu ra có "cảm thấy đúng" hay không - rất khó để phân tích thành các kiểm tra đạt/không đạt. Những lỗi này nên được phát hiện trong quá trình xem xét thủ công. Chỉ nên sử dụng các câu lệnh cơ sở dẫn liệu (assertions) cho những việc có thể kiểm tra một cách khách quan.

Thêm các câu lệnh cơ sở dẫn liệu vào mỗi trường hợp kiểm thử trong evals/evals.json:

{
  "skill_name": "csv-analyzer",
  "evals": [
    {
      "id": 1,
      "prompt": "Tôi có một file CSV chứa dữ liệu doanh số bán hàng hàng tháng trong thư mục data/sales_2025.csv. Bạn có thể tìm ra 3 tháng có doanh thu cao nhất và tạo biểu đồ cột được không?",
      "expected_output": "Biểu đồ cột thể hiện doanh thu cao nhất trong 3 tháng, với trục và giá trị được ghi nhãn.",
      "files": ["evals/files/sales_2025.csv"],
      "assertions": [
        "Kết quả đầu ra bao gồm một file hình ảnh biểu đồ cột.",
        "Biểu đồ thể hiện chính xác 3 tháng.",
        "Cả hai trục đều được dán nhãn.",
        "Tiêu đề hoặc chú thích của biểu đồ đề cập đến doanh thu."
      ]
    }
  ]
}

Chấm điểm kết quả

Chấm điểm có nghĩa là đánh giá từng cơ sở dẫn liệu dựa trên kết quả thực tế và ghi lại PASS hoặc FAIL kèm theo bằng chứng cụ thể. Bằng chứng nên trích dẫn hoặc tham chiếu đến kết quả, chứ không chỉ nêu ý kiến ​​cá nhân.

Cách đơn giản nhất là cung cấp kết quả và các cơ sở dẫn liệu cho một mô hình ngôn ngữ lớn (LLM) và yêu cầu nó đánh giá từng cơ sở dẫn liệu. Đối với các cơ sở dẫn liệu có thể được kiểm tra bằng mã (JSON hợp lệ, số hàng chính xác, file tồn tại với kích thước dự kiến), hãy sử dụng script xác minh - các script đáng tin cậy hơn so với đánh giá của LLM đối với những kiểm tra cơ học và có thể tái sử dụng trong nhiều lần lặp.

{
  "assertion_results": [
    {
      "text": "Kết quả đầu ra bao gồm một file hình ảnh biểu đồ cột.",
      "passed": true,
      "evidence": "Đã tìm thấy file chart.png (45KB) trong thư mục outputs."
    },
    {
      "text": "Biểu đồ thể hiện chính xác 3 tháng.",
      "passed": true,
      "evidence": "Biểu đồ hiển thị các cột biểu thị số liệu tháng 3, tháng 7 và tháng 11."
    },
    {
      "text": "Cả hai trục đều được dán nhãn.",
      "passed": false,
      "evidence": "Trục Y được ghi nhãn là 'Doanh thu ($)' nhưng trục X không có nhãn"
    },
    {
      "text": "Tiêu đề hoặc chú thích của biểu đồ đề cập đến doanh thu",
      "passed": true,
      "evidence": "Tiêu đề biểu đồ ghi là '3 tháng có doanh thu cao nhất''"
    }
  ],
  "summary": {
    "passed": 3,
    "failed": 1,
    "total": 4,
    "pass_rate": 0.75
  }
}

Nguyên tắc chấm điểm

• Yêu cầu bằng chứng cụ thể để đạt điểm PASS. Không nên cho qua loa. Nếu một cơ sở dẫn liệu nói rằng “bao gồm tóm tắt” và kết quả có một phần mang tên “Tóm tắt” với một câu mơ hồ, đó là FAIL - nhãn thì có nhưng nội dung thì không.
• Xem xét chính các cơ sở dẫn liệu, không chỉ kết quả. Trong quá trình chấm điểm, hãy lưu ý khi các cơ sở dẫn liệu quá dễ (luôn đạt bất kể chất lượng skill), quá khó (luôn không đạt ngay cả khi kết quả tốt), hoặc không thể kiểm chứng (không thể kiểm tra chỉ từ kết quả). Sửa những lỗi này cho lần lặp tiếp theo.

Tổng hợp kết quả

Sau khi chấm điểm tất cả các lần chạy trong mỗi vòng lặp, hãy tính toán số liệu thống kê tóm tắt cho mỗi cấu hình và lưu chúng vào file benchmark.json cùng với những thư mục đánh giá (ví dụ: csv-analyzer-workspace/iteration-1/benchmark.json):

{
  "run_summary": {
    "with_skill": {
      "pass_rate": { "mean": 0.83, "stddev": 0.06 },
      "time_seconds": { "mean": 45.0, "stddev": 12.0 },
      "tokens": { "mean": 3800, "stddev": 400 }
    },
    "without_skill": {
      "pass_rate": { "mean": 0.33, "stddev": 0.10 },
      "time_seconds": { "mean": 32.0, "stddev": 8.0 },
      "tokens": { "mean": 2100, "stddev": 300 }
    },
    "delta": {
      "pass_rate": 0.50,
      "time_seconds": 13.0,
      "tokens": 1700
    }
  }
}

Chỉ số delta cho bạn biết skill đó tốn bao nhiêu thời gian (nhiều thời gian hơn, nhiều token hơn) và mang lại gì (tỷ lệ đạt cao hơn). Một skill thêm 13 giây nhưng cải thiện tỷ lệ đạt lên 50 điểm phần trăm có lẽ đáng giá. Một skill tăng gấp đôi lượng token sử dụng chỉ để cải thiện 2 điểm có thể không đáng.

Phân tích các mẫu

Số liệu thống kê tổng hợp có thể che giấu các mẫu quan trọng. Sau khi tính toán các điểm chuẩn:

• Loại bỏ hoặc thay thế các cơ sở dẫn liệu luôn đạt trong cả hai cấu hình. Những cơ sở dẫn liệu này không cho bạn biết bất cứ điều gì hữu ích - mô hình xử lý chúng tốt mà không cần skill. Chúng làm tăng tỷ lệ đạt khi có skill mà không phản ánh giá trị thực sự của skill.
• Điều tra các cơ sở dẫn liệu luôn thất bại trong cả hai cấu hình. Hoặc là cơ sở dẫn liệu bị lỗi (yêu cầu điều mà mô hình không thể thực hiện), trường hợp kiểm thử quá khó, hoặc cơ sở dẫn liệu đang kiểm tra sai đối tượng. Hãy sửa những lỗi này trước khi thực hiện lần lặp tiếp theo.
• Nghiên cứu các cơ sở dẫn liệu thành công khi sử dụng skill nhưng lại thất bại khi không sử dụng skill. Đây là nơi mà skill thực sự mang lại giá trị. Hãy hiểu tại sao - những hướng dẫn hoặc script nào đã tạo nên sự khác biệt?
• Điều chỉnh hướng dẫn khi kết quả không nhất quán giữa các lần chạy. Nếu cùng một lần đánh giá đôi khi thành công và đôi khi thất bại (thể hiện bằng độ lệch chuẩn cao trong điểm chuẩn), thì lần đánh giá đó có thể không ổn định (nhạy cảm với tính ngẫu nhiên của mô hình), hoặc hướng dẫn của skill có thể quá mơ hồ đến mức mô hình diễn giải chúng khác nhau mỗi lần. Hãy thêm ví dụ hoặc hướng dẫn cụ thể hơn để giảm sự mơ hồ.
• Kiểm tra các giá trị ngoại lệ về thời gian và token. Nếu một lần đánh giá mất thời gian gấp 3 lần so với các lần khác, hãy đọc bản transcript thực thi của nó (toàn bộ nhật ký về những gì mô hình đã làm trong quá trình chạy) để tìm ra điểm nghẽn.

Xem xét kết quả với một người thật

Việc chấm điểm cơ sở dẫn liệu và phân tích mẫu giúp phát hiện nhiều lỗi, nhưng chúng chỉ kiểm tra những gì bạn nghĩ đến khi viết cơ sở dẫn liệu. Người đánh giá thủ công mang đến một góc nhìn mới mẻ - giúp phát hiện những vấn đề bạn không lường trước, nhận thấy khi kết quả về mặt kỹ thuật là chính xác nhưng lại không đúng trọng tâm, hoặc phát hiện những vấn đề khó diễn đạt bằng các kiểm tra đạt/không đạt. Đối với mỗi trường hợp kiểm thử, hãy xem xét kết quả thực tế cùng với điểm số.

Ghi lại phản hồi cụ thể cho từng trường hợp kiểm thử và lưu vào không gian làm việc (ví dụ: dưới dạng file feedback.json cùng với các thư mục eval):

{
  "eval-top-months-chart": "Biểu đồ thiếu nhãn trục và các tháng được sắp xếp theo thứ tự bảng chữ cái thay vì theo thứ tự thời gian.",
  "eval-clean-missing-emails": ""
}

“Biểu đồ thiếu nhãn trục” là phản hồi cần hành động; “trông tệ” thì không. Phản hồi trống có nghĩa là kết quả trông ổn - trường hợp kiểm thử đó đã vượt qua đánh giá của bạn. Trong bước lặp lại, hãy tập trung cải thiện các trường hợp kiểm thử mà bạn có khiếu nại cụ thể.

Lặp lại skill

Sau khi chấm điểm và xem xét, bạn có 3 nguồn tín hiệu:

• Các cơ sở dẫn liệu thất bại chỉ ra những lỗ hổng cụ thể - một bước bị thiếu, một hướng dẫn không rõ ràng hoặc một trường hợp mà skill không xử lý được.
• Phản hồi của người dùng chỉ ra các vấn đề chất lượng rộng hơn - phương pháp tiếp cận sai, đầu ra được cấu trúc kém hoặc skill tạo ra kết quả đúng về mặt kỹ thuật nhưng không hữu ích.
• bản transcript thực thi tiết lộ lý do tại sao mọi thứ lại sai. Nếu agent bỏ qua một hướng dẫn, hướng dẫn đó có thể không rõ ràng. Nếu agent dành thời gian cho các bước không hiệu quả, những hướng dẫn đó có thể cần được đơn giản hóa hoặc loại bỏ.

Cách hiệu quả nhất để biến những tín hiệu này thành cải tiến skill là cung cấp cả ba - cùng với file SKILL.md hiện tại - cho một LLM và yêu cầu nó đề xuất các thay đổi. LLM có thể tổng hợp các mẫu từ những cơ sở dẫn liệu thất bại, khiếu nại của người đánh giá và hành vi trong bản transcript, điều mà việc kết nối thủ công sẽ rất tốn công. Khi hướng dẫn LLM, hãy bao gồm các hướng dẫn sau:

• Khái quát hóa từ phản hồi. Skill này sẽ được sử dụng trong nhiều prompt khác nhau, không chỉ các trường hợp thử nghiệm. Các bản sửa lỗi nên giải quyết những vấn đề cơ bản một cách tổng quát hơn là thêm các bản vá nhỏ cho những ví dụ cụ thể.
• Giữ cho skill gọn nhẹ. Ít hướng dẫn, nhưng chất lượng thường hiệu quả hơn các quy tắc đầy đủ. Nếu bản transcript cho thấy công việc bị lãng phí (xác thực không cần thiết, đầu ra trung gian không cần thiết), hãy loại bỏ các hướng dẫn đó. Nếu tỷ lệ vượt qua chững lại mặc dù đã thêm nhiều quy tắc hơn, skill có thể bị hạn chế quá mức - hãy thử loại bỏ các hướng dẫn và xem liệu kết quả có giữ nguyên hoặc cải thiện hay không.
• Giải thích lý do. Các hướng dẫn dựa trên lý luận (“Làm X vì Y có xu hướng gây ra Z”) hoạt động tốt hơn những chỉ thị cứng nhắc (“LUÔN LUÔN làm X, KHÔNG BAO GIỜ làm Y”). Mô hình tuân theo hướng dẫn đáng tin cậy hơn khi chúng hiểu mục đích.
• Gộp các công việc lặp lại. Nếu mỗi lần chạy thử nghiệm độc lập đều viết một kịch bản hỗ trợ tương tự (trình tạo biểu đồ, trình phân tích dữ liệu), đó là tín hiệu để đóng gói kịch bản đó vào thư mục scripts/ của skill.

Vòng lặp

1. Cung cấp tín hiệu đánh giá và file SKILL.md hiện tại cho LLM và yêu cầu nó đề xuất các cải tiến.
2. Xem xét và áp dụng các thay đổi.
3. Chạy lại tất cả các trường hợp thử nghiệm trong thư mục iteration-<N+1>/ mới.
4. Chấm điểm và tổng hợp các kết quả mới.
5. Xem xét với người kiểm tra. Lặp lại.

Dừng lại khi bạn hài lòng với kết quả, phản hồi liên tục trống hoặc bạn không còn thấy sự cải thiện đáng kể giữa các lần lặp.