Giới thiệu

Skill là một tập hợp hướng dẫn - được đóng gói dưới dạng một folder đơn giản - giúp dạy Claude cách xử lý các tác vụ hoặc workflow (quy trình) cụ thể. Skill là một trong những cách mạnh mẽ nhất để tùy chỉnh Claude theo nhu cầu riêng của bạn. Thay vì phải giải thích lại sở thích, quy trình và kiến thức chuyên môn trong mỗi cuộc hội thoại, skill cho phép bạn dạy Claude một lần và hưởng lợi mãi mãi.

Skill đặc biệt mạnh khi bạn có các workflow (quy trình) lặp lại: tạo thiết kế frontend từ spec, nghiên cứu với phương pháp nhất quán, tạo tài liệu theo style guide của team, hoặc điều phối các quy trình nhiều bước. Chúng hoạt động tốt với các khả năng tích hợp sẵn của Claude như thực thi code và tạo tài liệu. Với những ai đang xây dựng MCP Integration (tích hợp MCP), skill bổ sung thêm một lớp mạnh mẽ - biến quyền truy cập tool thô thành các workflow đáng tin cậy, được tối ưu hóa.

Hướng dẫn này bao gồm mọi thứ bạn cần biết để xây dựng skill hiệu quả - từ lập kế hoạch và cấu trúc đến kiểm thử và phân phối. Dù bạn đang xây skill cho bản thân, cho team hay cho cộng đồng, bạn sẽ tìm thấy các pattern thực tế và ví dụ thực tế xuyên suốt.

Bạn sẽ học được gì:

• Yêu cầu kỹ thuật và best practice (thực hành tốt nhất) cho cấu trúc skill
• Các pattern cho standalone skill (skill độc lập) và MCP-enhanced workflow (quy trình nâng cao bằng MCP)
• Các pattern đã được chứng minh hiệu quả trên nhiều use case (trường hợp sử dụng) khác nhau
• Cách kiểm thử, cải tiến và phân phối skill

Đối tượng phù hợp:

• Developer muốn Claude tuân theo các workflow cụ thể một cách nhất quán
• Power user (người dùng nâng cao) muốn Claude tuân theo các workflow cụ thể
• Team muốn chuẩn hóa cách Claude hoạt động trong tổ chức

Hai lộ trình qua hướng dẫn này

• Xây dựng standalone skill (skill độc lập)? Tập trung vào Fundamentals (Nền tảng), Planning and Design (Lập kế hoạch & Thiết kế) và Category (danh mục) 1-2.
• Nâng cấp MCP Integration? Phần "Skills + MCP" và Category 3 dành cho bạn.

Cả hai lộ trình đều chia sẻ cùng yêu cầu kỹ thuật, nhưng bạn chọn phần phù hợp với use case của mình.

Kết quả bạn đạt được: Cuối hướng dẫn, bạn sẽ có thể xây dựng một skill hoàn chỉnh trong một lần ngồi. Dự kiến khoảng 15-30 phút để xây và test skill đầu tiên bằng skill-creator.

Bắt đầu thôi!

Chương 1: Nền tảng cơ bản (Fundamentals)

Skill là gì?

Một skill là một folder chứa:

• SKILL.md (bắt buộc): Hướng dẫn dạng Markdown với YAML Frontmatter
• scripts/ (tùy chọn): Code thực thi (Python, Bash, v.v.)
• references/ (tùy chọn): Tài liệu tham khảo, được tải khi cần
• assets/ (tùy chọn): Template (mẫu), font, icon dùng cho output

Nguyên tắc thiết kế cốt lõi (Core Design Principles)

Progressive Disclosure (Tiết lộ dần dần)

Skill sử dụng hệ thống ba tầng:

• Tầng 1 (YAML Frontmatter): Luôn được tải vào system prompt của Claude. Cung cấp vừa đủ thông tin để Claude biết khi nào nên sử dụng skill mà không cần tải toàn bộ nội dung.
• Tầng 2 (Phần thân SKILL.md): Được tải khi Claude cho rằng skill phù hợp với tác vụ hiện tại. Chứa toàn bộ hướng dẫn chi tiết.
• Tầng 3 (File liên kết): Các file bổ sung trong thư mục skill mà Claude có thể chủ động khám phá khi cần.

Cơ chế progressive disclosure này giảm thiểu token usage (lượng token sử dụng) trong khi vẫn duy trì chuyên môn chuyên sâu.

Composability (Khả năng kết hợp)

Claude có thể tải nhiều skill cùng lúc. Skill của bạn nên hoạt động tốt cùng với các skill khác, không nên giả định nó là khả năng duy nhất có sẵn.

Portability (Tính di động)

Skill hoạt động giống nhau trên Claude.ai, Claude Code và API. Tạo skill một lần và nó hoạt động trên tất cả các nền tảng mà không cần chỉnh sửa, miễn là môi trường hỗ trợ các dependency (phụ thuộc) mà skill yêu cầu.

Dành cho MCP Builder: Skills + Connectors

💡 Đang xây standalone skill (skill độc lập) mà không dùng MCP? Bỏ qua phần này và chuyển đến Planning and Design - bạn luôn có thể quay lại sau.

Nếu bạn đã có MCP Server hoạt động, bạn đã làm xong phần khó nhất. Skill là lớp kiến thức phía trên - nắm bắt các workflow và best practice bạn đã biết, để Claude có thể áp dụng chúng một cách nhất quán.

Phép so sánh nhà bếp (The Kitchen Analogy)

• MCP cung cấp nhà bếp chuyên nghiệp: quyền truy cập vào tool, nguyên liệu và thiết bị.
• Skill cung cấp công thức nấu ăn: hướng dẫn từng bước cách tạo ra thứ gì đó có giá trị.

Kết hợp lại, chúng cho phép người dùng hoàn thành các tác vụ phức tạp mà không cần tự tìm hiểu từng bước.

Cách chúng hoạt động cùng nhau:

Tại sao điều này quan trọng cho người dùng MCP của bạn

Không có skill: - Người dùng kết nối MCP nhưng không biết làm gì tiếp - Ticket hỗ trợ hỏi "làm sao dùng X với integration của bạn" - Mỗi cuộc hội thoại bắt đầu từ đầu - Kết quả không nhất quán vì mỗi người prompt khác nhau - Người dùng đổ lỗi cho connector trong khi vấn đề thật sự là thiếu hướng dẫn workflow

Có skill: - Workflow dựng sẵn tự động kích hoạt khi cần - Sử dụng tool nhất quán, đáng tin cậy - Best practice được nhúng trong mọi tương tác - Đường cong học tập thấp hơn cho integration của bạn

Chương 2: Lập kế hoạch và thiết kế (Planning and Design)

Bắt đầu với Use Case (trường hợp sử dụng)

Trước khi viết bất kỳ dòng code nào, hãy xác định 2-3 use case cụ thể mà skill của bạn cần hỗ trợ.

Ví dụ định nghĩa use case tốt:

Use Case: Lập kế hoạch Sprint dự án
Trigger: Người dùng nói "giúp tôi lập kế hoạch sprint" hoặc "tạo task sprint"
Các bước:
1. Lấy trạng thái dự án hiện tại từ Linear (qua MCP)
2. Phân tích velocity (tốc độ) và capacity (năng lực) của team
3. Đề xuất ưu tiên task
4. Tạo task trong Linear với label và estimate phù hợp
Kết quả: Sprint được lên kế hoạch đầy đủ với các task đã tạo

Hãy tự hỏi: - Người dùng muốn hoàn thành điều gì? - Workflow nhiều bước nào cần thiết? - Cần tool nào (tích hợp sẵn hay MCP)? - Kiến thức chuyên môn hoặc best practice nào cần được nhúng?

Các danh mục Use Case phổ biến

Tại Anthropic, họ đã quan sát ba danh mục phổ biến:

Category 1: Document & Asset Creation (Tạo tài liệu & tài sản)

Dùng cho: Tạo output chất lượng cao, nhất quán bao gồm tài liệu, bài thuyết trình, ứng dụng, thiết kế, code, v.v.

Ví dụ thực tế: skill frontend-design (cũng xem skill cho docx, pptx, xlsx, và ppt)

"Tạo giao diện frontend production-grade (cấp sản xuất) đặc sắc với chất lượng thiết kế cao. Sử dụng khi xây dựng web component, page, artifact, poster hoặc ứng dụng."

Kỹ thuật chính: - Style guide và brand standard (tiêu chuẩn thương hiệu) được nhúng - Cấu trúc template cho output nhất quán - Checklist chất lượng trước khi hoàn thiện - Không cần tool bên ngoài - sử dụng khả năng tích hợp sẵn của Claude

Category 2: Workflow Automation (Tự động hóa quy trình)

Dùng cho: Quy trình nhiều bước hưởng lợi từ phương pháp nhất quán, bao gồm phối hợp giữa nhiều MCP Server.

Ví dụ thực tế: skill skill-creator

"Hướng dẫn tương tác để tạo skill mới. Dẫn dắt người dùng qua định nghĩa use case, tạo frontmatter, viết hướng dẫn và xác nhận."

Kỹ thuật chính: - Workflow từng bước với validation gate (cổng xác nhận) - Template cho các cấu trúc phổ biến - Đề xuất review và cải thiện tích hợp sẵn - Vòng lặp tinh chỉnh lặp đi lặp lại

Category 3: MCP Enhancement (Nâng cấp MCP)

Dùng cho: Hướng dẫn workflow để nâng cao quyền truy cập tool mà MCP Server cung cấp.

Ví dụ thực tế: skill sentry-code-review (từ Sentry)

"Tự động phân tích và sửa bug được phát hiện trong GitHub Pull Request bằng dữ liệu giám sát lỗi của Sentry qua MCP Server."

Kỹ thuật chính: - Phối hợp nhiều lệnh gọi MCP theo tuần tự - Nhúng chuyên môn lĩnh vực - Cung cấp context (ngữ cảnh) mà người dùng thường phải tự chỉ định - Xử lý lỗi cho các vấn đề MCP phổ biến

Định nghĩa tiêu chí thành công (Success Criteria)

Làm sao biết skill đang hoạt động tốt?

Đây là các mục tiêu tham khảo - benchmark (chuẩn so sánh) ước tính hơn là ngưỡng chính xác. Hãy hướng tới sự nghiêm ngặt nhưng chấp nhận rằng sẽ có yếu tố đánh giá dựa trên cảm nhận.

Metric định lượng (Quantitative):

• Skill trigger (kích hoạt) đúng 90% các truy vấn liên quan
• Cách đo: Chạy 10-20 test query cần trigger skill. Theo dõi số lần nó tự tải vs. cần gọi thủ công.
• Hoàn thành workflow trong X tool call
• Cách đo: So sánh cùng một tác vụ có và không có skill. Đếm số tool call và tổng token tiêu thụ.
• 0 API call thất bại mỗi workflow
• Cách đo: Giám sát log MCP Server trong các lần chạy test. Theo dõi tỷ lệ retry và error code.

Metric định tính (Qualitative):

• Người dùng không cần prompt Claude về bước tiếp theo
• Cách đánh giá: Trong quá trình test, ghi chú số lần cần redirect hoặc làm rõ. Hỏi beta user feedback.
• Workflow hoàn thành mà không cần người dùng sửa
• Cách đánh giá: Chạy cùng một request 3-5 lần. So sánh output về tính nhất quán cấu trúc và chất lượng.
• Kết quả nhất quán giữa các session (phiên)
• Cách đánh giá: Người dùng mới có thể hoàn thành tác vụ ngay lần đầu với hướng dẫn tối thiểu không?

Yêu cầu kỹ thuật (Technical Requirements)

Cấu trúc file

your-skill-name/
├── SKILL.md              # Bắt buộc - file skill chính
├── scripts/              # Tùy chọn - code thực thi
│   ├── process_data.py   # Ví dụ
│   └── validate.sh       # Ví dụ
├── references/           # Tùy chọn - tài liệu
│   ├── api-guide.md      # Ví dụ
│   └── examples/         # Ví dụ
└── assets/               # Tùy chọn - template, v.v.
    └── report-template.md # Ví dụ

Quy tắc quan trọng (Critical Rules)

Đặt tên SKILL.md: - Phải đúng chính xác SKILL.md (phân biệt hoa thường / case-sensitive) - Không chấp nhận biến thể (SKILL.MD, skill.md, v.v.)

Đặt tên folder skill: - Dùng kebab-case: notion-project-setup ✅ - Không dùng dấu cách: Notion Project Setup ❌ - Không dùng gạch dưới: notion_project_setup ❌ - Không viết hoa: NotionProjectSetup ❌

Không dùng README.md: - Không đặt README.md bên trong folder skill - Tất cả tài liệu vào SKILL.md hoặc references/ - Lưu ý: khi phân phối qua GitHub, bạn vẫn cần README cấp repo cho người dùng - xem phần Distribution and Sharing.

YAML Frontmatter: Phần quan trọng nhất

YAML Frontmatter là cách Claude quyết định có nên tải skill hay không. Hãy làm đúng phần này.

Format tối thiểu bắt buộc:

---
name: your-skill-name
description: Nó làm gì. Sử dụng khi người dùng yêu cầu [cụm từ cụ thể].
---

Đó là tất cả những gì bạn cần để bắt đầu.

Yêu cầu các field:

• name (bắt buộc):
• Chỉ kebab-case
• Không dấu cách hay chữ hoa

• Nên trùng tên folder

• description (bắt buộc):

• PHẢI bao gồm CẢ HAI: skill làm gì + khi nào dùng (trigger condition)
• Dưới 1024 ký tự
• Không dùng XML tag (< hoặc >)
• Bao gồm các tác vụ cụ thể người dùng có thể nói

• Đề cập loại file nếu liên quan

• license (tùy chọn): Dùng nếu open source. Phổ biến: MIT, Apache-2.0

• compatibility (tùy chọn): 1-500 ký tự. Chỉ ra yêu cầu môi trường.

• metadata (tùy chọn): Bất kỳ cặp key-value tùy chỉnh. Đề xuất: author, version, mcp-server.

metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub

Hạn chế bảo mật (Security Restrictions)

Cấm trong frontmatter: - Dấu ngoặc nhọn XML (< >) - Skill có tên chứa "claude" hoặc "anthropic" (đã được đặt trước / reserved)

Lý do: Frontmatter xuất hiện trong system prompt của Claude. Nội dung độc hại có thể inject (tiêm) hướng dẫn.

Viết Skill hiệu quả

Field description

Theo blog kỹ thuật của Anthropic: "Metadata này... cung cấp vừa đủ thông tin để Claude biết khi nào nên sử dụng mỗi skill mà không cần tải toàn bộ vào context." Đây là tầng đầu tiên của progressive disclosure.

Cấu trúc: [Nó làm gì] + [Khi nào dùng] + [Khả năng chính]

Ví dụ description tốt:

# Tốt - cụ thể và actionable (có thể hành động)
description: Phân tích file thiết kế Figma và tạo tài liệu handoff
  cho developer. Sử dụng khi người dùng upload file .fig, yêu cầu
  "design specs", "component documentation", hoặc "design-to-code handoff".

# Tốt - có trigger phrase (cụm từ kích hoạt)
description: Quản lý workflow dự án Linear bao gồm sprint planning,
  tạo task và theo dõi trạng thái. Sử dụng khi người dùng nhắc đến
  "sprint", "Linear tasks", "project planning", hoặc yêu cầu "create tickets".

# Tốt - value proposition (giá trị đề xuất) rõ ràng
description: Workflow onboard khách hàng end-to-end cho PayFlow.
  Xử lý tạo tài khoản, thiết lập thanh toán và quản lý subscription.
  Sử dụng khi người dùng nói "onboard new customer", "set up subscription",
  hoặc "create PayFlow account".

Ví dụ description xấu:

# Quá mơ hồ
description: Giúp với dự án.

# Thiếu trigger
description: Tạo hệ thống tài liệu nhiều trang phức tạp.

# Quá kỹ thuật, không có user trigger
description: Triển khai Project entity model với quan hệ phân cấp.

Viết hướng dẫn chính (Main Instructions)

Sau frontmatter, viết hướng dẫn thực tế bằng Markdown.

Cấu trúc khuyến nghị (điều chỉnh template này cho skill của bạn):

---
name: your-skill
description: [...]
---

# Tên Skill Của Bạn

## Instructions (Hướng dẫn)

### Step 1: [Bước chính đầu tiên]
Giải thích rõ ràng điều gì xảy ra.

Ví dụ:
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [mô tả kết quả thành công như thế nào]

(Thêm các bước nếu cần)

## Examples (Ví dụ)

### Ví dụ 1: [kịch bản phổ biến]
Người dùng nói: "Thiết lập campaign marketing mới"
Hành động:
1. Lấy campaign hiện có qua MCP
2. Tạo campaign mới với tham số đã cung cấp
Kết quả: Campaign được tạo với link xác nhận

(Thêm ví dụ nếu cần)

## Troubleshooting (Xử lý sự cố)

Error: [Thông báo lỗi phổ biến]
Nguyên nhân: [Tại sao xảy ra]
Giải pháp: [Cách sửa]

(Thêm trường hợp lỗi nếu cần)

Best Practice cho hướng dẫn

Cụ thể và actionable (có thể hành động):

✅ Tốt:

Chạy `python scripts/validate.py --input {filename}` để kiểm tra format dữ liệu.
Nếu validation thất bại, các vấn đề phổ biến bao gồm:
- Thiếu required field (thêm vào CSV)
- Format ngày không hợp lệ (dùng YYYY-MM-DD)

❌ Xấu:

Xác nhận dữ liệu trước khi tiếp tục.

Bao gồm xử lý lỗi (Error Handling):

## Common Issues (Vấn đề phổ biến)

### MCP Connection Failed (Kết nối MCP thất bại)
Nếu thấy "Connection refused":
1. Xác nhận MCP server đang chạy: Kiểm tra Settings > Extensions
2. Xác nhận API key hợp lệ
3. Thử kết nối lại: Settings > Extensions > [Service] > Reconnect

Tham chiếu tài nguyên rõ ràng:

Trước khi viết query, tham khảo `references/api-patterns.md` về:
- Hướng dẫn rate limiting (giới hạn tốc độ)
- Pagination pattern (mẫu phân trang)
- Error code và xử lý

Sử dụng Progressive Disclosure (Tiết lộ dần dần):

Giữ SKILL.md tập trung vào hướng dẫn cốt lõi. Chuyển tài liệu chi tiết sang references/ và link tới. (Xem Core Design Principles về cách hệ thống ba tầng hoạt động.)

Chương 3: Kiểm thử và Cải tiến (Testing and Iteration)

Skill có thể được test ở các mức độ nghiêm ngặt khác nhau tùy nhu cầu:

• Manual testing (Test thủ công) trên Claude.ai - Chạy query trực tiếp và quan sát hành vi. Lặp nhanh, không cần setup.
• Scripted testing (Test có script) trên Claude Code - Tự động hóa test case để xác nhận lặp lại qua các thay đổi.
• Programmatic testing (Test lập trình) qua Skills API - Xây evaluation suite chạy có hệ thống trên tập test xác định.

Chọn cách tiếp cận phù hợp với yêu cầu chất lượng và mức độ phổ biến của skill. Skill dùng nội bộ cho team nhỏ có nhu cầu test khác với skill triển khai cho hàng ngàn người dùng enterprise.

Pro Tip: Lặp đi lặp lại trên một tác vụ duy nhất trước khi mở rộng. Cách hiệu quả nhất là lặp trên một tác vụ khó cho đến khi Claude thành công, sau đó rút ra cách tiếp cận hiệu quả thành skill. Điều này tận dụng in-context learning (học trong ngữ cảnh) của Claude và cho tín hiệu nhanh hơn so với test rộng.

Phương pháp test khuyến nghị

1. Triggering Test (Test kích hoạt)

Mục tiêu: Đảm bảo skill tải đúng lúc.

Test case: - ✅ Trigger với tác vụ rõ ràng - ✅ Trigger với yêu cầu diễn đạt lại - ❌ Không trigger với chủ đề không liên quan

Ví dụ test suite:

Nên trigger:
- "Giúp tôi thiết lập workspace ProjectHub mới"
- "Tôi cần tạo dự án trong ProjectHub"
- "Khởi tạo dự án ProjectHub cho kế hoạch Q4"

KHÔNG nên trigger:
- "Thời tiết ở San Francisco thế nào?"
- "Giúp tôi viết code Python"
- "Tạo spreadsheet" (trừ khi skill ProjectHub xử lý sheets)

2. Functional Test (Test chức năng)

Mục tiêu: Xác minh skill tạo output đúng.

Test case: - Output hợp lệ được tạo - API call thành công - Error handling hoạt động - Edge case (trường hợp biên) được xử lý

Ví dụ:

Test: Tạo dự án với 5 task
Given: Tên dự án "Q4 Planning", 5 mô tả task
When: Skill thực thi workflow
Then:
  - Dự án được tạo trong ProjectHub
  - 5 task được tạo với property đúng
  - Tất cả task liên kết với dự án
  - Không có API error

3. Performance Comparison (So sánh hiệu suất)

Mục tiêu: Chứng minh skill cải thiện kết quả so với baseline.

So sánh baseline:

Sử dụng skill skill-creator

Skill skill-creator - có sẵn trên Claude.ai qua plugin directory hoặc download cho Claude Code - giúp bạn xây và cải tiến skill. Nếu bạn có MCP Server và biết 2-3 workflow hàng đầu, bạn có thể xây và test skill hoàn chỉnh trong một lần ngồi - thường trong 15-30 phút.

Tạo skill: - Tạo skill từ mô tả ngôn ngữ tự nhiên - Xuất SKILL.md đúng format với frontmatter - Đề xuất trigger phrase và cấu trúc

Review skill: - Gắn cờ vấn đề phổ biến (description mơ hồ, thiếu trigger, vấn đề cấu trúc) - Xác định rủi ro over/under-triggering - Đề xuất test case dựa trên mục đích skill

Cải tiến lặp lại: - Sau khi dùng skill và gặp edge case hoặc lỗi, mang các ví dụ đó về skill-creator - Ví dụ: "Dùng các vấn đề & giải pháp trong chat này để cải thiện cách skill xử lý [edge case cụ thể]"

Cách sử dụng:

"Dùng skill skill-creator để giúp tôi xây skill cho [use case của bạn]"

Lưu ý: skill-creator giúp bạn thiết kế và tinh chỉnh skill nhưng không chạy automated test suite hay xuất kết quả đánh giá định lượng.

Cải tiến dựa trên feedback

Skill là tài liệu sống. Hãy lên kế hoạch cải tiến dựa trên:

Tín hiệu Undertriggering (kích hoạt thiếu): - Skill không tải khi cần - Người dùng phải bật thủ công - Câu hỏi hỗ trợ về khi nào dùng nó

Giải pháp: Thêm chi tiết và sắc thái vào description - bao gồm keyword đặc biệt cho thuật ngữ kỹ thuật.

Tín hiệu Overtriggering (kích hoạt thừa): - Skill tải cho query không liên quan - Người dùng tắt nó - Nhầm lẫn về mục đích

Giải pháp: Thêm negative trigger, cụ thể hơn.

Vấn đề Execution (thực thi): - Kết quả không nhất quán - API call thất bại - Người dùng cần sửa

Giải pháp: Cải thiện hướng dẫn, thêm error handling.

Chương 4: Phân phối và Chia sẻ (Distribution and Sharing)

Skill làm cho MCP Integration của bạn hoàn chỉnh hơn. Khi người dùng so sánh các connector, những cái có skill cung cấp đường dẫn nhanh hơn đến giá trị - giúp bạn có lợi thế hơn các giải pháp chỉ có MCP.

Mô hình phân phối hiện tại (Tháng 1/2026)

Cách người dùng cá nhân nhận skill: 1. Tải folder skill 2. Nén folder (nếu cần) 3. Upload lên Claude.ai qua Settings > Capabilities > Skills 4. Hoặc đặt vào thư mục skill của Claude Code

Skill cấp tổ chức (Organization-level): - Admin có thể triển khai skill toàn workspace (ra mắt ngày 18/12/2025) - Cập nhật tự động - Quản lý tập trung

Một tiêu chuẩn mở (Open Standard)

Anthropic đã công bố Agent Skills như một tiêu chuẩn mở. Giống MCP, họ tin rằng skill nên portable (di động) giữa các tool và platform - cùng một skill nên hoạt động dù bạn đang dùng Claude hay AI platform khác. Tuy nhiên, một số skill được thiết kế để tận dụng tối đa khả năng của platform cụ thể; tác giả có thể ghi chú điều này trong field compatibility.

Sử dụng Skill qua API

Cho use case lập trình - như xây ứng dụng, agent, hoặc automated workflow tận dụng skill - API cung cấp quyền kiểm soát trực tiếp quản lý và thực thi skill.

Khả năng chính: - Endpoint /v1/skills để liệt kê và quản lý skill - Thêm skill vào Messages API request qua parameter container.skills - Version control qua Claude Console - Hoạt động với Claude Agent SDK để xây custom agent

Khi nào dùng Skill qua API vs. Claude.ai:

Lưu ý: Skill trong API yêu cầu Code Execution Tool beta, cung cấp môi trường an toàn mà skill cần để chạy.

Cách tiếp cận khuyến nghị hiện tại

Bắt đầu bằng cách host skill trên GitHub với public repo, README rõ ràng (cho người dùng - tách biệt với folder skill không chứa README.md), và ví dụ sử dụng kèm screenshot.

1. Host trên GitHub
2. Public repo cho open-source skill
3. README rõ ràng với hướng dẫn cài đặt

4. Ví dụ sử dụng và screenshot

5. Tài liệu trong MCP Repo

6. Link đến skill từ tài liệu MCP
7. Giải thích giá trị khi dùng cả hai cùng nhau

8. Cung cấp quick-start guide

9. Tạo Installation Guide (Hướng dẫn cài đặt)

## Cài đặt skill [Dịch vụ của bạn]

1. Tải skill:
   - Clone repo: `git clone https://github.com/yourcompany/skills`
   - Hoặc download ZIP từ Releases

2. Cài đặt vào Claude:
   - Mở Claude.ai > Settings > Skills
   - Click "Upload skill"
   - Chọn folder skill (đã nén)

3. Bật skill:
   - Toggle bật skill [Dịch vụ]
   - Đảm bảo MCP Server đã kết nối

4. Test:
   - Hỏi Claude: "Thiết lập dự án mới trong [Dịch vụ]"

Định vị Skill (Positioning)

Cách bạn mô tả skill quyết định liệu người dùng có hiểu giá trị và thực sự thử hay không.

Tập trung vào outcome (kết quả), không phải feature (tính năng):

✅ Tốt:

"Skill ProjectHub cho phép team thiết lập workspace dự án hoàn chỉnh trong vài giây - bao gồm page, database và template - thay vì tốn 30 phút setup thủ công."

❌ Xấu:

"Skill ProjectHub là folder chứa YAML frontmatter và Markdown instruction gọi tool MCP Server."

Nêu bật câu chuyện MCP + Skills:

"MCP Server cho Claude truy cập dự án Linear. Skill dạy Claude workflow sprint planning của team. Kết hợp lại, chúng cho phép quản lý dự án bằng AI."

Chương 5: Các Pattern và Xử lý sự cố (Patterns and Troubleshooting)

Các pattern này xuất phát từ skill được tạo bởi early adopter và internal team. Chúng đại diện cho các cách tiếp cận phổ biến đã được chứng minh hiệu quả, không phải template bắt buộc.

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

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

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

Pattern 1: Sequential Workflow Orchestration (Điều phối workflow tuần tự)

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

## Workflow: Onboard Khách Hàng Mới

### Step 1: Tạo Tài Khoản
Gọi MCP tool: `create_customer`
Tham số: name, email, company

### Step 2: Thiết Lập Thanh Toán
Gọi MCP tool: `setup_payment_method`
Chờ: xác minh phương thức thanh toán

### Step 3: Tạo Subscription
Gọi MCP tool: `create_subscription`
Tham số: plan_id, customer_id (từ Step 1)

### Step 4: Gửi Email Chào Mừng
Gọi MCP tool: `send_email`
Template: welcome_email_template

Kỹ thuật chính: - Thứ tự bước rõ ràng - Dependency (phụ thuộc) giữa các bước - Validation ở mỗi giai đoạn - Hướng dẫn rollback (hoàn tác) khi thất bại

Pattern 2: Multi-MCP Coordination (Phối hợp đa MCP)

Dùng khi: Workflow trải rộng nhiều dịch vụ.

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

### Phase 1: Design Export (Figma MCP)
1. Export tài sản thiết kế từ Figma
2. Tạo specification thiết kế
3. Tạo asset manifest

### Phase 2: Asset Storage (Drive MCP)
1. Tạo folder dự án trong Drive
2. Upload tất cả tài sản
3. Tạo link chia sẻ

### Phase 3: Task Creation (Linear MCP)
1. Tạo task phát triển
2. Đính kèm link tài sản vào task
3. Phân công cho engineering team

### Phase 4: Notification (Slack MCP)
1. Đăng tóm tắt handoff vào #engineering
2. Bao gồm link tài sản và tham chiếu task

Kỹ thuật chính: - Phân pha rõ ràng - Truyền dữ liệu giữa các MCP - Validation trước khi chuyển pha tiếp - Error handling tập trung

Pattern 3: Iterative Refinement (Tinh chỉnh lặp lại)

Dùng khi: Chất lượng output cải thiện qua iteration (lặp).

## Tạo Báo Cáo Lặp

### Initial Draft (Bản nháp đầu)
1. Lấy dữ liệu qua MCP
2. Tạo báo cáo bản nháp đầu
3. Lưu vào file tạm

### Quality Check (Kiểm tra chất lượng)
1. Chạy script validation: `scripts/check_report.py`
2. Xác định vấn đề:
   - Thiếu section
   - Format không nhất quán
   - Lỗi validation dữ liệu

### Refinement Loop (Vòng tinh chỉnh)
1. Xử lý từng vấn đề đã xác định
2. Tạo lại các section bị ảnh hưởng
3. Validate lại
4. Lặp lại cho đến khi đạt ngưỡng chất lượng

### Finalization (Hoàn thiện)
1. Áp dụng format cuối cùng
2. Tạo tóm tắt
3. Lưu bản cuối

Kỹ thuật chính: Tiêu chí chất lượng rõ ràng, cải tiến lặp, validation script, biết khi nào dừng lặp.

Pattern 4: Context-aware Tool Selection (Chọn tool theo ngữ cảnh)

Dùng khi: Cùng kết quả nhưng tool khác nhau tùy ngữ cảnh.

## Smart File Storage (Lưu file thông minh)

### Decision Tree (Cây quyết định)
1. Kiểm tra loại file và kích thước
2. Xác định vị trí lưu tốt nhất:
   - File lớn (>10MB): Dùng cloud storage MCP
   - Tài liệu cộng tác: Dùng Notion/Docs MCP
   - File code: Dùng GitHub MCP
   - File tạm: Dùng local storage

### Execute Storage (Thực thi lưu trữ)
Dựa trên quyết định:
- Gọi tool MCP phù hợp
- Áp dụng metadata đặc thù dịch vụ
- Tạo link truy cập

### Giải thích cho người dùng
Giải thích tại sao chọn storage đó.

Kỹ thuật chính: Tiêu chí quyết định rõ ràng, tùy chọn dự phòng, minh bạch về lựa chọn.

Pattern 5: Domain-specific Intelligence (Trí tuệ chuyên ngành)

Dùng khi: Skill thêm kiến thức chuyên ngành vượt xa quyền truy cập tool.

## Xử lý thanh toán với Compliance (tuân thủ)

### Before Processing (Kiểm tra Compliance trước)
1. Lấy chi tiết giao dịch qua MCP
2. Áp dụng quy tắc compliance:
   - Kiểm tra danh sách trừng phạt
   - Xác minh quyền hạn theo khu vực
   - Đánh giá mức rủi ro
3. Ghi chép quyết định compliance

### Processing (Xử lý)
NẾU compliance đạt:
  - Gọi tool xử lý thanh toán MCP
  - Áp dụng kiểm tra gian lận phù hợp
  - Xử lý giao dịch
KHÔNG ĐẠT:
  - Đánh dấu để review
  - Tạo compliance case

### Audit Trail (Dấu vết kiểm toán)
- Ghi log tất cả kiểm tra compliance
- Ghi lại quyết định xử lý
- Tạo báo cáo kiểm toán

Kỹ thuật chính: Chuyên môn lĩnh vực nhúng trong logic, compliance trước hành động, tài liệu toàn diện, quản trị rõ ràng.

Xử lý sự cố (Troubleshooting)

Skill không upload được

Error: "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). Xác minh bằng: ls -la phải hiển thị SKILL.md

Error: "Invalid frontmatter" - Nguyên nhân: Vấn đề format YAML

# Sai - thiếu delimiter
name: my-skill
description: Làm gì đó

# Sai - ngoặc kép không đóng
name: my-skill
description: "Làm gì đó

# Đúng
---
name: my-skill
description: Làm gì đó
---

Error: "Invalid skill name" - Nguyên nhân: Tên có dấu cách hoặc chữ hoa

# Sai
name: My Cool Skill

# Đúng
name: my-cool-skill

Skill không trigger (kích hoạt)

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

Sửa: Chỉnh sửa field description. Checklist nhanh: - Quá chung chung? ("Giúp với dự án" sẽ không hoạt động) - Có trigger phrase người dùng thực sự nói không? - Có đề cập loại file liên quan khô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 thiếu.

Skill trigger quá nhiều

Triệu chứng: Skill tải cho query không liên quan.

Giải pháp:

1. Thêm negative trigger:

description: Phân tích dữ liệu nâng cao cho file CSV. Dùng cho
  mô hình thống kê, regression, clustering. KHÔNG dùng cho khám
  phá dữ liệu đơn giản (dùng skill data-viz thay thế).

1. Cụ thể hơn:

# Quá rộng
description: Xử lý tài liệu

# Cụ thể hơn
description: Xử lý tài liệu PDF pháp lý để review hợp đồng

1. Làm rõ phạm vi:

description: Xử lý thanh toán PayFlow cho thương mại điện tử.
  Dùng cụ thể cho workflow thanh toán online, không dùng cho truy
  vấn tài chính chung.

Vấn đề kết nối MCP

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

Checklist: 1. Xác minh MCP server đã kết nối (Claude.ai: Settings > Extensions > [Service], phải hiển thị "Connected") 2. Kiểm tra authentication - API key hợp lệ, chưa hết hạn, đúng permission/scope, OAuth token đã refresh 3. Test MCP độc lập - Hỏi Claude gọi MCP trực tiếp (không qua skill): "Dùng [Service] MCP để lấy dự án của tôi". Nếu thất bại → vấn đề là MCP, không phải skill. 4. Xác minh tên tool - Skill tham chiếu đúng tên tool MCP. Kiểm tra tài liệu MCP Server. Tên tool phân biệt hoa thường (case-sensitive).

Hướng dẫn 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:

1. Hướng dẫn quá dài: Giữ hướng dẫn ngắn gọn. Dùng bullet point và danh sách đánh số. Chuyển tài liệu chi tiết sang file riêng.

2. Hướng dẫn 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ồ:

# Xấu
Đảm bảo validate mọi thứ đúng cách

# Tốt
CRITICAL: Trước khi gọi create_project, xác minh:
- Tên dự án không trống
- Có ít nhất một thành viên team được phân công
- Ngày bắt đầu không nằm trong quá khứ

Kỹ thuật nâng cao: Cho validation quan trọng, cân nhắc đóng gói script kiểm tra theo chương trình thay vì dựa vào hướng dẫn ngôn ngữ. Code là deterministic (xác định); diễn giải ngôn ngữ thì không.

1. Model "lười biếng": Thêm khuyến khích rõ ràng:

## Performance Notes
- Hãy dành thời gian làm kỹ lưỡng
- Chất lượng quan trọng hơn tốc độ
- Không bỏ qua bước validation

Lưu ý: Thêm điều này vào user prompt hiệu quả hơn trong SKILL.md.

Vấn đề Context lớn

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

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: Di chuyển tài liệu chi tiết sang references/. Link thay vì inline. Giữ SKILL.md dưới 5,000 từ. 2. Giảm số skill bật: Đánh giá nếu bạn có hơn 20-50 skill bật đồng thời. Khuyến nghị bật có chọn lọc. Cân nhắc "skill pack" cho các khả năng liên quan.

Chương 6: Tài nguyên và Tham khảo (Resources and References)

Nếu bạn đang xây skill đầu tiên, hãy bắt đầu với Best Practices Guide, sau đó tham khảo API docs khi cần.

Tài liệu chính thức (Official Documentation)

Tài nguyên Anthropic: - Best Practices Guide - Skills Documentation - API Reference - MCP Documentation

Blog Post: - Introducing Agent Skills - Engineering Blog: Equipping Agents for the Real World - Skills Explained - How to Create Skills for Claude - Building Skills for Claude Code - Improving Frontend Design through Skills

Skill mẫu (Example Skills)

Public skills repository: - GitHub: anthropics/skills - Chứa các skill do Anthropic tạo mà bạn có thể tùy chỉnh

Tool và Tiện ích

Skill skill-creator: - Tích hợp sẵn trong Claude.ai và có sẵn cho Claude Code - Có thể tạo skill từ mô tả - Review và đưa ra khuyến nghị - Cách dùng: "Giúp tôi xây skill bằng skill-creator"

Validation: - skill-creator có thể đánh giá skill của bạn - Hỏi: "Review skill này và đề xuất cải thiện"

Hỗ trợ (Getting Support)

Câu hỏi kỹ thuật: Community forum tại Claude Developers Discord

Báo cáo Bug: GitHub Issues: anthropics/skills/issues - bao gồm: tên skill, thông báo lỗi, các bước tái tạo.

Phụ lục A: Checklist nhanh

Dùng checklist này để validate skill trước và sau khi upload. Nếu muốn bắt đầu nhanh, dùng skill skill-creator để tạo bản nháp đầu, sau đó chạy qua danh sách này.

Trước khi bắt đầu

• [ ] Xác định 2-3 use case cụ thể
• [ ] Xác định tool cần dùng (tích hợp sẵn hoặc MCP)
• [ ] Đã xem hướng dẫn và skill mẫu
• [ ] Lên kế hoạch cấu trúc folder

Trong quá trình phát triển

• [ ] Folder đặt tên kebab-case
• [ ] File SKILL.md tồn tại (chính xác chính tả)
• [ ] YAML Frontmatter có delimiter ---
• [ ] Field name: kebab-case, không dấu cách, không chữ hoa
• [ ] description bao gồm WHAT (cái gì) và WHEN (khi nào)
• [ ] Không có XML tag (< >) ở đâu cả
• [ ] Hướng dẫn rõ ràng và actionable
• [ ] Có xử lý lỗi (error handling)
• [ ] Có ví dụ
• [ ] Reference được link rõ ràng

Trước khi upload

• [ ] Test trigger với tác vụ rõ ràng
• [ ] Test trigger với yêu cầu diễn đạt lại
• [ ] Xác nhận không trigger với chủ đề không liên quan
• [ ] Functional test đạt
• [ ] Tool integration hoạt động (nếu áp dụng)
• [ ] Đã nén thành file .zip

Sau khi upload

• [ ] Test trong cuộc hội thoại thực
• [ ] Giám sát under/over-triggering
• [ ] Thu thập user feedback
• [ ] Cải tiến description và hướng dẫn
• [ ] Cập nhật version trong metadata

Phụ lục B: YAML Frontmatter

Field bắt buộc (Required)

---
name: skill-name-in-kebab-case
description: Nó làm gì và khi nào dùng. Bao gồm trigger phrase cụ thể.
---

Tất cả field tùy chọn

name: skill-name
description: [description bắt buộc]
license: MIT # Tùy chọn: License cho open-source
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # Tùy chọn: Giới hạn truy cập tool
metadata: # Tùy chọn: Field tùy chỉnh
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
  documentation: https://example.com/docs
  support: support@example.com

Lưu ý bảo mật (Security Notes)

Được phép: - Bất kỳ kiểu YAML chuẩn (string, number, boolean, list, object) - Field metadata tùy chỉnh - Description dài (đến 1024 ký tự)

Bị cấm: - Dấu ngoặc nhọn XML (< >) - hạn chế bảo mật - Thực thi code trong YAML (dùng safe YAML parsing) - Skill đặt tên với prefix "claude" hoặc "anthropic" (đã reserved)

Phụ lục C: Ví dụ Skill hoàn chỉnh

Cho các skill production-ready (sẵn sàng sản xuất) đầy đủ minh họa các pattern trong hướng dẫn này:

• Document Skills - Tạo PDF, DOCX, PPTX, XLSX
• Example Skills - Các pattern workflow đa dạng
• Partner Skills Directory - Xem skill từ nhiều partner như Asana, Atlassian, Canva, Figma, Sentry, Zapier, và nhiều hơn nữa

Các repository này được cập nhật thường xuyên và bao gồm ví dụ bổ sung ngoài những gì được trình bày ở đây. Clone chúng, chỉnh sửa cho use case của bạn, và dùng làm template.

Nguồn: claude.ai