Chia sẻ lại toàn bộ kiến thức về cách viết, nâng cấp, và audit Agent Skills cho Claude Code.
Tổng hợp từ The Complete Guide to Building Skills (Anthropic, 2026) kết hợp kinh nghiệm thực chiến vibe coding của mình.
Bài dài, nặng kỹ thuật. Nhưng nếu bạn đang dùng hoặc định dùng Claude Code, đây là thứ sẽ thay đổi hoàn toàn cách bạn làm việc với AI. Lưu lại đọc dần.

SKILL LÀ GÌ? TẠI SAO PHẢI VIẾT?

Hiểu đơn giản: skill là SOP cho AI.
Bạn viết SOP cho nhân viên để họ làm đúng quy trình mà không cần hỏi lại mỗi lần. Skill cũng vậy. Viết một lần, Claude tự đọc và làm đúng mỗi khi gặp tình huống phù hợp.
Mình hiện có skill cho: viết content Facebook, làm slide thuyết trình, phân tích tài chính, kiểm tra chính sách Meta Ads, build phần mềm, tạo poster, viết SOP, phân tích đối thủ… Mỗi skill là một “nhân viên ảo” biết đúng việc cần làm, theo đúng cách mình muốn.
Không có skill, mỗi lần bạn mở Claude Code là bắt đầu từ số 0. Có skill, nó biết việc phải làm.
⸻

CẤU TRÚC SKILL CHUẨN

Mỗi skill là 1 folder, bên trong chứa:
  • SKILL. md (bắt buộc): file chính, gồm YAML frontmatter + instructions
  • references/: tài liệu chi tiết, Claude chỉ đọc khi cần
  • scripts/: code chạy trực tiếp (Python stdlib only)
  • assets/: templates, fonts, images
Folder name viết kiểu kebab-case, ví dụ: facebook-content, vibe-coding-principles.
SKILL. md phải viết đúng case, viết sai là Claude không nhận.
⸻

YAML FRONTMATTER

Phần đầu file SKILL. md bắt buộc có 2 trường:
  • name: tên skill, kebab-case
  • description: mô tả dưới 1024 ký tự, viết cho Claude đọc (không phải cho người)
Optional thêm: license, compatibility, metadata (author, version, mcp-server), allowed-tools.
Lưu ý: tránh dùng dấu ngoặc nhọn < > trong description. Tên skill không được chứa “claude” hoặc “anthropic”.
Nghe thì nhỏ, nhưng sai mấy cái này là skill không load. Mình từng mất thời gian chỉnh sửa chỉ vì viết sai tên folder.
⸻

PROGRESSIVE DISCLOSURE 3 TẦNG

Đây là phần thiết kế hay nhất mà Anthropic làm. Claude không đọc hết tất cả cùng lúc. Nó đọc theo 3 tầng, giống kiểu bạn chỉ đưa nhân viên đọc cái cần đọc, không vứt cả tủ tài liệu lên bàn.
  • Tầng 1 (YAML frontmatter): khoảng 100 tokens/skill, luôn được load. Claude scan qua tất cả skill để quyết định cái nào liên quan đến yêu cầu hiện tại.
  • Tầng 2 (SKILL. md body): chỉ load khi Claude quyết định skill này cần được bật lên. Nên giữ dưới 500 dòng.
  • Tầng 3 (references/): zero tokens cho đến khi Claude tự quyết định cần đọc thêm chi tiết.

Tại sao phải thiết kế vậy? Vì context window có giới hạn. Nếu bạn nạp 130 skill mà cái nào cũng dài 1000 dòng, Claude sẽ không còn chỗ để suy nghĩ và làm việc. Thiết kế đúng 3 tầng = nhẹ mà vẫn thông minh.

⸻

5 PATTERNS HOẠT ĐỘNG

Mỗi skill hoạt động theo 1 trong 5 patterns:
  1. Sequential Workflow: các bước theo thứ tự cố định, bước sau phụ thuộc bước trước. Ví dụ: quy trình tạo slide (đọc brief → lên outline → viết copy → render HTML)
  2. Multi-MCP Coordination: phối hợp nhiều tools/services cùng lúc, chia thành phases. Ví dụ: skill kết nối Google Calendar + Gmail + Notion trong 1 flow
  3. Iterative Refinement: tạo draft → quality check → fix → lặp lại cho đến khi đạt. Ví dụ: viết content, review, sửa, review lại
  4. Context-Aware Tool Selection: cùng một mục tiêu nhưng chọn tool khác nhau tùy context. Ví dụ: cùng tạo slide nhưng tùy yêu cầu mà dùng HTML, PPTX, hay Canva
  5. Domain-Specific Intelligence: nhúng chuyên môn sâu vào, có compliance check trước khi hành động. Ví dụ: skill kiểm tra chính sách Facebook, skill tính lương theo luật Việt Nam
⸻

9 LOẠI SKILL

Anthropic phân loại rõ ràng:
  1. Library & API Reference
  2. Product Verification
  3. Code Scaffolding & Templates
  4. Business Process Automation
  5. Data Fetching & Analysis
  6. Code Quality & Review
  7. CI/CD & Deployment
  8. Runbooks
  9. Infrastructure Operations
Nguyên tắc quan trọng: mỗi skill chỉ nên thuộc 1 loại. Nếu đang lan sang nhiều loại, tách ra. Skill ôm đồm = skill không ai dùng.
Với anh em không biết code như mình, nhóm hay dùng nhất là Business Process Automation và Code Scaffolding & Templates. Đừng nghĩ skill chỉ dành cho developer.
⸻

DESCRIPTION = ĐIỀU KIỆN ĐỂ CLAUDE NHẬN DIỆN

Đây là phần quyết định thành bại của skill. Description không phải viết cho người đọc hiểu. Nó viết cho Claude đọc để quyết định có bật skill lên hay không.
Và cách viết ảnh hưởng trực tiếp:
  • Description chung chung: tỉ lệ được gọi ~20%
  • Có trigger phrases: ~50%
  • Có trigger phrases + ví dụ tình huống: 72-90%
20% vs 82%. Cái khác biệt chỉ nằm ở cách bạn mô tả.
Checklist description tốt:
  • 5+ trigger phrases (cả tiếng Việt lẫn tiếng Anh)
  • Mô tả TÌNH HUỐNG (“khi user muốn…”), không mô tả skill (“skill này dùng để…”)
  • Dùng cụm “BAT CU KHI NAO” để tăng activation
  • Thêm ví dụ câu user có thể nói
  • Dưới 1024 characters
  • Không dấu tiếng Việt (vì YAML encoding)
Mình thấy đây là phần nhiều người bỏ qua nhất. Viết skill rất kỹ nhưng description thì viết cho có. Kết quả là Claude không bao giờ tự nhận diện, phải gọi tay mỗi lần.
⸻

NGUYÊN TẮC VIẾT SKILL

5 nguyên tắc mà mình thấy đúng cả khi áp dụng cho việc viết SOP cho người thật:
  1. Không dạy Claude cái nó đã biết. Bạn không giải thích “thế nào là marketing” cho nhân viên marketing. Tập trung vào context riêng, gotchas riêng, quy trình riêng của tổ chức bạn.
  2. Gotchas là phần giá trị nhất. Những lỗi ngầm, lỗi lặp đi lặp lại mà chỉ người trong cuộc mới biết. Cập nhật liên tục theo thời gian. Mỗi lần Claude làm sai = 1 gotcha mới.
  3. Code hơn ngôn ngữ cho validation. Nếu có thể viết script để kiểm tra output thì viết script. Deterministic hơn chỉ dẫn bằng lời rất nhiều.
  4. Đừng railroading Claude. Cho thông tin cần thiết, nhưng để nó linh hoạt trong cách thực thi. Quản lý quá chi tiết thì output sẽ máy móc.
  5. Rewrite full, không patch. Sửa chắp vá từng chỗ sẽ gây mâu thuẫn nội bộ trong skill. Khi cần upgrade, viết lại toàn bộ luôn.
⸻

QUY TRÌNH NÂNG CẤP SKILL

Skill không phải viết 1 lần rồi xong. Nó cần được nâng cấp liên tục. Quy trình:
  • Ghi gotcha/vấn đề vào backlog mỗi khi phát hiện
  • Tích đủ 3-5 gotchas mới thì chạy upgrade
  • Đọc toàn bộ skill + references, đánh giá theo checklist 13 tiêu chí
  • Xác định vấn đề cụ thể: under-trigger (không nhận diện khi cần), over-trigger (nhận diện khi không cần), hay lỗi khi chạy (nhận diện đúng nhưng làm sai)
  • Rewrite toàn bộ, giữ nguyên tên
  • Test: tối thiểu 3 trường hợp nên trigger + 3 trường hợp không nên trigger
  • Package lại, thay thế bản cũ
Đừng nghĩ “skill đang chạy tốt thì không cần sửa”. Mình review lại skill cũ thường xuyên và gần như lần nào cũng tìm ra chỗ cải thiện.
⸻
Nguồn:
The Complete Guide to Building Skills for Claude (Anthropic, 2026)
Anthropic Engineering Blog: Equipping Agents for the Real World
Bài này mình tổng hợp cho bản thân dùng, thấy hay nên chia sẻ. Ai đang dùng Claude Code mà chưa viết skill, thử bắt đầu từ 1 cái cho công việc lặp lại nhiều nhất.