Troubleshooting skills

• Hầu hết các vấn đề về "Kỹ năng" (Skill) xoay quanh việc không kích hoạt, không tải, xung đột hoặc lỗi trong thời gian chạy, và thường có các giải pháp khắc phục đơn giản.
• Để một Kỹ năng được kích hoạt, mô tả của nó phải có sự khớp ngữ nghĩa với yêu cầu của người dùng, đòi hỏi việc thêm các cụm từ kích hoạt đa dạng.
• Khắc phục sự cố liên quan đến việc kiểm tra cấu trúc tệp, sử dụng các công cụ chẩn đoán như agent skills verifier và claude-debug, cùng với việc xác minh các gói phụ thuộc và quyền thực thi.

• Sử dụng lệnh agent skills verifier để kiểm tra nhanh chóng tình trạng Kỹ năng của bạn sau khi cài đặt.
• Cải thiện mô tả của Kỹ năng bằng cách thêm các cụm từ kích hoạt mà người dùng thực tế sẽ sử dụng để tăng khả năng kích hoạt thông qua khớp ngữ nghĩa.
• Đảm bảo cấu trúc tệp Kỹ năng chính xác: tệp skill.md phải nằm trong một thư mục con có tên, không phải thư mục gốc, và tên tệp phải là skill.md (chữ "s" viết hoa).
• Chạy claude-debug để xác định nguyên nhân gây lỗi tải khi Kỹ năng không xuất hiện, tìm kiếm các thông báo liên quan đến tên Kỹ năng của bạn.
• Để tránh Claude sử dụng sai Kỹ năng hoặc xung đột, hãy làm cho mô tả Kỹ năng của bạn thật khác biệt và cụ thể hơn.
• Nếu Kỹ năng cá nhân bị ghi đè, hãy kiểm tra các Kỹ năng cấp doanh nghiệp hoặc có độ ưu tiên cao hơn với tên tương tự và cân nhắc đổi tên Kỹ năng của bạn.
• Khi Kỹ năng thất bại trong thời gian chạy, hãy đảm bảo các gói bên ngoài (dependencies) đã được cài đặt, script có quyền thực thi, và sử dụng dấu gạch chéo / nhất quán cho đường dẫn.
• Đối với các vấn đề về plugin, hãy xóa bộ nhớ đệm, khởi động lại Claude Code và cài đặt lại; nếu vẫn không hoạt động, kiểm tra cấu trúc plugin bằng công cụ xác thực.

• Skill — Kỹ năng
• Activate — Kích hoạt
• Description — Mô tả
• Runtime — Thời gian chạy
• Verifier (tool/command) — Công cụ/Lệnh xác minh
• Trigger phrase — Cụm từ kích hoạt
• Semantic matching — Khớp ngữ nghĩa
• Plugin — Plugin
• Cache — Bộ nhớ đệm
• Execution permission — Quyền thực thi

Khắc phục sự cố Kỹ năng

Khi Kỹ năng không hoạt động, vấn đề thường thuộc một trong vài loại sau: Kỹ năng không kích hoạt, không tải, có xung đột hoặc thất bại trong thời gian chạy. Nhưng tin tốt là hầu hết các cách khắc phục đều khá đơn giản. Dưới đây là một số cách.

Sử dụng Lệnh xác minh Kỹ năng tác nhân AI

Điều đầu tiên chúng ta có thể làm là thử lệnh agent skills verifier. Tùy thuộc vào hệ điều hành của bạn, các bước cài đặt sẽ khác nhau, nhưng chúng tôi khuyến nghị sử dụng UV vì đây là cách dễ nhất để cài đặt nhanh chóng. Sau khi cài đặt, bạn có thể điều hướng đến thư mục chứa Kỹ năng của mình hoặc chạy lệnh này từ bất kỳ đâu.

Kỹ năng không kích hoạt

Kỹ năng của bạn đã tồn tại và vượt qua công cụ xác thực, nhưng Claude không sử dụng nó khi được mong đợi. Nguyên nhân gần như luôn nằm ở mô tả. Claude sử dụng khớp ngữ nghĩa, vì vậy yêu cầu của bạn cần phải trùng khớp với ý nghĩa của mô tả. Nếu không có đủ sự trùng khớp, sẽ không có kết quả.

Hãy kiểm tra mô tả của bạn so với cách bạn 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, thử nghiệm với các biến thể như "Giúp tôi lập hồ sơ cái này", "Tại sao cái này chậm?", "Làm cái này nhanh hơn". Nếu bất kỳ lời nhắc nào không kích hoạt được, hãy thêm các từ khóa đó vào mô tả của bạn.

Kỹ năng không xuất hiện hoặc không tải

Nếu Kỹ năng của bạn không xuất hiện khi bạn hỏi Claude rằng có những Kỹ năng nào, hãy kiểm tra những điều sau:

• Kỹ năng phải nằm ở đúng vị trí với đúng cấu trúc. Tệp skill.md phải nằm trong một thư mục con (có tên), chứ không phải ở thư mục gốc của các Kỹ năng.
• Tên tệp phải chính xác là skill.md (chữ "skill" viết hoa, ".md" viết thường).

Chạy claude-debug để xem lỗi tải. Tìm kiếm các thông báo có đề cập đến tên Kỹ năng của bạn. Đôi khi điều này sẽ tự động giải quyết vấn đề cho bạn.

Claude sử dụng Kỹ năng sai hoặc Kỹ năng bị ghi đè

Nếu Claude sử dụng sai Kỹ năng hoặc có vẻ bối rối, mô tả của bạn có thể quá giống nhau. Hãy làm cho chúng khác biệt. Hãy nhớ rằng, việc càng cụ thể càng tốt không chỉ giúp Claude quyết định khi nào nên sử dụng Kỹ năng của bạn mà còn tránh xung đột với các Kỹ năng có âm thanh tương tự khác.

Nếu Kỹ năng cá nhân của bạn bị bỏ qua, một Kỹ năng cấp doanh nghiệp hoặc Kỹ năng có độ ưu tiên cao hơn có thể có cùng tên. Vì vậy, hãy điều tra điều đó. Nếu bạn thấy một Kỹ năng cấp doanh nghiệp về code review và bạn cũng có một Kỹ năng cá nhân về code review, thì Kỹ năng cấp doanh nghiệp sẽ luôn được ưu tiên. Giải pháp của bạn là đổi tên Kỹ năng của bạn thành một cái tên khác biệt hơn một chút. Hãy trao đổi với quản trị viên của bạn về Kỹ năng cấp doanh nghiệp, nhưng bạn sẽ có cơ hội tốt hơn với giải pháp đổi tên.

Plugin không hiển thị Kỹ năng

Có thể bạn đã cài đặt plugin nhưng không thể nhìn thấy Kỹ năng của nó? Hãy xóa bộ nhớ đệm, khởi động lại Claude Code và cài đặt lại. Nếu Kỹ năng vẫn không xuất hiện, cấu trúc plugin có thể bị sai. Đây là lúc công cụ xác thực phát huy tác dụng.

Kỹ năng thất bại trong thời gian chạy

Kỹ năng tải thành công nhưng thất bại trong quá trình thực thi.

• Nếu Kỹ năng của bạn sử dụng gói bên ngoài, chúng phải được cài đặt. Hãy thêm thông tin này vào mô tả của bạn.
• Các script cần quyền thực thi.
• Hãy sử dụng dấu gạch chéo / ở khắp mọi nơi, ngay cả trên Windows.

Danh sách kiểm tra nhanh

Vậy, đây là một danh sách kiểm tra nhanh:

• Không kích hoạt? Hãy cải thiện mô tả và các cụm từ kích hoạt của bạn.
• Không tải? Kiểm tra đường dẫn, tên tệp, cú pháp YAML.
• Sử dụng Kỹ năng sai? Hãy làm cho mô tả của bạn khác biệt hơn một chút.
• Bị ghi đè? Kiểm tra độ ưu tiên và đổi tên nếu cần.
• Plugin bị thiếu? Xóa bộ nhớ đệm và cài đặt lại.
• Thất bại trong thời gian chạy? Kiểm tra các gói phụ thuộc, quyền truy cập và đường dẫn.