Hướng dẫn toàn diện xây skill

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Bài này tóm tắt lại các ý chính từ “The Complete Guide to Building Skills for Claude” - tài liệu hướng dẫn (dạng PDF, 33 trang) của Anthropic dành cho người xây skill. Nếu trang Mở rộng Claude bằng skill nói về cách skill hoạt động trong Claude Code, thì tài liệu gốc đi sâu hơn vào quy trình thiết kế, test, và phân phối một skill tốt - dành cho cả người xây skill độc lập lẫn người đang nâng cấp một tích hợp MCP có sẵn bằng skill.

Ý tưởng cốt lõi

Skill là cách mạnh nhất để tuỳ biến Claude cho quy trình lặp lại - dạy một lần, dùng mãi. Tài liệu dùng ẩn dụ nhà bếp: MCP cho Claude quyền truy cập vào “bếp chuyên nghiệp” (tool, dữ liệu, dịch vụ ngoài); skill là “công thức nấu ăn” - chỉ dẫn từng bước để biến quyền truy cập đó thành kết quả có giá trị. MCP quyết định Claude làm được gì; skill quyết định Claude nên làm như thế nào.

Không có skill đi kèm, người dùng MCP của bạn thường không biết bước tiếp theo, mỗi hội thoại phải giải thích lại từ đầu, và kết quả không nhất quán giữa các lần dùng. Có skill, quy trình dựng sẵn tự kích hoạt đúng lúc và nhúng sẵn thực hành tốt nhất vào mỗi lần tương tác.

Về mặt kỹ thuật, một skill là một thư mục kebab-case chứa SKILL.md (bắt buộc - Markdown kèm YAML frontmatter), cộng thêm scripts/, references/, assets/ tuỳ chọn. Cơ chế progressive disclosure ba tầng - frontmatter luôn nạp, thân bài nạp khi liên quan, file liên kết chỉ nạp khi cần - giữ cho việc dùng skill tiết kiệm token dù chứa kiến thức chuyên sâu.

Lên kế hoạch

Trước khi viết code, tài liệu khuyên xác định 2-3 use case cụ thể: người dùng muốn đạt gì, cần quy trình nhiều bước nào, cần tool gì (có sẵn hay qua MCP), và cần nhúng kiến thức chuyên môn nào. Ba nhóm use case phổ biến Anthropic quan sát được:

Tạo tài liệu & asset - sinh ra output nhất quán, chất lượng cao (tài liệu, slide, code, thiết kế…), không cần tool ngoài.
Tự động hoá quy trình - các bước nhiều giai đoạn có lợi từ một phương pháp nhất quán, có thể điều phối nhiều MCP server.
Nâng cấp MCP - thêm kiến thức chuyên môn và trình tự gọi tool hợp lý lên trên một MCP server đã có.

Tiêu chí thành công nên gồm cả định lượng (skill kích hoạt đúng trên phần lớn truy vấn liên quan, hoàn thành quy trình trong số lệnh gọi tool hợp lý, ít lỗi API) lẫn định tính (người dùng không cần hướng dẫn thêm, kết quả nhất quán qua nhiều lần chạy) - đây là các mục tiêu mang tính định hướng, không phải ngưỡng chính xác.

Viết SKILL.md

Phần quan trọng nhất là YAML frontmatter, vì đó là thứ Claude dùng để quyết định có nạp skill hay không. Hai field bắt buộc:

name: kebab-case, khớp tên thư mục.
description: phải nêu cả skill làm gì và khi nào nên dùng (kèm cụm từ kích hoạt cụ thể) - đây là lỗi phổ biến nhất khi viết skill. Mô tả chung chung như “Helps with projects” sẽ không bao giờ kích hoạt đúng lúc.

Field tuỳ chọn gồm license, compatibility, allowed-tools (giới hạn tool khi skill hoạt động), và metadata tự do. Vì frontmatter nằm trong system prompt của Claude, dấu ngoặc nhọn XML (< >) bị cấm để chặn chèn chỉ dẫn giả mạo, và tên skill không được dùng tiền tố “claude”/“anthropic”.

Phần thân SKILL.md nên cụ thể và có thể hành động (nêu đúng lệnh cần chạy, kết quả mong đợi là gì), có xử lý lỗi cho các tình huống thường gặp, và dùng progressive disclosure - giữ SKILL.md gọn, đẩy tài liệu chi tiết sang references/ rồi liên kết tới.

Test và lặp lại

Skill test được ở ba mức: thủ công trong Claude.ai (nhanh, không cần setup), bằng script trong Claude Code (tự động hoá, lặp lại được), hoặc có lập trình qua skills API (bộ đánh giá quy mô). Tài liệu khuyên tập trung test vào ba mảng: kích hoạt (skill có nạp đúng lúc, đúng chỗ, không nạp nhầm chủ đề khác), chức năng (output đúng, xử lý lỗi hoạt động), và so sánh hiệu năng (có/không skill, đo số lệnh gọi tool và token tiêu thụ).

Mẹo quan trọng nhất: lặp trên một tác vụ khó cho tới khi Claude làm đúng, rồi mới chiết xuất thành skill và mở rộng test case - thay vì viết skill trước rồi test dàn trải ngay từ đầu.

Skill skill-creator (có sẵn trên Claude.ai và Claude Code) hỗ trợ toàn bộ vòng đời này: sinh SKILL.md từ mô tả ngôn ngữ tự nhiên, review và gắn cờ vấn đề thường gặp (description mơ hồ, thiếu trigger), và giúp tinh chỉnh dựa trên trường hợp biên bạn gặp phải khi dùng thực tế. Lưu ý nó hỗ trợ thiết kế, không tự chạy test tự động.

Phân phối

Cách phổ biến nhất hiện nay (tính đến tháng 1/2026): host skill trên một GitHub repo công khai kèm README rõ ràng (README này nằm ở cấp repo, không đặt trong thư mục skill), rồi liên kết từ tài liệu MCP của bạn sang skill kèm hướng dẫn cài nhanh. Người dùng tự tải/giải nén rồi upload qua Claude.ai (Settings > Capabilities > Skills) hoặc đặt vào thư mục skill của Claude Code. Ở cấp tổ chức, admin có thể triển khai skill cho toàn workspace.

Anthropic đã công bố Agent Skills như một chuẩn mở, tương tự tinh thần của MCP - một skill viết ra nên chạy được trên nhiều nền tảng AI, dù một số skill có thể tối ưu riêng cho một nền tảng cụ thể (ghi chú qua field compatibility).

Với use case lập trình (ứng dụng, agent, pipeline tự động), có một REST API riêng để liệt kê/quản lý skill và đưa skill vào Messages API request, hoạt động cùng Claude Agent SDK - yêu cầu Code Execution Tool (beta). Quy tắc chung: end-user tương tác trực tiếp và test thủ công thì dùng Claude.ai/Claude Code; ứng dụng lập trình và triển khai production ở quy mô thì dùng API.

Khi viết tài liệu giới thiệu skill, tài liệu khuyên tập trung vào kết quả (“giúp team dựng xong workspace project trong vài giây thay vì 30 phút thao tác tay”) thay vì mô tả kỹ thuật thuần tuý (“một thư mục chứa YAML frontmatter gọi tool MCP”).

Các pattern thường gặp

Tài liệu mô tả năm pattern đúc kết từ skill do người dùng sớm và các đội nội bộ tạo ra:

Điều phối quy trình tuần tự - các bước có thứ tự và phụ thuộc rõ ràng (vd. onboarding khách hàng mới: tạo tài khoản → thiết lập thanh toán → tạo subscription → gửi email).
Điều phối nhiều MCP - quy trình trải dài qua nhiều dịch vụ, tách rõ từng giai đoạn và validate trước khi sang giai đoạn kế (vd. bàn giao thiết kế: Figma → Drive → Linear → Slack).
Tinh chỉnh lặp lại - chất lượng output cải thiện qua nhiều vòng, cần tiêu chí dừng rõ ràng (vd. sinh báo cáo: nháp → kiểm tra chất lượng → vòng lặp sửa lỗi → hoàn thiện).
Chọn tool theo ngữ cảnh - cùng mục tiêu nhưng chọn công cụ khác nhau tuỳ điều kiện, kèm giải thích minh bạch cho người dùng vì sao chọn vậy.
Kiến thức chuyên biệt theo lĩnh vực - skill nhúng sẵn chuyên môn (vd. quy tắc tuân thủ tài chính) chứ không chỉ đơn thuần gọi tool.

Khi chọn hướng thiết kế, tài liệu gợi ý phân biệt hai kiểu: problem-first (người dùng mô tả kết quả mong muốn, skill tự điều phối tool cần thiết) và tool-first (người dùng đã có sẵn quyền truy cập, skill dạy quy trình và thực hành tốt nhất để dùng nó hiệu quả).

Xử lý sự cố thường gặp

Phần cuối tài liệu là một mục lớn về debug, tóm gọn theo từng nhóm triệu chứng:

Không upload được - hầu hết do đặt sai tên SKILL.md (phải viết hoa chính xác như vậy) hoặc lỗi cú pháp YAML (thiếu dấu ---, quote chưa đóng).
Không kích hoạt - gần như luôn nằm ở description quá chung chung hoặc thiếu cụm từ kích hoạt khớp cách người dùng thực sự nói. Cách debug: hỏi thẳng Claude “khi nào bạn sẽ dùng skill này?” và xem nó trích lại description thiếu gì.
Kích hoạt quá thường xuyên - thêm trigger phủ định vào description, thu hẹp phạm vi cụ thể hơn.
Kết nối MCP lỗi - checklist: xác nhận MCP server đã connect, xác thực API key/token còn hiệu lực, test gọi MCP trực tiếp (không qua skill) để cô lập vấn đề, và xác minh tên tool đúng chính tả.
Chỉ dẫn không được tuân theo - thường do instructions quá dài dòng, bị chôn vùi giữa văn bản, hoặc dùng ngôn ngữ mơ hồ thay vì yêu cầu tường minh. Với các bước kiểm chứng quan trọng, tài liệu khuyên đóng gói thành script thay vì chỉ dặn bằng lời - code thì tất định, diễn giải ngôn ngữ thì không.
Ngữ cảnh phình to - do SKILL.md quá dài hoặc bật quá nhiều skill cùng lúc; khắc phục bằng cách đẩy tài liệu chi tiết ra references/ và chỉ bật những skill thực sự cần.

Checklist nhanh trước khi publish

Rút gọn từ phụ lục A của tài liệu gốc:

Đã xác định rõ 2-3 use case và tool cần dùng.
Thư mục kebab-case, có đúng file SKILL.md.
Frontmatter hợp lệ, description có cả “làm gì” và “khi nào dùng”, không chứa < >.
Đã test kích hoạt trên cả câu rõ ràng lẫn diễn đạt lại, và xác nhận không kích hoạt nhầm chủ đề khác.
Đã test chức năng, có xử lý lỗi và ví dụ minh hoạ.
Sau khi publish: theo dõi tín hiệu kích hoạt thiếu/quá mức, thu thập phản hồi người dùng thực tế, và tiếp tục lặp lại description/chỉ dẫn - skill là tài liệu sống, không phải thứ viết một lần rồi xong.

Tài nguyên đầy đủ

Toàn văn tài liệu gốc có ví dụ code chi tiết cho từng pattern, mẫu YAML frontmatter đầy đủ (phụ lục B), và link tới các repo skill mẫu sẵn sàng dùng - bao gồm skill xử lý PDF/DOCX/PPTX/XLSX, một bộ ví dụ quy trình đa dạng, và một danh mục skill từ các đối tác như Asana, Atlassian, Canva, Figma, Sentry, Zapier (phụ lục C). Skill skill-creator (gõ /plugin trên Claude.ai hoặc tải cho Claude Code) là công cụ nhanh nhất để bắt đầu - nó có thể sinh và review skill giúp bạn ngay trong hội thoại.

Xem thêm trên site này: Mở rộng Claude bằng skill · MCP · Introduction to agent skills (khóa học đầy đủ, 6 bài).

Phuc Tran

Software Engineer | Learning Claude