Canonical HTML: https://claudewiki.org/claude-skills/bai-8.html

# 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.

### ❓ khắc phục lỗi skill claude ai — trả lời nhanh

Sáu lỗi skill Claude AI phổ biến: upload fail (sai YAML hoặc tên file), không trigger (thiếu từ khoá trong description), trigger quá nhiều (thiếu điều kiện phủ định), lỗi MCP (do kết nối chứ không do skill), bỏ qua hướng dẫn (skill quá dài), tràn context (bật quá nhiều skill).

### 🎯 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.

BẢNG CHẨN ĐOÁN

## 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 |

KỸ THUẬT TỐI ƯU QUAN TRỌNG NHẤT

## 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.

ANTI-PATTERN

## 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ẻ `` để 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ậmREQUEST_TIMEOUT = 30`. Nếu bạn không biết giá trị đúng, làm sao Claude biết?

#### 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ý.

CÂU HỎI THƯỜNG GẶP

## 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 06/11/2026. Mọi số liệu kỹ thuật lấy theo tài liệu chính thức.

**Đối chiếu thông tin Claude: 06/11/2026.** Xem [các thay đổi, phạm vi truy cập và nguồn chính thức](https://claudewiki.org/cap-nhat-claude.html). Tính năng có thể triển khai theo đợt, khu vực và cấu hình tổ chức.

[← Bài trước**Bài 7 · 5 Pattern thiết kế nâng cao**](https://claudewiki.org/claude-skills/bai-7.html) · [Bài tiếp theo →**Bài 9 · Checklist chuẩn hoá**](https://claudewiki.org/claude-skills/bai-9.html)
