Xử lý sự cố với skill

Khi skill không hoạt động như mong đợi, vấn đề thường rơi vào một vài nhóm dễ đoán: skill không kích hoạt, không nạp được, có xung đột, hoặc lỗi khi chạy. Tin vui là đa số cách khắc phục khá đơn giản.

Dùng skills validator

Điều đầu tiên nên thử là công cụ agent skills verifier. Các bước cài đặt khác nhau tuỳ hệ điều hành, nhưng dùng uv là cách nhanh nhất để thiết lập.

Sau khi cài, bạn có thể vào thư mục skill của mình hoặc chạy lệnh từ bất cứ đâu. Validator sẽ bắt được các vấn đề về cấu trúc trước khi bạn tốn thời gian debug những thứ khác.

Skill không kích hoạt

Skill của bạn tồn tại và vượt qua validation, nhưng Claude không dùng nó khi bạn mong đợi. Nguyên nhân gần như luôn nằm ở description.

Claude dùng khớp lệnh theo ngữ nghĩa (semantic matching), nên yêu cầu của bạn cần có sự chồng lấn về nghĩa với description. Nếu không đủ chồng lấn, sẽ không có khớp lệnh nào. Đây là những gì cần làm:

• Đối chiếu description với cách bạn thực sự diễn đạt yêu cầu.
• Thêm các cụm từ kích hoạt mà người dùng thực sự sẽ nói.
• Test với các biến thể như “giúp tôi profile cái này”, “sao cái này chậm vậy?”, “làm cái này nhanh hơn”.
• Nếu bất kỳ biến thể nào không kích hoạt được, hãy thêm những từ khoá đó vào description.

Skill không nạp được

Nếu skill của bạn không xuất hiện khi bạn hỏi Claude “những skill nào khả dụng”, hãy kiểm tra các yêu cầu cấu trúc sau:

• File SKILL.md phải nằm bên trong một thư mục có tên, không nằm ở gốc thư mục skills.
• Tên file phải chính xác là SKILL.md - viết hoa toàn bộ “SKILL”, viết thường “md”.

Chạy claude --debug để xem lỗi nạp. Tìm các thông báo nhắc tới tên skill của bạn. Đôi khi chỉ cần vậy là đủ để chỉ thẳng ra vấn đề.

Sai skill được dùng

Nếu Claude dùng nhầm skill, hoặc có vẻ nhầm lẫn giữa các skill, có thể description của bạn quá giống nhau. Hãy làm chúng khác biệt rõ ràng hơn. Cụ thể nhất có thể không chỉ giúp Claude quyết định khi nào dùng skill của bạn - nó còn ngăn xung đột với các skill có tên nghe tương tự.

Xung đột ưu tiên skill

Nếu skill cá nhân của bạn đang bị bỏ qua, có thể một skill enterprise hoặc ưu tiên cao hơn đang trùng tên.

Thứ tự ưu tiên skill: Enterprise → Personal → Project → Plugins.

Ví dụ, nếu có một skill enterprise “code-review” và bạn cũng có một skill cá nhân cùng tên, phiên bản enterprise luôn thắng. Lựa chọn của bạn:

1. Đổi tên skill của bạn thành thứ gì đó khác biệt hơn (thường là cách dễ hơn).
2. Trao đổi với admin của bạn về skill enterprise đó.

Skill từ plugin không xuất hiện

Đã cài một plugin nhưng không thấy skill của nó? Hãy xoá cache, khởi động lại Claude Code, và cài lại.

Nếu skill vẫn không xuất hiện sau đó, có thể cấu trúc plugin bị sai. Đây chính là lúc công cụ validator thực sự phát huy tác dụng.

Lỗi runtime

Skill nạp được nhưng lỗi khi thực thi. Vài nguyên nhân phổ biến:

• Thiếu dependency: nếu skill của bạn dùng package bên ngoài, chúng phải được cài đặt. Thêm thông tin dependency vào description của skill để Claude biết cần gì.
• Vấn đề permission: script cần quyền thực thi. Chạy chmod +x trên bất kỳ script nào skill của bạn tham chiếu tới.
• Dấu phân tách đường dẫn: dùng dấu gạch chéo xuôi (/) ở mọi nơi, kể cả trên Windows.

Checklist xử lý sự cố nhanh

• Không kích hoạt? Cải thiện description và thêm cụm từ kích hoạt.
• Không nạp được? Kiểm tra đường dẫn, tên file, và cú pháp YAML.
• Sai skill được dùng? Làm các description khác biệt rõ ràng hơn.
• Bị che khuất (shadowed)? Kiểm tra thứ tự ưu tiên và đổi tên nếu cần.
• Skill từ plugin bị thiếu? Xoá cache và cài lại.
• Lỗi runtime? Kiểm tra dependency, permission, và đường dẫn.

Đây là bài giảng cuối cùng trong khóa. Xem thêm tại academy.claude.com/courses/introduction-to-agent-skills/complete.

Nguồn

Dịch từ bài giảng “Troubleshooting skills”, khóa Introduction to agent skills trên Claude Academy.