Khắc phục sự cố Skill
Troubleshooting
Khắc phục lỗi skill Claude AI qua sáu triệu chứng phổ biến nhất, kèm kỹ thuật tối ưu quan trọng nhất: khi nào dùng văn bản, khi nào bắt buộc dùng script.
🎯 Mục tiêu bài học
- Chẩn đoán nhanh 6 sự cố skill phổ biến nhất theo triệu chứng.
- Phân biệt lỗi do skill và lỗi do kết nối MCP để sửa đúng chỗ.
- Biết khi nào phải chuyển quy tắc từ văn bản sang script để bảo đảm chính xác.
- Tránh các anti-pattern làm hỏng chất lượng skill.
Sáu triệu chứng phổ biến nhất
| Triệu chứng | Nguyên nhân gốc | Cách sửa |
|---|---|---|
| Upload thất bại | YAML sai thụt lề, hoặc tên file không đúng SKILL.md, hoặc frontmatter có trường ngoài 6 trường hợp lệ | Kiểm tra thụt lề YAML, viết hoa đúng tên file, xoá mọi trường lạ khỏi frontmatter |
| Không trigger | Description thiếu từ khoá thực tế người dùng gõ | Thêm các cách diễn đạt đa dạng vào description — cả từ ngữ chuyên môn lẫn từ ngữ đời thường của team |
| Trigger quá nhiều | Description quá rộng, thiếu điều kiện phủ định | Thu hẹp phạm vi và ghi rõ khi nào KHÔNG dùng skill này |
| Lỗi MCP | Lỗi nằm ở kết nối MCP server, không phải do skill | Sửa kết nối MCP trước. Đừng sửa skill khi gốc rễ là vấn đề kết nối |
| Bỏ qua instructions | Skill quá dài, thông tin quan trọng bị chìm giữa các đoạn phụ | Cắt giảm nội dung, đưa chi tiết vào file tham chiếu, để quy tắc quan trọng lên đầu |
| Tràn context | Đang bật quá nhiều skill cùng lúc | Tắt bớt skill không dùng tới. Metadata mỗi skill khoảng 100 token nên vài chục skill mới đáng kể — nhưng nhiều skill cùng kích hoạt thì rất nặng |
Dặn dò bằng văn bản hay nhúng script?
| 📝 Language — bất ổn | ⚙️ Bundle Script — chuẩn xác | |
|---|---|---|
| Cách làm | Viết vào SKILL.md: "Hãy cẩn thận kiểm tra logic báo cáo nhé." | Nhúng script Python vào scripts/ và gọi: python scripts/validate.py |
| Kết quả | Model có thể diễn dịch sai, làm tắt hoặc bỏ sót bước kiểm tra | Code luôn cho ra một kết quả duy nhất, không suy hao qua các lượt |
| Chi phí context | Tốn token mỗi lần skill kích hoạt | Mã nguồn không vào context — chỉ output của script mới tốn token |
| Nên dùng khi | Nhiều cách làm đều đúng, cần phán đoán theo ngữ cảnh | Quy tắc validation cứng, thao tác mong manh, dữ liệu nặng |
💡 Takeaway
Để giảm tải cửa sổ context và tăng độ chính xác, hãy đưa các quy tắc validation cứng hoặc dữ liệu nặng vào file script hay markdown phụ, và chỉ gọi tới khi thực sự cần thiết. Script pre-made còn đáng tin cậy hơn code Claude tự sinh ra mỗi lần, đồng thời tiết kiệm cả token lẫn thời gian.
Bốn lỗi làm hỏng chất lượng skill
Đưa ra quá nhiều lựa chọn
⛔ "Bạn có thể dùng pypdf, hoặc pdfplumber, hoặc PyMuPDF, hoặc pdf2image..."
✅ Đưa một mặc định kèm một lối thoát: "Dùng pdfplumber. Với PDF scan cần OCR thì dùng pdf2image kèm pytesseract."
Thông tin gắn mốc thời gian
⛔ "Nếu trước tháng 8/2026 thì dùng API cũ." Ngày tháng sẽ lạc hậu.
✅ Dùng mục "Pattern cũ" gói trong thẻ <details> để lưu bối cảnh lịch sử mà không làm rối phần chính.
Hằng số không giải thích
⛔ TIMEOUT = 47 — tại sao lại 47?
✅ # Request HTTP thường xong trong 30 giây; để dư cho kết nối chậm. Nếu bạn không biết giá trị đúng, làm sao Claude biết?
REQUEST_TIMEOUT = 30
Script đùn đẩy lỗi cho Claude
⛔ Script chỉ open(path).read() rồi để Claude tự xử khi lỗi.
✅ Bắt FileNotFoundError và PermissionError, in thông báo rõ ràng và trả về giá trị mặc định hợp lý.
TenServer:ten_tool — ví dụ BigQuery:bigquery_schema hay GitHub:create_issue. Thiếu tiền tố server, Claude có thể không tìm thấy tool, đặc biệt khi bạn bật nhiều MCP server cùng lúc.FAQ — 3 câu hỏi thường gặp về khắc phục lỗi skill claude ai
Upload skill thất bại thì kiểm tra gì trước?
Ba thứ theo thứ tự: thụt lề YAML có đúng không, tên file có đúng SKILL.md viết hoa toàn bộ không, và frontmatter có trường nào ngoài 6 trường hợp lệ không.
Khi nào nên chuyển quy tắc từ văn bản sang script?
Khi cần kết quả xác định, không được sai. Dặn dò bằng văn bản thì model có thể diễn dịch sai hoặc bỏ sót bước; script luôn cho một kết quả duy nhất. Thêm nữa, mã nguồn script không vào context — chỉ output mới tốn token.
Skill gọi MCP tool bị lỗi không tìm thấy thì sao?
Phải dùng tên đầy đủ có tiền tố server dạng TenServer:ten_tool, ví dụ BigQuery:bigquery_schema. Thiếu tiền tố, Claude có thể không tìm thấy tool, đặc biệt khi bật nhiều MCP server cùng lúc.
Nguồn: Bài viết biên soạn dựa trên tài liệu Xây dựng bộ Skills cho Claude (Anthropic Academy, bản tiếng Việt do Nguyen Ngoc Tuan trình bày), đã viết lại và đối chiếu với tài liệu Agent Skills chính thức của Anthropic (platform.claude.com và code.claude.com), cập nhật 15/08/2026. Mọi số liệu kỹ thuật lấy theo tài liệu chính thức.