15.6 · Khắc phục sự cố — Skill debug playbook

Mở đầu: Skill "hỏng" — và tại sao đây là tin tốt

Frustrating? Yes. Nhưng có tin tốt: sự cố skill hầu như luôn rơi vào một trong 6 category có thể đoán được. Otto (Anthropic):

When skills don't work, the problem usually falls into one of a few categories: the skill doesn't trigger, doesn't load, has conflicts, or fails at runtime. The good news is that most fixes are pretty straightforward.

Bài này là playbook — 6 symptom, cho mỗi symptom: checklist chẩn đoán + fix cụ thể. Bạn không cần memorize — bookmark bài này, quay lại khi gặp sự cố.

Thứ tự chẩn đoán đề xuất:

┌──────────────────────────────────────┐
│  1. Skills Validator  (structural)   │ ← check đầu tiên, 30s
│  2. Skill không trigger              │
│  3. Skill không load                 │
│  4. Wrong skill được dùng            │
│  5. Priority conflict                │
│  6. Plugin skill không xuất hiện     │
│  7. Runtime error khi execute        │
└──────────────────────────────────────┘

Công cụ #1: Skills Validator

Trước khi debug sâu, luôn chạy validator trước. Nó catch 80% structural issue trong 30 giây.

Cài đặt với uv

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

pip install uv

Chạy validator

cd ~/.claude/skills/pr-review
uvx agent-skills-verifier check .

uvx agent-skills-verifier check ~/.claude/skills/

Output điển hình

Pass:

✓ pr-review/SKILL.md — valid frontmatter
✓ pr-review/SKILL.md — name matches folder
✓ pr-review/SKILL.md — description present

Fail:

✗ pr-review/SKILL.md — description missing
✗ pr-review/SKILL.md — name 'pr_review' contains underscore (use hyphen)
✗ pr-review/SKILL.md — file should be SKILL.md (found skill.md)

Nếu validator fail → fix theo hướng dẫn, chạy lại. Nếu pass nhưng vẫn có vấn đề → tiếp tục 6 category dưới.

Category 1: Skill không trigger

Symptom

Bạn chắc chắn skill đã load (xuất hiện trong "what skills are available"), nhưng khi bạn gõ trigger phrase, Claude không dùng skill.

Chẩn đoán

Nguyên nhân #1 (90% trường hợp): Description không overlap request

Claude dùng semantic matching, request phải có overlap với description:

Description skill: "Writes pull request descriptions. Use when creating a PR, writing a PR, or summarizing changes for a pull request."

Request: "Can you summarize my git diff for me?"
         ↓
Claude check overlap:
  "git diff" — không có trong description
  "summarize" — có trong description ("summarizing changes")
  "my" — không có ý nghĩa matching
         ↓
Kết quả: partial match, không đủ confidence → không trigger

Fix

Bước 1: Liệt kê 5 variation user (bao gồm bạn) có thể dùng:

• "Write a PR description"
• "Summarize my changes"
• "Create a pull request description"
• "Help me write a PR"
• "Summarize the git diff for a PR"

Bước 2

Test mỗi variation. Cái nào fail → thiếu keyword gì?

Bước 3

Thêm keyword vào description:

description: Writes pull request descriptions. Use when creating a PR or writing a PR.

description: Writes pull request descriptions. Use when creating a PR, writing a PR, summarizing changes, summarizing a git diff, or when asked to write PR feedback for a branch.

Bước 4: Restart Claude Code. Test lại.

Litton's pro tip

Nếu thử nhiều variation mà không trigger, dùng exact skill name trong prompt:

"Use the pr-description skill to write a PR description for my changes."

Explicit mention → Claude buộc phải dùng skill đó. Sau khi skill trigger ít nhất 1 lần, bạn hiểu nó match keyword gì → điều chỉnh description.

Category 2: Skill không load

Symptom

Bạn gõ "what skills are available?" — skill của bạn không có trong danh sách.

Chẩn đoán — 5 điểm kiểm tra

Check 1: Tên file chính xác SKILL.md

Case-sensitive! Claude Code phân biệt:

• SKILL.md — đúng (cap SKILL, lowercase md)
• skill.md — sai
• Skill.md — sai
• SKILL.MD — sai

ls ~/.claude/skills/pr-review/

Check 2: File SKILL.md nằm trong folder có tên (không ở root)

• ~/.claude/skills/pr-review/SKILL.md
• ~/.claude/skills/SKILL.md ← không trong named folder
• ~/.claude/skills/pr-review.md ← không phải folder

Check 3: Folder đúng location

• Personal: ~/.claude/skills/ (Linux/macOS) hoặc C:\Users\<name>\.claude\skills\ (Windows)
• Project: <repo-root>/.claude/skills/

Typo nhẹ (ví dụ .claude/skill/ — thiếu s) → Claude không tìm thấy.

Check 4: YAML frontmatter đúng syntax

---
name: pr-review
description: ...
---

• Có --- ở đầu và cuối
• Indent bị sai → YAML invalid
• Quote không match → YAML invalid

Ví dụ fail:

---
name: pr-review
  description: ...     ← wrong indent
---

Check 5: Chưa restart Claude Code

Skill scan ở startup. Thêm skill mới → không auto reload. Phải /quit + claude.

Fix tool: claude --debug

Chạy Claude với debug flag để thấy loading errors:

claude --debug

Output có thể có:

[DEBUG] Scanning ~/.claude/skills/...
[DEBUG] Found folder: pr-review
[DEBUG] Loading pr-review/SKILL.md...
[ERROR] pr-review: YAML parse error at line 3: unexpected token

Error message thường chỉ thẳng vấn đề. Fix theo hướng dẫn → restart.

Checklist summary

• File name chính xác SKILL.md (cap SKILL, lower md)
• File trong folder có tên, không ở root skills/
• Location path đúng (~/.claude/skills/ hoặc .claude/skills/ trong repo)
• YAML frontmatter parse được (có --- 2 đầu, indent OK)
• name và description field có mặt
• Đã restart Claude Code sau khi tạo/sửa

Category 3: Wrong skill được dùng

Symptom

Claude trigger skill, nhưng sai skill. Bạn muốn pr-review, nó lại load code-explain. Hoặc Claude hỏi "should I use skill A or skill B?" — confused.

Nguyên nhân

Description quá tương tự nhau. Claude không phân biệt nổi.

Ví dụ fail:

name: pr-review
description: Reviews code changes.

name: code-review
description: Reviews code quality.

name: merge-check
description: Reviews changes before merge.

3 skill này overlap 80% ý nghĩa. Claude sẽ:

• Match cả 3 → hỏi user chọn
• Hoặc match sai (random 1 trong 3)

Fix: Làm description distinct

Cách 1: Add specific context

name: pr-review
description: Reviews pull requests for correctness, typing, and test coverage. Use when reviewing a PR, checking code changes against team standards.

name: security-review
description: Reviews code for security vulnerabilities per OWASP top 10. Use when asked for security audit, security check, or auth/crypto review.

name: pre-merge-check
description: Runs pre-merge verification checklist (tests passing, docs updated). Use before merging, when asked "is this ready to merge?"

3 skill có purpose distinct, không overlap nữa.

Cách 2: Consolidate

Nếu 3 skill thực sự làm cùng thứ, merge thành 1 skill tốt hơn:

name: pr-comprehensive-review
description: Reviews PR comprehensively - correctness, security, pre-merge checks. Use when reviewing a PR or preparing it for merge.

Anti-pattern

Đừng tạo skill tên chung chung như review, check, write. Luôn specific:

Category 4: Priority conflict

Symptom

Bạn có skill code-review personal. Nhưng mỗi khi trigger, version khác được load (enterprise, project, hoặc plugin).

Chẩn đoán

Nhớ lại priority hierarchy (Bài 15.1 & 15.3):

1. Enterprise  (highest)
2. Personal
3. Project
4. Plugins     (lowest)

Nếu 2+ skill cùng tên ở các tầng khác nhau → tầng cao hơn thắng.

Ví dụ điển hình

Setup của Minh:

• Personal ~/.claude/skills/code-review/ — style của Minh (hơi informal)
• Clone repo về, project có .claude/skills/code-review/ — style của team (formal hơn)
• Công ty deploy enterprise code-review — mandatory OWASP check

Khi Minh gõ "review this PR":

• Enterprise version thắng
• Personal + project đều bị đè

Fix

Option 1: Rename skill của bạn (dễ nhất)

Đổi tên personal skill thành my-code-review:

mv ~/.claude/skills/code-review ~/.claude/skills/my-code-review

Update frontmatter name: my-code-review. Restart.

Giờ user gõ "review this PR":

• Enterprise code-review trigger
• Hoặc personal my-code-review trigger (nếu mention cụ thể)

Option 2: Talk to admin (dành cho enterprise conflict)

Nếu enterprise version có bug hoặc không phù hợp workflow → báo admin fix/whitelist. Đường này chậm hơn, ưu tiên Option 1.

Option 3: Xóa skill tầng thấp hơn (nếu thực sự không cần)

Nếu project skill đã duplicate personal:

rm -rf .claude/skills/code-review

Debug: Skill nào đang thắng?

Trong Claude Code, hỏi:

Which version of code-review skill am I using?

Claude sẽ report nó load từ path nào. Bạn biết tầng nào đang thắng.

Category 5: Plugin skill không xuất hiện

Symptom

Cài plugin thành công (claude plugin install ...), nhưng skill trong plugin không hiển thị trong danh sách available skills.

Chẩn đoán

Nguyên nhân 1: Cache chưa clear

Claude Code cache skill metadata ở startup. Install plugin giữa session → cache chưa update.

Nguyên nhân 2: Plugin structure sai

Plugin phải có skill ở đúng path:

my-plugin/
├── plugin.json
└── skills/                  ← không phải .claude/skills/
    └── my-skill/
        └── SKILL.md

Nguyên nhân 3: Plugin không được enable

Một số plugin cần enable explicit trong settings.

Fix — Theo thứ tự

Step 1: Clear cache + restart + reinstall plugin:

claude plugin uninstall <plugin-name>
claude plugin install <plugin-name>

Step 2: Run validator trên plugin:

cd <path-to-plugin>
uvx agent-skills-verifier check .

Nếu validator báo lỗi → plugin structure sai. Báo cho plugin author.

Step 3: Check plugin enabled trong settings:

Settings → Plugins → enable <plugin-name>

Step 4: Kiểm tra strictKnownMarketplaces (nếu enterprise):

Nếu tổ chức bạn có enterprise managed settings với strictKnownMarketplaces, plugin phải từ whitelisted source. Nếu không, plugin bị block silently.

Category 6: Runtime error

Symptom

Skill trigger thành công, load đúng, nhưng fail trong lúc execute. Lỗi như:

Error: command not found: some-script.py
Error: permission denied: run /path/to/script.sh
Error: module 'pandas' not found

Nguyên nhân phổ biến

Nguyên nhân 1: Missing dependencies

Skill dùng external package (Python lib, CLI tool) mà máy chưa cài.

Fix

Document dependency trong description:

description: Analyzes CSV data with pandas. Use when analyzing CSV, spreadsheet, or tabular data. Requires: python 3.9+, pandas, numpy (install via pip install -r requirements.txt in skill folder).

Hoặc trong SKILL.md body:

Prerequisites

Before using this skill, install:

• Python 3.9+
• pandas 2.0+
• numpy 1.24+

pip install -r requirements.txt

User đọc instruction trước khi trigger → biết cần cài gì.

**Nguyên nhân 2: Permission issue**

Script không execute permission.

### Fix

chmod +x ~/.claude/skills/<skill-name>/scripts/.sh chmod +x ~/.claude/skills/<skill-name>/scripts/.py

**Nguyên nhân 3: Path separator (Windows)**

Hardcode Windows path:

FILE_PATH = "C:\Users\John\file.txt" ← backslash, fail trên macOS/Linux

### Fix

**Use forward slash everywhere, hoặc `os.path.join`:**

import os FILE_PATH = os.path.join(os.path.expanduser("~"), "file.txt")

**Nguyên nhân 4: Working directory không đúng**

Script chạy relative path → fail khi cwd không phải skill folder.

### Fix

Dùng absolute path từ `__file__`:

import os SKILL_DIR = os.path.dirname(os.path.abspath(__file__)) TEMPLATE_PATH = os.path.join(SKILL_DIR, "..", "assets", "template.md")

---

Quick Troubleshooting Checklist

Bookmark checklist này. Khi skill hỏng:

┌──────────────────────────────────────────────────────────┐
│  SYMPTOM                       FIRST ACTION              │
├──────────────────────────────────────────────────────────┤
│  Không trigger                 → Add trigger phrases     │
│                                 vào description          │
│                                                          │
│  Không load                    → Check file name         │
│                                 SKILL.md + path          │
│                                 + restart                │
│                                                          │
│  Wrong skill được dùng         → Make descriptions       │
│                                 distinct                 │
│                                                          │
│  Bị shadowed bởi skill khác    → Check priority          │
│                                 hierarchy + rename       │
│                                                          │
│  Plugin skill missing          → Clear cache + reinstall │
│                                 + run validator          │
│                                                          │
│  Runtime failure               → Check dependencies,     │
│                                 permissions, paths       │
└──────────────────────────────────────────────────────────┘

Quy trình QC trước khi share skill

Sau khi build skill, trước khi commit/share, chạy qua 10-point QC:

Content QC

• SKILL.md < 500 dòng (nếu dài hơn, split ra references/)
• Instructions cụ thể, không vague ("make it good" không được)
• Ví dụ / template có trong SKILL.md hoặc link tới assets/
• Nếu skill có script: link đúng với scripts/<name>, nói rõ "run" (không "read")

Structural QC

• Tên folder = name frontmatter (lowercase, dash, không underscore)
• File tên chính xác SKILL.md (cap SKILL, lower md)
• YAML frontmatter parse được (test: python -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1])")
• Validator pass: uvx agent-skills-verifier check .

Description QC

• Description 150-300 chars
• 3-5 trigger phrases liệt kê
• Action verb đầu câu (Writes, Reviews, Generates, Analyzes...)
• Distinct với skill khác cùng tên (check hierarchy)

Functional QC

• Test với 5 variation prompt — all trigger đúng?
• Test edge case: request mơ hồ — skill có over-trigger không?
• Test không trigger phrase — skill có tự active không khi không nên?
• Output consistent qua 3 lần chạy liên tiếp?

Sharing readiness QC

• README.md repo mention skill với trigger phrase
• Không có secret hardcoded trong bất kỳ file nào của skill
• Dependency document rõ (nếu có)
• Path dùng forward slash, không hardcode /Users/john/

Nếu ≥ 3 item unchecked → iterate trước khi share.

Advanced: --debug deep dive

Khi các check trên không giải quyết, bật debug mode:

claude --debug 2>&1 | tee claude-debug.log

Trong session, trigger skill có vấn đề. Sau đó inspect log:

grep -i "skill\|pr-review\|error" claude-debug.log

Các dòng hữu ích:

[DEBUG] Loading skills from ~/.claude/skills/...
[DEBUG] Skill 'pr-review' loaded: name=pr-review, description_len=247
[DEBUG] Matching user input against skills...
[DEBUG] Skill 'pr-review' match score: 0.82 (passed threshold 0.7)
[DEBUG] Activating skill 'pr-review'
[DEBUG] Loading full SKILL.md (452 lines)
[ERROR] Skill script not executable: scripts/check.py

Log này tell bạn chính xác claude đang làm gì / fail ở bước nào.

Case studies — Lỗi thực tế & fix

Case 1: Minh (team lead) — skill không trigger

Symptom

Minh viết skill pr-review, validator pass, trong danh sách, nhưng gõ "check my diff" không trigger.

Diagnosis

Description chỉ có "Reviews pull requests". "check my diff" không overlap đủ.

Fix:

description: Reviews pull requests for quality.

description: Reviews pull requests for code quality. Use when asked to review a PR, check my changes, check my diff, or give feedback on code before merge.

Result: Trigger 100% với cả 4 variation.

Case 2: Linh (marketing) — wrong skill

Symptom

Linh có 2 skill blog-writer và social-writer. Claude trigger blog-writer cho cả blog lẫn social posts.

Diagnosis

Description của 2 skill quá giống:

• blog-writer: "Writes content for company."
• social-writer: "Writes social content."

Fix:

description: Writes long-form blog posts (1500+ words) for the company blog. Use when writing a blog post, article, or long-form content.

description: Writes short-form social media posts (< 280 chars for Twitter, 1200 for LinkedIn). Use when writing a tweet, LinkedIn post, Twitter thread, or social post.

Result: Claude phân biệt rõ. "Write a tweet" trigger social-writer, không trigger blog-writer.

Case 3: Hằng (finance) — runtime error

Symptom: Skill monthly-reconcile load OK, start script fail:

Error: command not found: match_transactions.py

Diagnosis: Script không có execute permission + script absolute path không đúng.

Fix:

chmod +x ~/.claude/skills/monthly-reconcile/scripts/*.py

Cũng update script dùng os.path thay vì hardcode path.

Result: Script chạy OK cross-platform.

Case 4: Bảo (new hire) — priority conflict

Symptom

Bảo tạo personal code-review nhưng nó không bao giờ trigger. Thay vào đó, version khác chạy (formal hơn style của Bảo).

Diagnosis

Repo có .claude/skills/code-review (project). Priority 3 > Priority 2 sai — project thấp hơn personal. Vậy tại sao personal không thắng?

Tìm ra

Enterprise code-review deploy bởi admin — priority 1, override tất cả.

Fix

Bảo rename personal thành my-informal-review:

mv ~/.claude/skills/code-review ~/.claude/skills/my-informal-review

Và trigger với cụm cụ thể: "use my-informal-review to check my changes".

Result: Khi cần review formal (compliance), Bảo gõ "review" → enterprise trigger. Khi cần style cá nhân, Bảo nói "my-informal-review".

Anti-patterns — Sai lầm khi debug

Restart 10 lần hy vọng sẽ work

Triệu chứng

Skill fail → restart Claude → vẫn fail → restart lại → ...

Tại sao tệ

Tốn thời gian. Không giải quyết root cause.

Cách đúng

Chạy validator + --debug trước. Đọc error. Fix root cause. 1 restart là đủ nếu fix đúng.

Thêm trigger phrase ngẫu nhiên vào description

Triệu chứng

Skill không trigger → add 20 keyword vào description hoping sẽ work.

Tại sao tệ

Description phình to. Match độ chính xác giảm (over-trigger). Overhead token startup tăng.

Cách đúng

Thêm trigger phrase theo user actual usage. Observe 5-10 actual prompt user dùng → add chính xác những keyword đó.

Debug mà không đọc error message

Triệu chứng

Claude fail → re-run → re-run → không đọc terminal.

Tại sao tệ

Error message thường chỉ thẳng vấn đề. Bỏ qua = miss clue miễn phí.

Cách đúng

Mỗi khi fail, đọc đầy đủ error. Copy error message → search docs / community. 90% case solution nằm trong error.

Fix 1 skill, phá 3 skill khác

Triệu chứng

Sửa skill A trigger lớn, đổi description. Sau đó skill B, C, D bị ảnh hưởng vì over-trigger.

Tại sao tệ

Description A giờ match prompt của B, C, D.

Cách đúng

Sau khi sửa skill A, test tất cả skill relevant. Đảm bảo B, C, D vẫn trigger đúng cho prompt của chúng.

Áp dụng ngay

Bài tập 1: Chạy validator + QC trên skill đã có (~15 phút)

Bước 1: Cài validator (nếu chưa):

curl -LsSf https://astral.sh/uv/install.sh | sh

Bước 2: Chạy validator trên toàn bộ skill của bạn:

uvx agent-skills-verifier check ~/.claude/skills/

Ghi ra:

• Số skill pass: _____
• Số skill fail: _____
• Top 3 issue phổ biến: _____

Bước 3

Fix từng issue. Chạy lại validator. Pass 100%.

Bước 4

Chạy 10-point QC checklist trên skill quan trọng nhất (skill bạn share team). Mark unchecked item → fix.

Bài tập 2: Test trigger variation (~10 phút)

Pick 1 skill. Viết 5 variation prompt:

1. _________________________________
2. _________________________________
3. _________________________________
4. _________________________________
5. _________________________________

Test từng variation. Cái nào không trigger → note keyword thiếu. Add vào description. Retest.

Target: 5/5 trigger sau khi fix.

Tóm tắt bài học

Course wrap-up

Chúc mừng! Bạn đã hoàn thành khóa Introduction to Agent Skills.

Bạn đã học:

• Bài 15.0-15.2: Hiểu bản chất skill, phân biệt với CLAUDE.md/slash command
• Bài 15.2-15.4: Tạo skill đầu tiên + nâng cấp lên multi-file với progressive disclosure
• Bài 15.4: Chọn đúng cơ chế trong 5 cái (skill, CLAUDE.md, subagent, hook, MCP)
• Bài 15.5: Share skill qua 3 kênh (repo, plugin, enterprise)
• Bài 15.6: Debug 6 category sự cố

Skill tốt nhất đến từ pain point thực tế. Otto nhắc:

The best skills come from real pain points — start with the instructions you find yourself repeating most often.

Đừng build 20 skill cuối tuần (như Litton cảnh báo). Start with one. Task bạn làm nhiều nhất, cùng process mỗi lần → skill đầu tiên của bạn. Từ đó, skill thứ 2, thứ 3 đến nhanh hơn rất nhiều.

Đừng bỏ qua Bài 15.7 — quiz tổng hợp 25 câu để verify hiểu biết.

Tài liệu tham khảo

• Anthropic Academy — "Troubleshooting skills"
• Video — "Troubleshooting"
• Skills Validator — official validator tool
• claude --debug docs — Claude Code CLI reference