Khi Claude Skill không chạy hoặc chạy sai — tìm đúng chỗ để sửa

Playbook này dành cho ai?

Bạn đã có ít nhất 1 skill thực sự đang dùng (không phải skill demo) qua Tạo Claude Skill đầu tiên hoặc Framework 5 phần. Sau 1-2 tuần, bạn gặp tình huống: nhờ "tóm tắt email này" mà Claude tự tóm tắt theo cách của nó (skill không kích hoạt), hoặc skill kích hoạt nhưng làm sai bước, hoặc kết quả đúng quy trình mà giọng nhạt, hoặc skill lặp lại cùng lỗi dù đã nhắc 3-4 lần, hoặc 2 tuần trước chạy ngon mà hôm nay tự dưng kỳ lạ — không thay đổi gì.

Đây là 5 lỗi phổ biến nhất khi vận hành skill. Mỗi lỗi sửa ở chỗ khác nhau — sửa sai chỗ thì skill rối thêm. Playbook này dạy bạn chẩn đoán trước, sửa sau: hỏi 4 câu → sửa đúng file (description / body / references / quy tắc) → kiểm lại bằng dữ liệu thực tế. Bài cũng chỉ cách xử lý chuyện skill chạy lệch sau khi Claude cập nhật model, và checklist kiểm skill cài từ ngoài.

Không cần biết code. Cần biết đọc YAML frontmatter (xem Bên trong một Claude Skill) và markdown body.

Bạn sẽ đạt được gì?

• Chẩn đoán nhanh 4 triệu chứng — không kích hoạt / sai bước / kết quả nhạt / lặp lại lỗi
• Biết sửa ở đâu — description (frontmatter) / body / references / quy tắc — không sửa bừa
• Xử lý chuyện skill cũ chạy lệch sau khi Claude cập nhật model — không đổi gì mà tự dưng sai
• Checklist 3 bước kiểm tra skill từ bên ngoài trước khi cài (rà soát bảo mật)
• Cách dọn skill định kỳ — xoá skill bỏ không, sửa đường dẫn hỏng, gộp mô tả trùng

Bạn cần chuẩn bị gì?

• Đã đọc Bên trong một Claude Skill (cấu trúc SKILL.md) và Tạo Claude Skill đầu tiên (tạo skill cơ bản). Tốt hơn nếu đã đọc Framework 5 phần.
• 1 skill đang gặp vấn đề — đem theo, sẽ gỡ lỗi thật trong bài
• 2-3 dữ liệu thật đã làm skill sai — không bịa, không chung chung. Skill chỉ lộ điểm yếu khi gặp dữ liệu thật.

---

Bức tranh toàn cảnh

Skill chạy sai có 4 nguồn gốc chính, mỗi nguồn sửa ở một file khác nhau. Cộng thêm 2 vấn đề "ngoài skill" — skill chạy lệch sau khi Claude cập nhật model, và việc kiểm tra skill cài từ ngoài.

Triệu chứng	Nguồn gốc	Sửa ở	Mục
Skill không kích hoạt	Dòng mô tả (description) mơ hồ / trùng nhau	frontmatter (description)	1
Kích hoạt nhưng làm sai bước	Quy trình chưa đủ rõ	body (mục Quy trình)	2
Làm đúng quy trình nhưng kết quả nhạt	Thiếu file tham chiếu	references/	3
Lặp lại cùng một lỗi	Thiếu quy tắc	body (mục Quy tắc)	4
Skill cũ tự dưng chạy lệch (không đổi gì)	Model vừa cập nhật	Bỏ bớt hướng dẫn thừa	5
Cần cài skill ngoài	Rủi ro bảo mật	Kiểm 3 bước trước khi cài	6

Quy tắc cốt lõi của bài này: chẩn đoán trước, sửa sau. Đừng sửa bừa — sửa sai chỗ làm skill rối hơn ban đầu.

---

Trước khi bắt đầu — nơi gõ prompt sửa skill

Mọi mục dưới có khối prompt để bạn dán cho Claude tự sửa file. Cần gõ đúng nơi thì Claude mới tìm thấy skill. Khác nhau giữa Cowork và Code:

Trên Cowork (Claude.ai)

1. Sidebar trái → click vào Project chứa skill (không phải chat ngoài Project). Vào đúng Project thì Claude mới biết skill nào đang nói tới.
2. Bấm "+ New chat" trong Project đó (chat mới, không tiếp chat cũ — tránh context cũ làm nhiễu).
3. Dán prompt sửa, gõ Enter. Claude trả lời "đã cập nhật skill" kèm preview SKILL.md mới.
4. Kiểm lại: sidebar trái → Customize → Skills → click tên skill → đọc SKILL.md ở panel phải. Đoạn vừa sửa đã đổi đúng chưa?

Trên Claude Code (terminal)

1. Mở terminal, cd vào folder project chứa .claude/skills/<tên-skill>/. Sai folder → Claude không thấy skill local.
2. Gõ claude mở session mới.
3. Dán prompt sửa, Enter. Claude edit file .claude/skills/<tên-skill>/SKILL.md trực tiếp — bạn thấy diff trong session.
4. Kiểm lại: mở .claude/skills/<tên-skill>/SKILL.md trong trình soạn thảo (VS Code, Cursor, Typora) đọc lại. Hoặc dùng git diff để xem chính xác đã đổi gì.

Mẹo: mọi prompt dưới có <name> — thay bằng tên skill thật của bạn (vd tom-tat-email). Quên thay, Claude sẽ hỏi lại "skill nào" — không phải lỗi.

---

1. Triệu chứng 1 — Skill không kích hoạt

Bạn nhờ "tóm tắt email này" — Claude trả lời "OK đây là tóm tắt:" rồi tự làm theo cách của nó. Không nhắc skill, không bám định dạng đã định.

Cách kiểm tra

1. Mở chat mới (để loại trừ trường hợp bộ nhớ chat bị đầy — xem Mục 5).
2. Thử 5 cách yêu cầu khác nhau cho cùng skill:
   • "tóm tắt email này"
   • "rút gọn báo cáo dài"
   • "tin nhắn từ sếp nói gì"
   • "summarize this email"
   • "/tom-tat-email" (gọi thẳng slash)
3. Đếm: trong 5 cách, skill kích hoạt mấy lần?

Kết quả	Chẩn đoán
0/5	Description quá mơ hồ — LLM không khớp được
1-2/5	Description thiếu các cụm từ kích hoạt phổ biến
3-4/5	Description ổn, còn 1-2 cách diễn đạt chưa bao phủ hết — vẫn chấp nhận được.
4-5/5 nhưng skill khác kích hoạt	Description trùng với skill khác (xem dưới)
5/5 (chỉ qua lệnh tắt)	Description đủ rõ nhưng tính năng tự nhận diện đang tắt — kiểm user-invocable

Cách sửa (nguồn gốc 1 — description mơ hồ)

Description nằm trong frontmatter (xem Bên trong một Claude Skill). Quy tắc: đẩy phần kích hoạt lên ngay câu đầu. Dán prompt sau (theo môi trường ở mục "Trước khi bắt đầu" — Cowork: chat mới trong Project; Code: session trong folder project):