# SkillEvaluator: chấm điểm và đo tác động của skill AI agent — hướng dẫn cài đặt và dùng

> SkillEvaluator là công cụ dòng lệnh mã nguồn mở của NVIDIA, dùng để kiểm tra chất lượng, độ an toàn và tác động thực tế của các skill (thư mục hướng dẫn) cho AI agent. Bạn có thể chạy thử không cần API key, chỉ cần Git và uv. Cài đặt không khó nếu bạn quen dùng terminal.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-22 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/skillevaluator-cham-diem-do-tac-dong-skill-ai-agent

SkillEvaluator là công cụ mã nguồn mở của NVIDIA, giúp bạn kiểm tra một skill của AI agent có tốt không và có thật sự giúp agent làm việc hiệu quả hơn không. Skill ở đây là một thư mục chứa hướng dẫn và các file hỗ trợ theo chuẩn Agent Skills. Công cụ viết bằng Python, chạy bằng dòng lệnh.

Nếu bạn đang tự viết skill cho Claude Code, Codex hay agent khác, bạn sẽ gặp câu hỏi quen thuộc: skill này viết đã ổn chưa, có an toàn không, có trùng với skill khác không, và agent có làm tốt hơn khi có nó không? SkillEvaluator trả lời lần lượt các câu hỏi đó, từ kiểm tra nhanh đến chạy agent thật có skill và không có skill để so sánh.

Điểm đáng giá nhất: bạn có thể thử ngay mà không cần API key, không cần GPU, không cần Docker. Chỉ cần Git và uv là chạy được lần chấm điểm đầu tiên trên skill mẫu đi kèm. Hiện repo có khoảng 853 sao và 104 fork, giấy phép Apache-2.0.

```repo
- repo | NVIDIA/SkillEvaluator
- kind | CLI
- desc | Công cụ mã nguồn mở của NVIDIA: kiểm tra chất lượng skill của AI agent, phát hiện trùng lặp và đo skill có giúp agent làm việc tốt hơn không.
- stars | 853
- lang | Python
- license | Apache-2.0
```

## SkillEvaluator làm được gì

Công cụ chia làm ba tầng, mỗi tầng độc lập. Bạn dùng tầng nào cũng được.

### Tầng 1: Kiểm tra skill có an toàn và đúng chuẩn không

Tầng này trả lời câu hỏi: skill có an toàn và viết đúng cấu trúc không? Nó chấm điểm chất lượng tĩnh, kèm danh sách phát hiện. Với quét bảo mật, repo dùng SkillSpector và Gitleaks (Gitleaks thường dùng để dò lộ key). Semgrep là tuỳ chọn. Lợi ích thực tế: bạn biết skill của mình có lỗ hổng hay lộ thông tin trước khi đưa cho người khác dùng.

### Tầng 2: Phát hiện trùng lặp

Tầng này trả lời: hướng dẫn trong skill có bị lặp hay chồng lấn không? Bạn có thể thêm danh mục skill (`--catalog ./skill-catalog.json`) để so sánh giữa nhiều skill với nhau. Khi bạn có hàng chục skill, tầng này giúp bạn khỏi giữ những skill làm cùng một việc.

### Tầng 3: Đánh giá bằng agent chạy thật

Đây là tầng khác biệt nhất. Nó trả lời: skill có thật sự giúp agent không? Công cụ chạy agent trong môi trường cách ly (mặc định là Docker), so sánh kết quả khi có và không có skill. Nó cũng có thể tạo bộ dữ liệu đánh giá giả lập để bạn không phải tự nghĩ từng ca kiểm tra.

### Tích hợp vào quy trình làm việc của nhóm

Bạn có thể gắn kiểm tra vào GitHub hoặc GitLab, để mỗi lần sửa skill là tự chạy kiểm tra chất lượng, quét bảo mật và xuất báo cáo. Bạn chọn thư mục và ngưỡng điểm, không cần viết code của công cụ.

### Có sẵn skill để agent tự chạy công cụ

Nếu muốn để agent chạy SkillEvaluator giúp bạn, README hướng dẫn cài skill trong thư mục `skills/skillevaluator/` của repo.

## Cần chuẩn bị gì

Theo tư liệu, bạn cần:

- **Git** và **uv** (trình quản lý gói Python). README dẫn tới trang cài uv chính thức. uv sẽ tự chuẩn bị Python 3.13 và các thư viện cần thiết.
- **Python**: file `pyproject.toml` yêu cầu từ 3.12 đến dưới 3.15. Nếu dùng uv như README thì bạn không cần tự cài Python.
- **Chạy thử không cần LLM**: không cần API key, bộ quét, GPU hay Docker.
- **Chạy chấm rubric bằng mô hình**: cần API key của NVIDIA Build. README nói thành viên NVIDIA Developer Program đủ điều kiện có thể dùng endpoint do NVIDIA lưu trữ để thử nghiệm miễn phí, theo điều khoản và giới hạn tốc độ của họ.
- **Tầng 3 (agent thật)**: cần truy cập một nhà cung cấp mô hình, một agent được hỗ trợ, và một sandbox đang chạy (mặc định là Docker).

README chưa nói rõ về hệ điều hành được hỗ trợ. Các lệnh mẫu viết theo kiểu terminal Linux/macOS (dùng `export` và dấu `\` xuống dòng). Nếu bạn dùng Windows, hãy xem hướng dẫn cài đặt trên trang tài liệu của dự án trước khi bắt đầu.

```note
Chạy bằng mô hình và sandbox được quản lý có thể phát sinh chi phí. README cũng nói lệnh chấm rubric sẽ gửi nội dung tài liệu của skill lên mô hình. Đừng đưa skill chứa thông tin nội bộ, mật khẩu hay dữ liệu khách hàng vào lệnh có dùng LLM.
```

## Cài đặt từng bước

```steps
- Cài Git và uv | Chuẩn bị hai công cụ nền, uv sẽ lo Python và thư viện
- Tải repo về | Dùng git clone rồi cd vào thư mục
- Chạy chấm điểm không cần LLM | Thử trên skill mẫu text-analyzer, không cần key
- (Tuỳ chọn) Dùng NVIDIA Build | Lấy API key để có điểm rubric do mô hình chấm
- (Tuỳ chọn) Chạy cả ba tầng | Kiểm tra môi trường bằng doctor rồi chạy validate
```

### Bước 1: Cài Git và uv

README chỉ dẫn cài uv theo trang hướng dẫn chính thức của uv, chứ không đưa lệnh cụ thể. Bạn mở trang cài đặt của uv (docs.astral.sh/uv) và làm theo phần dành cho hệ điều hành của bạn. Git cài từ trang chính thức của Git. Cài xong, hãy mở terminal mới để máy nhận lệnh `git` và `uv`.

### Bước 2: Tải repo về

Mở terminal ở thư mục bạn muốn lưu, rồi chạy:

```bash
git clone --depth 1 https://github.com/NVIDIA/SkillEvaluator.git
cd SkillEvaluator
```

Lệnh đầu tải mã nguồn (`--depth 1` chỉ tải bản mới nhất cho nhẹ). Lệnh thứ hai đi vào thư mục vừa tải. Các lệnh ở bước sau phải chạy trong thư mục này. Đây là chỗ người mới hay vấp: chạy lệnh ở thư mục khác sẽ báo không tìm thấy đường dẫn skill.

### Bước 3: Chạy chấm điểm không cần LLM

```bash
uv run --python 3.13 skillevaluator quality-check \
  src/skillevaluator/tier3/reference_skills/text-analyzer \
  -r cli -r json -o reports/first-quality
```

Lệnh này chấm chất lượng skill mẫu `text-analyzer`. `-r cli -r json` là xuất báo cáo ra màn hình và ra file JSON. `-o reports/first-quality` là thư mục lưu kết quả. Nếu terminal của bạn không hiểu dấu `\` cuối dòng (ví dụ PowerShell), hãy gộp cả lệnh thành một dòng.

### Bước 4 (tuỳ chọn): Dùng NVIDIA Build

Làm theo README:

1. Đăng nhập tại build.nvidia.com và hoàn tất đăng ký.
2. Mở trang của một mô hình, chọn **Get API Key** và tạo key.
3. Đặt nhà cung cấp và key trong cùng một cửa sổ terminal, rồi chạy:

```bash
export SKILL_EVAL_LLM_PROVIDER=nv_build
export NVIDIA_API_KEY='nvapi-...'
uv run --python 3.13 --extra llm skillevaluator rubric-eval \
  src/skillevaluator/tier3/reference_skills/text-analyzer \
  -r cli -r json -o reports/first-build
```

Thay `nvapi-...` bằng key thật của bạn. Phải đặt key và chạy lệnh trong cùng một cửa sổ terminal, vì biến môi trường sẽ mất khi đóng cửa sổ. Lệnh `export` là cú pháp của terminal kiểu bash; README không ghi cú pháp tương đương cho Windows.

### Bước 5 (tuỳ chọn): Chạy cả ba tầng

Sau khi đã thiết lập nhà cung cấp, bộ quét và sandbox cho agent, README đưa hai lệnh:

```bash
uv run --python 3.13 --extra all skillevaluator doctor --env-mode docker
uv run --python 3.13 --extra all skillevaluator validate ./my-skill
```

`doctor` kiểm tra môi trường đã sẵn sàng chưa (chỉ kiểm tra độ sẵn sàng, không đảm bảo gọi mô hình thành công). `validate` chạy cả ba tầng cho skill của bạn; thay `./my-skill` bằng đường dẫn thư mục skill thật. Muốn bỏ tầng chạy agent thật thì thêm `--tiers 1,2`; chỉ kiểm tra tĩnh thì dùng `--tiers 1`.

### Cài như một lệnh dùng độc lập

Nếu bạn muốn có lệnh `skillevaluator` dùng riêng, không cần checkout mã nguồn, README dẫn tới trang Installation của dự án. Riêng phần tích hợp CI cho GitHub, README có lệnh sau, chạy bên trong repo của bạn đã tải về máy:

```bash
pip install --upgrade skillevaluator
skillevaluator ci init
```

Lệnh thứ hai hướng dẫn bạn chọn các kiểm tra và phản hồi tuỳ chọn, rồi tạo một pull request thiết lập để bạn xem lại. Nếu dùng GitLab hoặc muốn tự sao chép, README có sẵn các file mẫu trong thư mục `ci/bundles/` của repo.

## Kiểm tra đã chạy được chưa

Với lệnh không cần LLM ở bước 3, README mô tả kết quả mong đợi như sau:

- Skill mẫu được chấm khoảng **84.5/100 (B)**.
- Lệnh kết thúc với mã thoát `0` (nghĩa là qua ngưỡng, mặc định ngưỡng đạt là 70).
- File báo cáo được lưu tại `reports/first-quality/skillevaluator-quality.json`.

Với lệnh dùng NVIDIA Build, kết quả nằm ở `reports/first-build/skillevaluator-rubric.json`. README lưu ý: một lần đánh giá hoàn tất vẫn có thể không đạt ngưỡng rubric, nên "chạy xong" và "đạt" là hai chuyện khác nhau.

Còn một điểm cần hiểu: kiểm tra tĩnh không đủ để kết luận skill hoàn chỉnh. README nói bằng chứng để công bố vẫn ở trạng thái `INCOMPLETE`, vì bảo mật cần bộ quét và tác động lên agent cần đánh giá chạy thật. Đây là hành vi bình thường, không phải lỗi cài đặt.

## Dùng vào việc thật

### Kiểm tra skill mình vừa viết trước khi chia sẻ

Bạn là lập trình viên mới, vừa viết một skill cho Claude Code. Thay vì đoán, bạn chạy lại đúng lệnh ở bước 3 nhưng đổi đường dẫn sang thư mục skill của mình:

```bash
uv run --python 3.13 skillevaluator quality-check ./my-skill -r cli -r json -o reports/my-skill
```

Lệnh này giữ nguyên cấu trúc lệnh trong README, chỉ thay đường dẫn. Bạn nhận điểm số kèm danh sách phát hiện, và sửa dần đến khi vượt ngưỡng 70.

### Quét bảo mật một skill tải từ nơi khác

Bạn là nhân viên IT, được đồng nghiệp gửi một skill và định cài cho cả nhóm. Trước khi cài, bạn chạy tầng 1:

```bash
uv run --extra security skillevaluator tier1 ./my-skill --no-llm
```

Lệnh này nằm trong README. `--no-llm` nghĩa là không gọi mô hình, nhưng vẫn cần bộ quét. Công cụ sẽ tải các bản SkillSpector và Gitleaks đã được ghim và xác minh nếu máy chưa có. Nếu một bộ quét không chạy được, kết quả là `INCOMPLETE` và thoát với mã khác 0, nên bạn không bị "qua" nhầm.

> Đo skill có giúp agent hay không, đừng chỉ tin cảm giác là nó hay.
>
> — Ông T

### Dọn bớt skill trùng nhau

Nhóm bạn có cả chục skill do nhiều người viết, nghi ngờ có cái làm trùng việc. Bạn chạy tầng 2 với danh mục skill:

```bash
uv run --extra tier2 skillevaluator tier2 ./my-skill --catalog ./skill-catalog.json
```

Cần có nhà cung cấp cho embedding và chat. README nói nếu so sánh giữa các skill không chạy được thì tầng 2 sẽ báo rõ. Kết quả giúp bạn quyết định gộp hay bỏ bớt.

### Đo skill có thật sự cải thiện agent

Bạn đã có skill và muốn biết agent làm tốt hơn bao nhiêu khi có nó. Bạn tạo thêm ca kiểm tra rồi chạy tầng 3:

```bash
uv run --python 3.13 --extra tier3 skillevaluator tier3 create-eval-dataset ./my-skill --full
uv run --extra tier3 skillevaluator tier3 ./my-skill
```

Lệnh đầu tạo bộ ca đánh giá đầy đủ hơn. README khuyên bạn nên xem lại các ca được tạo, vì mẫu mặc định bỏ qua ca phủ định nếu bạn không tự viết trong `EVAL.md`. Lệnh sau chạy agent thật để so sánh. Nếu không có nguồn đánh giá sẵn, công cụ chỉ tạo một ca khởi đầu với độ phủ hạn chế.

## Lỗi hay gặp và cách xử lý

### Báo không tìm thấy thư mục skill

Nguyên nhân thường gặp là bạn đang đứng sai thư mục khi chạy lệnh có đường dẫn tương đối như `src/skillevaluator/...`. Hãy `cd` vào thư mục `SkillEvaluator` đã tải về, hoặc dùng đường dẫn đầy đủ tới skill.

### Lệnh xuống dòng bị lỗi

Dấu `\` cuối dòng chỉ chạy trên terminal kiểu bash. Nếu bạn gặp lỗi lạ ở PowerShell hay cmd, cách an toàn nhất là gộp cả lệnh thành một dòng duy nhất.

### Lệnh rubric-eval không chạy hoặc báo thiếu key

Kiểm tra bạn đã đặt `SKILL_EVAL_LLM_PROVIDER` và `NVIDIA_API_KEY` trong cùng cửa sổ terminal với lệnh chạy. Mở cửa sổ mới là mất biến. Cũng nên kiểm tra key đã được tạo đúng ở trang build.nvidia.com và chưa vượt giới hạn tốc độ.

### Tầng 1 thoát với mã khác 0 dù đã thêm --no-llm

Đây là hành vi README đã ghi: `--no-llm` không bỏ yêu cầu về bộ quét. Nếu một bộ quét không chạy được (ví dụ không tải được), kết quả là `INCOMPLETE` và thoát nonzero. Hãy xem phần về scanners trong tài liệu dự án để biết cách xử lý.

### Tầng 3 không chạy vì thiếu sandbox

Tầng 3 cần một sandbox đang chạy, mặc định là Docker. Hãy mở Docker trước, rồi chạy `doctor` như ở bước 5 để kiểm tra môi trường. Nhớ rằng `doctor` chỉ kiểm tra độ sẵn sàng, chưa đảm bảo mô hình trả lời được.

## Có nên dùng không

**Điểm mạnh.** Bạn thử được ngay không cần key, GPU hay Docker. Công cụ đi từ kiểm tra rẻ (tĩnh) đến đo tác động thật trên agent, nên bạn dùng đến đâu tuỳ nhu cầu. Nó tích hợp được vào GitHub và GitLab, có giấy phép Apache-2.0, và là một phần của quy trình NVIDIA Verified Skills. Repo còn được cập nhật trong 3 tháng gần đây.

**Giới hạn.** README ghi mức hỗ trợ là **Experimental**: cộng đồng hỗ trợ theo khả năng, không có cam kết SLA hay hỗ trợ doanh nghiệp từ NVIDIA. Để chạy đầy đủ, bạn phải thiết lập nhiều thứ (bộ quét, nhà cung cấp mô hình, agent, sandbox), nên không hẳn nhẹ nhàng với người mới. Dự án cũng tải và cài thêm phần mềm mã nguồn mở của bên thứ ba, bạn nên xem giấy phép của chúng. Chi phí mô hình và sandbox có thể phát sinh.

**Khi nào chọn cách khác.** Nếu bạn chỉ dùng skill có sẵn và không tự viết hay quản lý skill, công cụ này chưa cần thiết. Nếu bạn cần cam kết hỗ trợ doanh nghiệp, mức Experimental có thể chưa phù hợp. Còn nếu bạn tự viết skill, đặc biệt trong nhóm hoặc dự án mở, thì chạy `quality-check` một lần cho skill của mình là bước đáng làm nhất.

## Câu hỏi thường gặp

### SkillEvaluator có miễn phí không?

Bản thân công cụ là mã nguồn mở theo giấy phép Apache-2.0. Chạy kiểm tra chất lượng không cần LLM thì không cần API key. Với NVIDIA Build, README nói thành viên NVIDIA Developer Program đủ điều kiện có thể dùng endpoint để thử nghiệm miễn phí, theo điều khoản và giới hạn tốc độ. Mô hình và sandbox được quản lý có thể phát sinh chi phí.

### Có cần GPU không?

Không cho lần chạy thử đầu tiên. README nói lệnh quality-check không cần API key, bộ quét, GPU hay Docker. Với tầng 3, README yêu cầu nhà cung cấp mô hình, agent được hỗ trợ và sandbox (mặc định Docker), chứ không nhắc đến GPU.

### Chạy được trên Windows không?

README chưa nói rõ về hệ điều hành được hỗ trợ. Các lệnh mẫu viết theo kiểu terminal bash. Bạn nên xem trang Installation trong tài liệu của dự án trước khi cài trên Windows.

### Dữ liệu của tôi có an toàn không?

Lệnh rubric-eval gửi tài liệu của skill lên mô hình, nên đừng đưa nội dung nhạy cảm vào. Lệnh quality-check không cần LLM thì không gửi gì đi theo mô tả trong README. Chi tiết chính sách dữ liệu của endpoint NVIDIA Build, tư liệu hiện chưa nói.

### SkillEvaluator khác gì việc tự đọc lại skill?

Công cụ cho điểm số có thể lặp lại, quét bảo mật, phát hiện nội dung trùng lặp, và đo skill ảnh hưởng thế nào đến hành vi agent khi chạy thật có và không có skill. Những việc này khó làm chính xác nếu chỉ đọc bằng mắt.

### Cần Python phiên bản nào?

File pyproject.toml yêu cầu Python từ 3.12 đến dưới 3.15. Nếu dùng uv theo README, uv sẽ tự chuẩn bị Python 3.13 và các thư viện nên bạn không cần cài Python riêng.

### Công cụ có hỗ trợ chính thức từ NVIDIA không?

README ghi mức hỗ trợ là Experimental: cộng đồng hỗ trợ theo khả năng, không có SLA và không có quyền lợi hỗ trợ doanh nghiệp của NVIDIA. Lỗi và yêu cầu tính năng được báo qua GitHub Issues.
