Bỏ qua đến nội dung chính

Troubleshooting skills

                        (Show All)_ · **Bài 6/6** · [🌐 English](../../en/06-troubleshooting-skills/en.md)

← Bài trước · 📋 Mục lục khoá · Bài sau: —

Troubleshooting skills

👨‍💻 Track: Developer Track · 📚 Course: Introduction to Agent Skills · ⏱ 15 phút · 🧭 Path C

📖 Nội dung bài học

Bạn sẽ học được gì

Thời gian ước tính: 15 phút

Đến cuối bài học này, bạn sẽ có thể:

  • Dùng công cụ xác thực skills để bắt các vấn đề cấu trúc trước khi debug
  • Chẩn đoán và sửa các vấn đề thường gặp khi kích hoạt và load skill
  • Giải quyết xung đột ưu tiên skill giữa skills của doanh nghiệp, cá nhân, dự án và plugin
  • Debug các lỗi runtime, bao gồm các dependency bị thiếu, vấn đề về quyền và đường dẫn

Xử lý sự cố skills

(4 phút)

Khi skills không hoạt động như mong đợi, vấn đề thường rơi vào một vài loại có thể dự đoán được. Video này sẽ hướng dẫn bạn từng loại — từ skills không kích hoạt đến xung đột ưu tiên và lỗi runtime — và cung cấp cho bạn một cách tiếp cận xử lý sự cố có hệ thống. Bạn cũng sẽ học về công cụ xác thực skills và cách dùng claude --debug để chẩn đoán các vấn đề về loading.

Những điểm chính

  • Bắt đầu với công cụ xác thực skills — nó bắt các vấn đề cấu trúc trước khi bạn dành thời gian debug những thứ khác
  • Nếu một skill không kích hoạt, nguyên nhân hầu như luôn là do phần mô tả — thêm các cụm từ kích hoạt phù hợp với cách bạn thực sự diễn đạt các yêu cầu
  • Nếu một skill không load, hãy kiểm tra xem SKILL.md có nằm bên trong một thư mục có tên (không phải ở root của skills) và tên file chính xác là SKILL.md
  • Nếu skill sai được dùng, phần mô tả của bạn quá giống nhau — làm cho chúng khác biệt hơn
  • Đối với lỗi runtime, hãy kiểm tra các dependency, quyền file (chmod +x), và dấu phân cách đường dẫn (dùng dấu gạch chéo về phía trước ở mọi nơi)

Khi skills không hoạt động, vấn đề thường rơi vào một trong một vài loại: skill không kích hoạt, không load, có xung đột hoặc bị lỗi runtime. Tin tốt là hầu hết các cách sửa đều khá đơn giản.

Dùng Skills Validator

Điều đầu tiên cần thử là lệnh xác minh agent skills. Các bước cài đặt khác nhau tùy theo hệ điều hành, nhưng dùng uv là cách dễ nhất để thiết lập nhanh chóng.

Sau khi cài đặt, bạn có thể điều hướng đến thư mục skill của mình hoặc chạy lệnh từ bất kỳ đâu. Trình xác thực sẽ bắt các vấn đề cấu trúc trước khi bạn dành 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 quá trình xác thực, nhưng Claude không dùng nó khi bạn mong đợi. Nguyên nhân hầu như luôn là do phần mô tả.

Claude dùng semantic matching, 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 phần mô tả. Nếu không có đủ sự trùng khớp, sẽ không có kết quả nào. Đây là những việc cần làm:

  • Kiểm tra phần mô tả của bạn với cách bạn thực sự diễn đạt các 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
  • Kiểm tra với các biến thể như "giúp tôi profile cái này", "tại sao cái này chậm?", "làm cho 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 các từ khóa đó vào phần mô tả của bạn

Skill không load

Nếu skill của bạn không xuất hiện khi bạn hỏi Claude "những skills nào có sẵn", 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 phải ở root của skills
  • Tên file phải chính xác là SKILL.md — tất cả chữ in hoa ở "SKILL", chữ thường ở "md"

Chạy claude --debug để xem các lỗi loading. Tìm các tin nhắn đề cập đến tên skill của bạn. Đôi khi chỉ điều này thôi cũng sẽ chỉ ra vấn đề cho bạn.

Skill sai được dùng

Nếu Claude dùng skill sai hoặc có vẻ bối rối giữa các skills, phần mô tả của bạn có lẽ quá giống nhau. Hãy làm cho chúng khác biệt. Càng cụ thể càng tốt không chỉ giúp Claude quyết định khi nào dùng skill của bạn — nó còn ngăn ngừa xung đột với các skills khác có âm thanh tương tự.

Xung đột ưu tiên skill

Nếu skill cá nhân của bạn bị bỏ qua, một skill của doanh nghiệp hoặc skill có mức ưu tiên cao hơn có thể có cùng tên.

Ví dụ: nếu có một skill "code-review" của doanh nghiệp và bạn cũng có một skill "code-review" cá nhân, thì skill của doanh nghiệp sẽ thắng mọi lúc. Các lựa chọn của bạn:

  1. Đổi tên skill của bạn thành một thứ gì đó khác biệt hơn (đây thường là cách dễ dàng hơn)
  2. Nói chuyện với quản trị viên của bạn về skill của doanh nghiệp

Plugin Skills không xuất hiện

Đã cài đặt plugin nhưng không thấy skills của nó? Xóa cache, khởi động lại Claude Code và cài đặt lại.

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

Lỗi Runtime

Skill load nhưng bị lỗi trong quá trình thực thi. Một vài nguyên nhân phổ biến:

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

Checklist xử lý sự cố nhanh

  • Không kích hoạt? Cải thiện phần mô tả của bạn và thêm các cụm từ kích hoạt.
  • Không load? Kiểm tra đường dẫn, tên file và cú pháp YAML của bạn.
  • Dùng skill sai? Làm cho phần mô tả khác biệt hơn với nhau.
  • Bị che khuất? Kiểm tra thứ bậc ưu tiên và đổi tên nếu cần.
  • Plugin skills bị thiếu? Xóa cache và cài đặt lại.
  • Lỗi runtime? Kiểm tra các dependency, quyền và đường dẫn.

Bài học phản ánh

  • Bạn đã gặp bất kỳ tình huống xử lý sự cố nào trong công việc của mình chưa? Cách sửa nào sẽ giúp bạn tiết kiệm được nhiều thời gian nhất?
  • Bạn sẽ thiết lập quy trình như thế nào để xác thực skills trước khi chia sẻ chúng với nhóm của mình?

Tổng kết khóa học

Chúc mừng bạn đã hoàn thành Giới thiệu về Agent Skills! Bạn đã học cách tạo, cấu hình, chia sẻ và xử lý sự cố skills trong Claude Code. Khi bạn bắt đầu xây dựng skills cho quy trình làm việc của riêng mình, hãy nhớ rằng các skills tốt nhất đến từ những điểm khó khăn thực tế — hãy bắt đầu với các hướng dẫn mà bạn thấy mình lặp lại thường xuyên nhất.

Phản hồi

Chúng tôi rất muốn nghe bạn dùng skills trong công việc của mình như thế nào, cộng với bất kỳ phản hồi nào về khóa học này. Chia sẻ phản hồi của bạn tại đây.

🔁 Bài học liên quan

📚 Nguồn & ghi nhận

Bài học có hữu ích không?

Góp ý / Báo lỗiPhát hiện sai sót hoặc có ý tưởng cải thiện?