Quy trình chẩn đoán 4 bước
Skill không chạy là vấn đề ai cũng gặp tuần đầu. Debug theo thứ tự sau, đừng nhảy cóc:
Bước 1: Skill có được NẠP không?
- Claude Code: kiểm tra skill có trong danh sách không (xem các skill available trong phiên). Không thấy? Kiểm tra: đường dẫn đúng chưa (
~/.claude/skills/<ten>/SKILL.md— file phải tên đúng SKILL.md), YAML frontmatter có lỗi cú pháp không (thiếu---, thụt dòng sai). - Claude.ai: skill đã bật trong Settings → Capabilities chưa?
Bước 2: Frontmatter có hợp lệ không?
Lỗi YAML phổ biến: description chứa dấu : mà không bọc trong ngoặc kép; name có chữ hoa hoặc dấu cách. Thử validate:
python3 -c "
import yaml
content = open('SKILL.md').read()
fm = content.split('---')[1]
print(yaml.safe_load(fm))
"
Bước 3: Description có khớp yêu cầu không?
Test trực diện — hỏi Claude: "Tôi có skill với description: '...'. Yêu cầu 'X' có nên kích hoạt skill này không, tại sao?" Câu trả lời cho bạn biết chính xác lỗ hổng ngôn ngữ giữa description và cách bạn hỏi.
Bước 4: Skill chạy nhưng làm sai?
Đây không còn là lỗi trigger mà là lỗi NỘI DUNG:
- Hướng dẫn mâu thuẫn nhau giữa 2 đoạn → AI chọn ngẫu nhiên
- Thiếu ví dụ mẫu → AI tự suy diễn format
- File phụ không được tham chiếu rõ trong SKILL.md → AI không biết tồn tại
Mẹo cuối: ép dùng để cô lập lỗi
Yêu cầu thẳng: "Dùng skill code-review-chuan để review đoạn này". Nếu ép mà chạy đúng → lỗi ở description (trigger). Nếu ép vẫn sai → lỗi ở nội dung skill. Một câu test, chia đôi không gian lỗi.