TECHDEV · Công cụ open-source

skill-audit

Gói Agent Skills của bạn ngày càng phình ra. Skill nào bị trùng? Skill nào tranh giành cùng một trigger? Skill nào không có mô tả nên agent chẳng bao giờ chọn? skill-audit trả lời cả ba câu hỏi bằng một lệnh duy nhất, không cần cài thêm thư viện nào.

Xem trên GitHub →Đọc bài viết →

Python 3.9+ · Không cần thư viện ngoài · 9 kiểm tra · MIT

Ai gặp khó, và công cụ giải quyết ra sao

Các gói Agent Skills đang bùng nổ — mỗi tuần lại có thêm pack mới, và các nhóm chép skill từ nhiều nguồn vào chung một thư mục. Hệ quả: hai skill cùng tên (agent chọn bừa một cái), hai skill có mô tả gần như giống nhau (cả hai cùng kích hoạt với một prompt, kết quả ngẫu nhiên), skill không có mô tả (agent chẳng bao giờ gọi, vì mô tả chính là cách agent quyết định), skill có tên sai quy tắc hoặc không có frontmatter (một số loader lặng lẽ bỏ qua), và pack không ghi version (chẳng ai biết mình có bản mới nhất chưa).

Các skill pack hiện có chỉ thêm skill mới. skill-audit cho bạn biết những skill đang có có còn "khỏe" không.

Nó kiểm tra những gì

Kiểm tra	Phát hiện
`duplicate-name`	Hai file `SKILL.md` khai báo cùng `name`
`invalid-name`	Tên không đúng kebab-case (`Bad Name`, `UPPER`, ...)
`missing-name` / `missing-description`	Frontmatter thiếu `name` hoặc `description`
`frontmatter-parse`	`SKILL.md` không có khối `---`
`overlapping-description`	Mô tả giống hệt nhau, hoặc trùng token ≥70% (Jaccard)
`description-length`	Ngắn hơn 20 ký tự, hoặc dài hơn 1024 ký tự
`thin-body`	Phần nội dung `SKILL.md` dưới 50 ký tự — chỉ là tiêu đề, chưa phải skill
`missing-skill-md`	Thư mục có file nhưng không có `SKILL.md` — không được phát hiện
`no-version`	Frontmatter thiếu `version` — nên bổ sung

Exit code 0 = không có lỗi, 1 = có lỗi. Cảnh báo (warning) không tự làm fail lần chạy.

Dùng thử ngay

$ skill-audit check --path examples/messy
[ERROR] duplicate-name: Duplicate skill name 'dup-skill'
[ERROR] invalid-name: 'Bad Name' must be kebab-case
[ERROR] missing-description: no-desc has no 'description'
[ERROR] missing-description: (unnamed) has no 'description'
[ERROR] missing-name: no-frontmatter/SKILL.md has no 'name'
[WARN ] frontmatter-parse: no-frontmatter/SKILL.md missing frontmatter block
[WARN ] no-version: (unnamed) has no 'version' in frontmatter
Summary: 5 error(s), 2 warning(s), 5 skill(s).

Đoạn demo sao y từ README của skill-audit (mục "Demo"). Repo cũng kèm docs/demo.svg vẽ lại kết quả này.

Cài đặt

# 1. Clone
git clone https://github.com/techdevfun/skill-audit.git
cd skill-audit

# 2. Không cần cài thư viện nào (chỉ dùng stdlib của Python 3.9+).
#    Tuỳ chọn: cài lệnh `skill-audit`
pip install -e .

# 3. Kiểm tra thư mục skills của bạn
PYTHONPATH=src python -m skill_audit check --path ~/.claude/skills

Ba bước sao y từ README của skill-audit. Lệnh check còn hỗ trợ --format json cho script và dashboard.

Sử dụng

# Pack sạch — phải pass
PYTHONPATH=src python -m skill_audit check --path examples/good

# Pack lộn xộn — phải fail kèm lỗi
PYTHONPATH=src python -m skill_audit check --path examples/messy || true

# Liệt kê những gì tìm được
PYTHONPATH=src python -m skill_audit list --path examples/good

# JSON cho script / CI
PYTHONPATH=src python -m skill_audit check --path examples/messy --format json

Các lệnh sao y từ README của skill-audit (mục "Try it on the examples"). Lệnh con list liệt kê các skill tìm được trong pack; check là cổng kiểm tra.

Cổng CI

- name: Audit skills pack
  run: PYTHONPATH=src python -m skill_audit check --path skills --format text

Đoạn snippet sao y từ README của skill-audit. Chính repo này cũng chạy các kiểm tra tương tự trong .github/workflows/ci.yml trên Python 3.9, 3.11 và 3.12; wrapper dùng sẵn nằm ở examples/ci/check.sh.

Đây KHÔNG phải gì — và đối thủ hơn chúng ta ở đâu

skill-audit không thêm bất kỳ skill nào vào pack của bạn — nó chỉ kiểm tra những gì bạn đang có. Các skill pack chuyên cung cấp skill mới bổ trợ cho nó; công cụ này chỉ trả lời "pack của tôi có khỏe không".
Nó kiểm tra, không tự sửa: chế độ --fix (gợi ý đổi tên bản trùng, viết lại mô tả) nằm trên roadmap của README, chưa phát hành. Phiên bản hiện tại là một báo cáo kèm file, dòng và bằng chứng — bạn là người quyết định thay đổi.
Làn của nó là sức khỏe của pack, và chỉ làn đó: tên trùng, trigger chồng chéo, thiếu metadata. Nó không chạy skill của bạn, không đánh giá chất lượng skill ngoài các kiểm tra trên, và không theo dõi skill nào agent thực sự dùng (cần usage log — roadmap, chưa phát hành).

Mã nguồn + README trên GitHub → · Báo lỗi → · ask@techdev.fun

Giới hạn

Mô tả chồng chéo được phát hiện bằng độ trùng token (Jaccard, ≥70%) — hai mô tả cùng nghĩa nhưng khác từ có thể lọt, hai mô tả cùng boilerplate có thể bị gắn cờ. Mỗi phát hiện đều kèm bằng chứng; bạn là người quyết định cuối.
Frontmatter chỉ được đọc ba trường name, description và version. Kiểm tra các trường allowed-tools / permission xem có cấp quyền nguy hiểm không, và báo cáo skill nào không bao giờ được kích hoạt, nằm trên roadmap của README — chưa phát hành.
skill-audit chỉ đọc thư mục skill; nó không cài đặt, không chạy và không kiểm chứng hành vi của skill.

Giấy phép

MIT — xem LICENSE trong repo.

Công cụ liên quan

Các công cụ mã nguồn mở khác của TECHDEV: sessguard, runverdict, gheist-guard, vetgate, context-diet, ci-failure-detective, agent-seatbelt, devsecops-os, env-doctor, logtrim, testguard, breakcheck, keymap, memgraph, ggufit, leaseguard, factfence, jsonfold

Đóng góp ý kiến

Bình chọn cho công cụ này, đề xuất tính năng, hoặc thảo luận với các vận hành khác trên bảng cộng đồng.