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

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

Chạy validator

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

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

# Hoặc dùng pip
pip install uv

Chạy validator

Output điển hình

Pass:

# Chạy trên skill cụ thể
cd ~/.claude/skills/pr-review
uvx agent-skills-verifier check .

# Chạy trên toàn bộ skills folder
uvx agent-skills-verifier check ~/.claude/skills/

Output điển hình

Fail:

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

Công cụ #1: Skills Validator (tiếp)

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.

✗ 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)

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:

Fix

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

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:

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

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 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:

# Trước
description: Writes pull request descriptions. Use when creating a PR or writing a PR.

# Sau
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.

Litton's pro tip

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.

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

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:

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

Check 3: Folder đúng location

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

Check 4: YAML frontmatter đúng syntax

• ✅ SKILL.md — đúng (cap SKILL, lowercase md)
• ❌ skill.md — sai
• ❌ Skill.md — sai
• ❌ SKILL.MD — sai
• ✅ ~/.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
• Personal: ~/.claude/skills/ (Linux/macOS) hoặc C:\Users\<name>\.claude\skills\ (Windows)
• Project: <repo-root>/.claude/skills/

ls ~/.claude/skills/pr-review/
# phải thấy: SKILL.md

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

Ví dụ fail:

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

name: pr-review
description: ...

Category 2: Skill không load (tiếp)

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:

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

Fix tool: claude --debug

Output có thể có:

claude --debug

Category 2: Skill không load (tiếp)

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

[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

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:

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

Fix: Làm description distinct

Cách 1: Add specific context

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

# Skill 1
name: pr-review
description: Reviews code changes.

# Skill 2
name: code-review
description: Reviews code quality.

# Skill 3
name: merge-check
description: Reviews changes before merge.

Fix: Làm description distinct

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:

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

# Skill 2
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.

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

Category 3: Wrong skill được dùng (tiếp)

Anti-pattern

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

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

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):

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:

Khi Minh gõ "review this PR":

Fix

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

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

• 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
• Enterprise version thắng
• Personal + project đều bị đè

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

Fix

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

Giờ user gõ "review this PR":

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:

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

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

Category 4: Priority conflict (tiếp)

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

Trong Claude Code, hỏi:

rm -rf .claude/skills/code-review
# (cân nhắc trước khi xóa project skill — ảnh hưởng team)

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

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

Which version of code-review skill am I using?

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:

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:

Step 2: Run validator trên plugin:

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

claude plugin uninstall <plugin-name>
# Restart Claude Code
claude plugin install <plugin-name>
# Restart again

Fix — Theo thứ tự

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

Step 3: Check plugin enabled trong settings:

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

Category 5: Plugin skill không xuất hiện (tiếp)

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.

Settings → Plugins → enable <plugin-name>

Category 6: Runtime error

Symptom

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

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:

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

Fix

Hoặc trong SKILL.md body:

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).

Category 6: Runtime error (tiếp)

pip install -r requirements.txt

## Prerequisites

Before using this skill, install:

- Python 3.9+
- pandas 2.0+
- numpy 1.24+

Category 6: Runtime error (tiếp)

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

Fix

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

Hardcode Windows path:

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

Category 6: Runtime error (tiếp)

Fix

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

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

Fix

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
FILE_PATH = os.path.join(os.path.expanduser("~"), "file.txt")

Fix

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

Structural QC

Description QC

Functional QC

Sharing readiness QC

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

• ☐ 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")
• ☐ 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 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)
• ☐ 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?
• ☐ 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/

Advanced: --debug deep dive

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

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

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

Advanced: --debug deep dive (tiếp)

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

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

Advanced: --debug deep dive (tiếp)

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

[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

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:

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:

Fix:

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

# Trước
description: Reviews pull requests for quality.

# Sau
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.

Case 2: Linh (marketing) — wrong skill

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:

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

# social-writer
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.

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

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

Fix:

Error: command not found: match_transactions.py

Case studies — Lỗi thực tế & fix (tiếp)

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:

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

# Trong SKILL.md, đổi:
# run: match_transactions.py
# thành:
# run: python3 scripts/match_transactions.py

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

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".

mv ~/.claude/skills/code-review ~/.claude/skills/my-informal-review
# update name trong SKILL.md

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):

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

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

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

Ghi ra:

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:

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

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

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

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.

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

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

🎯 Validator first. uvx agent-skills-verifier check . trước khi debug sâu — catch 80% issue structural trong 30 giây.

🎯 6 category lỗi, mỗi cái có fix cụ thể. Không trigger → description. Không load → tên file/path. Wrong skill → distinct description. Conflict → rename. Plugin missing → cache. Runtime → dependency/permission.

🎯 claude --debug cho visibility vào loading + matching process. Đọc error message trước khi action.

🎯 QC checklist 10 điểm trước khi share team. Skill đã pass QC = skill share được không phá workflow.

🎯 Test với variation, không chỉ happy path. User thực tế nói đủ kiểu — skill phải robust.

Course wrap-up

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

Bạn đã học:

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

Đừ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.

➡️ Bài tiếp theo: Bài 15.7: Quiz tổng hợp & chứng nhận

• 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ố