Xây dựng Skills cho Claude — Phần 5: Patterns thực chiến và Xử lý lỗi

Dịch và biên soạn từ "The Complete Guide to Building Skills for Claude" của Anthropic.

Đây là phần thực chiến nhất của serial. Các patterns trong bài được đúc kết từ skill của early adopters và đội ngũ nội bộ Anthropic. Chúng là những cách tiếp cận đã chứng minh hiệu quả, không phải template cứng nhắc.

Chọn cách tiếp cận: Problem-first vs Tool-first

Anthropic dùng ẩn dụ Home Depot rất hay: Bạn có thể bước vào cửa hàng với một vấn đề -- "Tôi cần sửa tủ bếp" -- và nhân viên sẽ chỉ bạn đến đúng công cụ. Hoặc bạn chọn một máy khoan mới và hỏi cách dùng cho công việc cụ thể.

Skills hoạt động tương tự:

• Problem-first: "Tôi cần thiết lập workspace dự án" -- Skill điều phối đúng MCP calls theo đúng trình tự. Người dùng mô tả kết quả mong muốn; skill xử lý công cụ
• Tool-first: "Tôi đã kết nối Notion MCP" -- Skill dạy Claude quy trình tối ưu và best practices. Người dùng có quyền truy cập; skill cung cấp chuyên môn

Hầu hết skill nghiêng về một hướng. Biết rõ framing nào phù hợp giúp bạn chọn đúng pattern.

Pattern 1: Sequential Workflow Orchestration

Dùng khi: Người dùng cần quy trình nhiều bước theo thứ tự cố định.

Ví dụ: Onboard khách hàng mới

## Workflow: Onboard Khach Hang Moi

### Buoc 1: Tao Tai Khoan
Goi MCP tool: create_customer
Tham so: name, email, company

### Buoc 2: Thiet Lap Thanh Toan
Goi MCP tool: setup_payment_method
Cho: xac minh phuong thuc thanh toan

### Buoc 3: Tao Subscription
Goi MCP tool: create_subscription
Tham so: plan_id, customer_id (tu Buoc 1)

### Buoc 4: Gui Email Chao Mung
Goi MCP tool: send_email
Template: welcome_email_template

Kỹ thuật chính

• Thứ tự bước rõ ràng (explicit step ordering)
• Dependencies giữa các bước
• Validation tại mỗi giai đoạn
• Hướng dẫn rollback khi thất bại

Ví dụ Việt Nam: Skill onboarding khách hàng cho SaaS: tạo tài khoản, thiết lập thanh toán qua SePay/VNPay, gửi email chào mừng qua Mailchimp, tạo task onboarding trong Linear cho team Customer Success.

Pattern 2: Multi-MCP Coordination

Dùng khi: Quy trình trải qua nhiều dịch vụ khác nhau.

Ví dụ: Chuyển giao thiết kế sang phát triển

### Phase 1: Xuat Thiet Ke (Figma MCP)
1. Xuat design assets tu Figma
2. Tao design specifications
3. Tao asset manifest

### Phase 2: Luu Tru (Drive MCP)
1. Tao thu muc du an trong Drive
2. Upload tat ca assets
3. Tao shareable links

### Phase 3: Tao Tasks (Linear MCP)
1. Tao development tasks
2. Dinh kem asset links vao tasks
3. Assign cho doi engineering

### Phase 4: Thong Bao (Slack MCP)
1. Post tom tat handoff vao #engineering
2. Bao gom asset links va task references

Kỹ thuật chính

• Phân tách phase rõ ràng
• Truyền dữ liệu giữa các MCP
• Validation trước khi chuyển sang phase tiếp theo
• Xử lý lỗi tập trung

Pattern 3: Iterative Refinement

Dùng khi: Chất lượng output cải thiện qua nhiều vòng lặp.

Ví dụ: Tạo báo cáo

## Tao Bao Cao Lap

### Ban Nhap
1. Lay du lieu qua MCP
2. Tao ban nhap bao cao
3. Luu vao file tam

### Kiem Tra Chat Luong
1. Chay script kiem tra: scripts/check_report.py
2. Xac dinh van de:
   - Thieu sections
   - Dinh dang khong nhat quan
   - Loi validation du lieu

### Vong Lap Tinh Chinh
1. Xu ly tung van de da xac dinh
2. Tao lai cac sections bi anh huong
3. Kiem tra lai
4. Lap lai cho den khi dat nguong chat luong

### Hoan Thien
1. Ap dung dinh dang cuoi cung
2. Tao tom tat
3. Luu phien ban chinh thuc

Kỹ thuật chính

• Tiêu chí chất lượng rõ ràng
• Cải thiện qua nhiều vòng lặp
• Validation scripts
• Biết khi nào dừng iterate

Pattern 4: Context-Aware Tool Selection

Dùng khi: Cùng kết quả nhưng cần công cụ khác nhau tuỳ ngữ cảnh.

Ví dụ: Lưu trữ file thông minh

## Luu Tru File Thong Minh

### Cay Quyet Dinh
1. Kiem tra loai file va kich thuoc
2. Xac dinh vi tri luu tru tot nhat:
   - File lon (>10MB): Dung cloud storage MCP
   - Tai lieu cong tac: Dung Notion/Docs MCP
   - File code: Dung GitHub MCP
   - File tam: Dung local storage

### Thuc Thi Luu Tru
Dua tren quyet dinh:
- Goi MCP tool phu hop
- Ap dung metadata rieng cua dich vu
- Tao link truy cap

### Giai Thich Cho Nguoi Dung
Giai thich tai sao chon kieu luu tru do

Kỹ thuật chính

• Tiêu chí quyết định rõ ràng
• Có phương án dự phòng (fallback)
• Minh bạch về lựa chọn

Pattern 5: Domain-Specific Intelligence

Dùng khi: Skill cần kiến thức chuyên môn vượt xa khả năng truy cập công cụ.

Ví dụ: Xử lý thanh toán với tuân thủ pháp luật

## Xu Ly Thanh Toan Voi Compliance

### Truoc Khi Xu Ly (Kiem Tra Compliance)
1. Lay chi tiet giao dich qua MCP
2. Ap dung quy tac compliance:
   - Kiem tra danh sach cam van
   - Xac minh quyen tai phan cua thanh pham
   - Danh gia muc do rui ro
3. Ghi nhan quyet dinh compliance

### Xu Ly
NEU compliance dat:
  - Goi payment processing MCP tool
  - Ap dung kiem tra gian lan phu hop
  - Xu ly giao dich
NEU KHONG:
  - Danh dau de review
  - Tao compliance case

### Nhat Ky Kiem Toan
- Ghi log tat ca kiem tra compliance
- Ghi nhan quyet dinh xu ly
- Tao bao cao kiem toan

Kỹ thuật chính

• Kiến thức chuyên môn nhúng trong logic
• Compliance trước hành động
• Tài liệu toàn diện
• Quản trị rõ ràng

Ví dụ Việt Nam: Skill xử lý hoá đơn điện tử theo quy định của Tổng cục Thuế: kiểm tra format hoá đơn, validate mã số thuế, áp dụng quy tắc VAT theo từng loại hàng hoá, và tạo báo cáo thuế hàng quý.

Troubleshooting: Giải quyết lỗi phổ biến

Lỗi 1: Skill không upload được

Lỗi: "Could not find SKILL.md in uploaded folder"

Nguyên nhân: File không đặt tên đúng SKILL.md

Giải pháp:

• Đổi tên thành SKILL.md (phân biệt hoa thường)
• Kiểm tra bằng: ls -la phải thấy đúng SKILL.md

Lỗi: "Invalid frontmatter"

Nguyên nhân: Sai định dạng YAML

Các lỗi phổ biến:

# Sai - thieu delimiter
name: my-skill
description: Does things

# Sai - chua dong ngoac kep
name: my-skill
description: "Does things

# Dung
---
name: my-skill
description: Does things
---

Lỗi: "Invalid skill name"

Nguyên nhân: Tên có dấu cách hoặc viết hoa

# Sai
name: My Cool Skill

# Dung
name: my-cool-skill

Lỗi 2: Skill không kích hoạt (doesn't trigger)

Triệu chứng: Skill không bao giờ tự tải

Giải pháp: Chỉnh sửa trường description.

Checklist nhanh:

• Description có quá chung chung không? ("Helps with projects" sẽ không hoạt động)
• Có bao gồm trigger phrases mà người dùng thực sự nói không?
• Có đề cập loại file liên quan không (nếu áp dụng)?

Cách debug: Hỏi Claude: "Khi nào bạn sẽ dùng skill [tên skill]?" Claude sẽ trích dẫn description. Điều chỉnh dựa trên phần còn thiếu.

Lỗi 3: Skill kích hoạt quá nhiều (triggers too often)

Triệu chứng: Skill tải cho các truy vấn không liên quan

Giải pháp 1: Thêm negative triggers

description: Phan tich du lieu nang cao cho file CSV. Dung cho
mo hinh thong ke, hoi quy, phan cum. KHONG dung cho kham pha
du lieu don gian (dung skill data-viz thay the).

Giải pháp 2: Cụ thể hoá hơn

# Qua rong
description: Xu ly tai lieu

# Cu the hon
description: Xu ly tai lieu PDF phap ly de review hop dong

Giải pháp 3: Giới hạn phạm vi

description: Xu ly thanh toan PayFlow cho e-commerce. Dung cu the
cho quy trinh thanh toan truc tuyen, khong dung cho cac truy van
tai chinh chung.

Lỗi 4: Instructions không được tuân theo

Triệu chứng: Skill tải nhưng Claude không làm theo hướng dẫn

Nguyên nhân phổ biến và cách sửa:

1. Instructions quá dài: Giữ ngắn gọn, dùng bullet points và numbered lists, chuyển tài liệu chi tiết sang file riêng
2. Instructions bị chôn vùi: Đặt hướng dẫn quan trọng lên đầu, dùng header ## Important hoặc ## Critical, lặp lại điểm chính nếu cần
3. Ngôn ngữ mơ hồ:

# Te
Dam bao validate du lieu cho dung

# Tot
CRITICAL: Truoc khi goi create_project, kiem tra:
- Ten du an khong rong
- It nhat mot thanh vien duoc assign
- Ngay bat dau khong nam trong qua khu

Kỹ thuật nâng cao: Với các validation quan trọng, cân nhắc đóng gói script thực hiện kiểm tra bằng code thay vì dựa vào ngôn ngữ tự nhiên. Code là deterministic; diễn giải ngôn ngữ thì không.

Chống "lười biếng" của model: Thêm khuyến khích rõ ràng (hiệu quả hơn khi đặt trong prompt người dùng thay vì SKILL.md):

## Ghi Chu Hieu Suat
- Hay lam ky cang, khong voi
- Chat luong quan trong hon toc do
- Khong bo qua cac buoc validation

Lỗi 5: MCP connection issues

Triệu chứng: Skill tải nhưng MCP calls thất bại

Checklist:

1. Kiểm tra MCP server đã kết nối: Claude.ai Settings > Extensions > [Service] -- nên hiện "Connected"
2. Kiểm tra xác thực: API keys còn hạn, đúng permissions/scopes, OAuth tokens đã refresh
3. Test MCP độc lập (không qua skill): Hỏi Claude gọi MCP trực tiếp, ví dụ "Dùng [Service] MCP để lấy danh sách dự án". Nếu thất bại, vấn đề là MCP chứ không phải skill
4. Kiểm tra tên tool: Skill tham chiếu đúng tên MCP tool, tên tool phân biệt hoa thường

Lỗi 6: Large context issues

Triệu chứng: Skill chậm hoặc chất lượng phản hồi giảm

Nguyên nhân:

• Nội dung skill quá lớn
• Quá nhiều skill được bật đồng thời
• Tất cả nội dung được tải thay vì progressive disclosure

Giải pháp:

1. Tối ưu kích thước SKILL.md: Chuyển tài liệu chi tiết sang references/, liên kết thay vì inline, giữ SKILL.md dưới 5,000 từ
2. Giảm số skill bật: Đánh giá nếu bạn bật hơn 20-50 skill cùng lúc, khuyến nghị bật có chọn lọc, cân nhắc "skill packs" cho các khả năng liên quan

Tổng kết Phần 5

Bạn đã nắm được:

• Problem-first vs Tool-first: hai cách tiếp cận thiết kế skill
• 5 patterns: Sequential Workflow, Multi-MCP Coordination, Iterative Refinement, Context-Aware Tool Selection, Domain-Specific Intelligence
• 6 lỗi phổ biến và cách troubleshoot: upload thất bại, không trigger, trigger quá nhiều, instructions không được tuân theo, MCP issues, large context

Trong Phần 6 (phần cuối), chúng ta sẽ tổng hợp checklist hoàn chỉnh, tham chiếu YAML frontmatter đầy đủ, ví dụ skill hoàn chỉnh, và danh sách tài nguyên hữu ích.