Hướng dẫn đầy đủ về cách xây dựng Skills cho Claude

Nguồn: Anthropic, The Complete Guide to Building Skills for Claude
File gốc trong workspace: claude-skill-guide.pdf

Bản này là Markdown tiếng Việt đã được làm sạch từ PDF, giữ lại cấu trúc chính, ví dụ kỹ thuật, checklist và mẫu YAML.

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 thư mục đơn giản, dạy Claude cách xử lý một công việc hoặc quy trình cụ thể. Đây là một trong những cách mạnh nhất để tùy biến Claude theo nhu cầu riêng. Thay vì phải giải thích lại sở thích, quy trình và hiểu biết chuyên môn về lĩnh vực của bạn trong từng cuộc trò chuyện, bạn có thể dạy Claude một lần bằng skill rồi dùng lại nhiều lần.

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

Tài liệu này bao quát toàn bộ quá trình xây dựng skill hiệu quả: từ lập kế hoạch, cấu trúc, kiểm thử đến phân phối. Dù bạn xây skill cho cá nhân, đội nhóm hay cộng đồng, tài liệu vẫn cung cấp các mẫu thực tế và ví dụ có thể áp dụng.

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

• Yêu cầu kỹ thuật và best practice cho cấu trúc skill.
• Mẫu thiết kế cho skill chạy độc lập và workflow được hỗ trợ bằng MCP.
• Các pattern đã hoạt động tốt trong nhiều trường hợp sử dụng.
• Cách kiểm thử, cải tiến qua nhiều vòng và phân phối skill.

Tài liệu này dành cho ai

• Developer muốn Claude tuân theo workflow cụ thể một cách nhất quán.
• Người dùng bình thường muốn Claude làm việc theo quy trình riêng.
• Đội nhóm muốn chuẩn hóa cách Claude vận hành trong tổ chức.

Hai hướng đọc tài liệu

Nếu bạn đang xây skill chạy độc lập, hãy tập trung vào các phần: Nền tảng, Lập kế hoạch và thiết kế, cùng các nhóm use case 1-2. Nếu bạn đang bổ sung hướng dẫn cho một tích hợp MCP, phần "Skills + MCP" và nhóm 3 sẽ phù hợp hơn. Cả hai hướng đều dùng chung yêu cầu kỹ thuật, nhưng bạn chọn phần liên quan đến use case của mình.

Mục tiêu cuối cùng: sau khi đọc xong, bạn có thể xây một skill hoạt động được trong một phiên làm việc. Với skill-creator, thường mất khoảng 15-30 phút để tạo và kiểm thử skill đầu tiên.

Chương 1: Nền tảng

Skill là gì?

Một skill là một thư mục chứa:

• SKILL.md (bắt buộc): hướng dẫn bằng Markdown, có YAML frontmatter.
• scripts/ (tùy chọn): code thực thi, ví dụ Python hoặc Bash.
• references/ (tùy chọn): tài liệu tham khảo được tải khi cần.
• assets/ (tùy chọn): template, font, icon hoặc tài nguyên dùng trong output.

Nguyên tắc thiết kế cốt lõi

Progressive Disclosure

Skill 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. Phần này chỉ cung cấp đủ thông tin để Claude biết khi nào nên dùng skill, không đưa toàn bộ nội dung vào context.
• Tầng 2, nội dung SKILL.md: được tải khi Claude đánh giá skill có liên quan đến yêu cầu hiện tại. Đây là nơi chứa hướng dẫn đầy đủ.
• Tầng 3, file liên kết: các file bổ sung trong thư mục skill mà Claude có thể tự tìm và đọc khi cần.

Cách làm này giảm lượng token sử dụng nhưng vẫn giữ được hướng dẫn chuyên sâu.

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 skill khác, không nên giả định nó là khả năng duy nhất đang có.

Khả năng dùng ở nhiều môi trường

Skill hoạt động tương tự trên Claude.ai, Claude Code và API, miễn là môi trường hỗ trợ các dependency mà skill cần. Bạn tạo skill một lần và có thể dùng ở nhiều nơi khác nhau.

Dành cho người xây MCP: Skills + Connectors

Nếu bạn đã có MCP server hoạt động, phần khó nhất đã xong. Skill là lớp hướng dẫn đặt phía trên: nó ghi lại workflow và best practice bạn đã biết để Claude áp dụng nhất quán.

Một cách hình dung:

• MCP là căn bếp chuyên nghiệp: cung cấp công cụ, nguyên liệu và thiết bị.
• Skill là công thức: chỉ dẫn từng bước để tạo ra kết quả có giá trị.

Kết hợp lại, chúng giúp người dùng hoàn thành công việc phức tạp mà không cần tự tìm từng bước.

Vì sao điều này quan trọng với người dùng MCP

Không có skill:

• Người dùng kết nối MCP nhưng không biết làm gì tiếp theo.
• Có nhiều ticket hỗ trợ kiểu "làm X với integration của bạn như thế nào".
• Mỗi cuộc trò chuyện bắt đầu lại từ đầu.
• Kết quả không nhất quán vì mỗi người prompt khác nhau.
• Người dùng có thể đổ lỗi cho connector, trong khi vấn đề thật là thiếu hướng dẫn workflow.

Có skill:

• Các workflow dựng sẵn được Claude dùng tự động khi cần.
• Cách dùng tool nhất quán và đáng tin cậy hơn.
• Best practice được nhúng vào từng tương tác.
• Giúp người dùng học cách dùng integration nhanh hơn.

Chương 2: Lập kế hoạch và thiết kế

Bắt đầu từ use case

Trước khi viết code, hãy xác định 2-3 use case cụ thể mà skill cần hỗ trợ.

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

Trường hợp sử dụng: Lập kế hoạch sprint cho dự án
Kích hoạt khi: Người dùng nói "giúp tôi lập kế hoạch sprint này" hoặc "tạo task cho sprint"

Các bước:
1. Lấy trạng thái hiện tại của dự án từ Linear (qua MCP)
2. Phân tích velocity và capacity của team
3. Đề xuất thứ 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ập kế hoạch đầy đủ, kèm 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 được hỗ trợ?
• Cần dùng tool nào, built-in hay MCP?
• Hiểu biết chuyên môn hoặc best practice nào nên được nhúng vào skill?

Các nhóm use case phổ biến

Anthropic quan sát thấy ba nhóm use case thường gặp.

Nhóm 1: Tạo tài liệu và tài nguyên

Dùng cho việc tạo output nhất quán, chất lượng cao như tài liệu, presentation, app, design, code.

Ví dụ thực tế: skill frontend-design, cùng các skill cho docx, pptx, xlsx, ppt.

Mô tả mẫu:

Tạo giao diện frontend khác biệt, đủ chất lượng production và có thiết kế tốt.
Dùng khi xây web component, page, artifact, poster hoặc ứng dụng.

Kỹ thuật chính:

• Nhúng style guide và chuẩn thương hiệu.
• Dùng template để output nhất quán.
• Có checklist chất lượng trước khi hoàn tất.
• Không cần tool bên ngoài, tận dụng khả năng sẵn có của Claude.

Nhóm 2: Tự động hóa workflow

Dùng cho quy trình nhiều bước cần phương pháp nhất quán, có thể điều phối nhiều MCP server.

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

Mô tả mẫu:

Hướng dẫn tương tác để tạo skill mới. Dẫn người dùng qua các bước định nghĩa
use case, tạo frontmatter, viết hướng dẫn và kiểm tra hợp lệ.

Kỹ thuật chính:

• Workflow từng bước với các điểm kiểm tra rõ ràng.
• Template cho cấu trúc phổ biến.
• Review tích hợp sẵn và đề xuất cải thiện.
• Vòng lặp cải tiến.

Nhóm 3: Bổ sung hướng dẫn cho MCP

Dùng để bổ sung hướng dẫn workflow cho các tool mà MCP server cung cấp.

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

Mô tả mẫu:

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 thông qua MCP server của họ.

Kỹ thuật chính:

• Điều phối nhiều lệnh gọi MCP theo trình tự.
• Nhúng chuyên môn theo lĩnh vực.
• Cung cấp bối cảnh mà nếu không người dùng phải tự mô tả.
• Xử lý các lỗi MCP thường gặp.

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

Các chỉ số này là mục tiêu định hướng, không phải ngưỡng tuyệt đối. Hãy nghiêm túc đo lường, nhưng chấp nhận rằng đánh giá chất lượng vẫn có phần cảm tính.

Chỉ số định lượng:

• Claude dùng skill cho khoảng 90% truy vấn liên quan.
• Hoàn thành workflow trong X tool call.
• Không có API call lỗi trong mỗi workflow.

Cách đo:

• Chạy 10-20 câu test mà skill nên được dùng.
• So sánh cùng một công việc khi bật và tắt skill.
• Đếm tool call, token sử dụng, số lần retry và mã lỗi.

Chỉ số định tính:

• Người dùng không cần hỏi Claude bước tiếp theo.
• Workflow hoàn tất mà không cần người dùng sửa.
• Kết quả nhất quán giữa các phiên làm việc.

Cách đánh giá:

• Ghi lại số lần cần chuyển hướng hoặc làm rõ trong lúc test.
• Chạy cùng request 3-5 lần và so sánh cấu trúc, chất lượng output.
• Kiểm tra liệu người dùng mới có làm được việc ngay lần đầu với ít hướng dẫn hay không.

Yêu cầu kỹ thuật

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

Quy tắc quan trọng:

• File chính phải tên chính xác là SKILL.md, phân biệt hoa thường.
• Không dùng biến thể như SKILL.MD, skill.md.
• Tên thư mục skill dùng kebab-case, ví dụ notion-project-setup.
• Không dùng khoảng trắng, underscore hoặc chữ hoa trong tên skill.
• Không đặt README.md bên trong thư mục skill. Tài liệu của skill nằm trong SKILL.md hoặc references/. README cấp repo vẫn nên có khi phân phối qua GitHub.

YAML frontmatter

YAML frontmatter là phần Claude dùng để quyết định có tải skill hay không. Đây là phần quan trọng nhất.

Định dạng tối thiểu:

---
name: your-skill-name
description: Skill này làm gì. Dùng khi người dùng yêu cầu [các cụm từ cụ thể].
---

Trường bắt buộc:

• name: chỉ dùng kebab-case, không có khoảng trắng hoặc chữ hoa, nên khớp tên thư mục.
• description: phải có cả skill làm gì và khi nào dùng. Dưới 1024 ký tự, không có XML tag, nên chứa task hoặc cụm từ người dùng có thể nói.

Trường tùy chọn:

• license: dùng nếu skill open source, ví dụ MIT, Apache-2.0.
• compatibility: mô tả yêu cầu môi trường, sản phẩm, package hệ thống hoặc network.
• metadata: thông tin tùy ý như author, version, MCP server.

Ví dụ:

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

Hạn chế bảo mật trong frontmatter:

• Không dùng dấu ngoặc nhọn XML < hoặc >.
• Không dùng claude hoặc anthropic trong tên skill vì đây là các từ khóa dành riêng.

Lý do: frontmatter xuất hiện trong system prompt của Claude, nên nội dung không an toàn có thể cố tình chèn chỉ dẫn.

Viết description hiệu quả

Cấu trúc nên là:

[Skill làm gì] + [Khi nào dùng] + [Khả năng chính]

Ví dụ tốt:

description: Phân tích file thiết kế Figma và tạo tài liệu bàn giao cho developer. Dùng khi người dùng upload file .fig, yêu cầu "thông số thiết kế", "tài liệu component" hoặc "bàn giao từ design sang code".

description: Quản lý workflow dự án trong Linear, gồm lập kế hoạch sprint, tạo task và theo dõi trạng thái. Dùng khi người dùng nhắc tới "sprint", "task Linear", "lập kế hoạch dự án" hoặc yêu cầu "tạo ticket".

Ví dụ chưa tốt:

description: Giúp xử lý dự án.

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

description: Triển khai model entity Dự án với quan hệ phân cấp.

Vấn đề của các ví dụ xấu là quá mơ hồ, thiếu trigger hoặc quá kỹ thuật nhưng không nói người dùng sẽ yêu cầu như thế nào.

Viết phần hướng dẫn chính

Sau frontmatter, viết hướng dẫn thật sự bằng Markdown. Một cấu trúc khuyến nghị:

---
name: your-skill
description: [Mô tả bắt buộc]
---

# Tên Skill Của Bạn

## Hướng dẫn

## Bước 1: [Bước chính đầu tiên]

Giải thích rõ điều sẽ diễn ra.

Ví dụ:

```bash
python scripts/fetch_data.py --project-id PROJECT_ID
```

Output kỳ vọng: [mô tả trạng thái thành công]

## Ví dụ

### Ví dụ 1: [tình huống thường gặp]

Người dùng nói: "Thiết lập một chiến dịch marketing mới"

Hành động:
1. Lấy các campaign hiện có qua MCP
2. Tạo campaign mới với các tham số được cung cấp

Kết quả: Campaign được tạo kèm link xác nhận

## Xử lý sự cố

### Lỗi: [Thông báo lỗi thường gặp]

Nguyên nhân: [Vì sao lỗi xảy ra]

Cách xử lý: [Cách sửa lỗi]

Best practice khi viết hướng dẫn:

• Cụ thể và có thể hành động.
• Tham chiếu rõ tài nguyên đi kèm.
• Dùng progressive disclosure: giữ SKILL.md tập trung vào hướng dẫn cốt lõi, chuyển tài liệu dài sang references/.
• Có xử lý lỗi.

Ví dụ tốt:

Trước khi viết query, đọc `references/api-patterns.md` để xem:
- Hướng dẫn rate limit
- Pattern phân trang
- Mã lỗi và cách xử lý

Chạy `python scripts/validate.py --input {filename}` để kiểm tra định dạng dữ liệu.

Ví dụ chưa tốt:

Kiểm tra dữ liệu trước khi tiếp tục.

Lý do: câu này không nói kiểm tra bằng gì, kiểm tra điều kiện nào, lỗi thì xử lý ra sao.

Ví dụ xử lý lỗi:

## Vấn đề thường gặp

### Kết nối MCP thất bại

Nếu thấy lỗi "Connection refused":
1. Xác minh MCP server đang chạy: kiểm tra Settings > Extensions
2. Xác nhận API key còn hợp lệ
3. Thử kết nối lại: Settings > Extensions > [Dịch vụ của bạn] > Reconnect

Chương 3: Kiểm thử và cải tiến qua nhiều vòng

Skill có thể được kiểm thử ở nhiều mức độ:

• Kiểm thử thủ công trong Claude.ai: chạy query trực tiếp và quan sát hành vi.
• Kiểm thử bằng script trong Claude Code: tự động hóa test case để kiểm tra lặp lại sau mỗi lần sửa.
• Kiểm thử bằng API: xây evaluation suite chạy có hệ thống trên bộ test đã định nghĩa.

Chọn mức độ phù hợp với yêu cầu chất lượng và phạm vi sử dụng. Skill nội bộ cho một nhóm nhỏ không cần cùng mức kiểm thử như skill dùng cho hàng nghìn người dùng enterprise.

Mẹo: hãy cải tiến trên một việc khó trước, cho đến khi Claude làm đúng, rồi trích xuất cách làm hiệu quả đó thành skill. Cách này tận dụng in-context learning và cho tín hiệu nhanh hơn so với test quá rộng ngay từ đầu.

Cách kiểm thử khuyến nghị

1. Triggering tests

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

Test case:

• Claude dùng skill với yêu cầu hiển nhiên.
• Claude dùng skill với yêu cầu được nói theo cách khác.
• Claude không dùng skill với chủ đề không liên quan.

Ví dụ nên dùng skill:

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

Ví dụ không nên dùng skill:

• "Thời tiết ở San Francisco hôm nay thế nào?"
• "Giúp tôi viết code Python"
• "Tạo một spreadsheet" nếu skill ProjectHub không xử lý spreadsheet.

2. Functional tests

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

Test case:

• Output hợp lệ được tạo.
• API call thành công.
• Xử lý lỗi hoạt động.
• Edge case được bao phủ.

Ví dụ:

Kiểm thử: Tạo dự án với 5 task
Cho trước: Tên dự án là "Kế hoạch Q4", có 5 mô tả task
Khi: Skill thực thi workflow
Thì:
- Dự án được tạo trong ProjectHub
- 5 task được tạo với thuộc tính đúng
- Tất cả task được liên kết với dự án
- Không có lỗi API

3. So sánh hiệu năng

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

Ví dụ so sánh:

Không dùng skill:
- Người dùng phải cung cấp hướng dẫn mỗi lần
- 15 lượt trao đổi qua lại
- 3 API call lỗi cần thử lại
- Tiêu thụ 12.000 token

Có dùng skill:
- Workflow được thực thi tự động
- Chỉ cần 2 câu hỏi làm rõ
- 0 API call lỗi
- Tiêu thụ 6.000 token

Dùng skill-creator

skill-creator có trong Claude.ai qua plugin directory hoặc có thể tải cho Claude Code. Nó giúp xây và cải tiến skill qua nhiều vòng. Nếu bạn có MCP server và biết 2-3 workflow quan trọng nhất, thường có thể tạo và test skill hoạt động trong 15-30 phút.

Khả năng khi tạo skill:

• Sinh skill từ mô tả ngôn ngữ tự nhiên.
• Tạo SKILL.md đúng định dạng với frontmatter.
• Gợi ý trigger phrase và cấu trúc.

Khả năng khi review skill:

• Chỉ ra lỗi phổ biến như description mơ hồ, thiếu trigger, vấn đề cấu trúc.
• Xác định nguy cơ over-trigger hoặc under-trigger.
• Gợi ý test case dựa trên mục đích skill.

Ví dụ dùng:

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

Lưu ý: skill-creator giúp thiết kế và chỉnh sửa skill, nhưng không tự chạy test suite tự động hoặc tạo kết quả đánh giá định lượng.

Lặp lại dựa trên phản hồi

Skill là tài liệu sống. Hãy dự kiến việc chỉnh sửa dựa trên:

Tín hiệu under-triggering:

• Claude không tải skill khi đáng ra phải tải.
• Người dùng phải bật skill thủ công.
• Có câu hỏi hỗ trợ về lúc nào nên dùng skill.

Giải pháp: thêm chi tiết và bối cảnh vào description, đặc biệt là keyword kỹ thuật.

Tín hiệu over-triggering:

• Claude tải skill cho truy vấn không liên quan.
• Người dùng tắt skill.
• Người dùng bối rối về mục đích skill.

Giải pháp: thêm negative trigger và làm description cụ thể hơn.

Vấn đề thực thi:

• Kết quả không nhất quán.
• API call bị lỗi.
• Cần người dùng sửa nhiều.

Giải pháp: cải thiện hướng dẫn và bổ sung xử lý lỗi.

Chương 4: Phân phối và chia sẻ

Skill làm cho tích hợp MCP hoàn chỉnh hơn. Khi người dùng so sánh connector, connector có skill giúp họ đạt được giá trị nhanh hơn so với chỉ có MCP.

Mô hình phân phối hiện tại

Cách người dùng cá nhân nhận skill:

1. Tải thư mục skill.
2. Zip thư mục nếu cần.
3. Upload vào Claude.ai qua Settings > Capabilities > Skills.
4. Hoặc đặt vào thư mục skills của Claude Code.

Skill cấp tổ chức:

• Admin có thể triển khai skill cho toàn workspace.
• Hỗ trợ cập nhật tự động.
• Quản lý tập trung.

Dùng skill qua API

Với use case lập trình như xây app, agent hoặc workflow tự động dùng skill, API cho phép kiểm soát trực tiếp việc 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 request Messages API qua tham số container.skills.
• Quản lý phiên bản qua Claude Console.
• Hoạt động cùng Claude Agent SDK để xây agent tùy chỉnh.

Khi nào dùng API thay vì Claude.ai:

Lưu ý: skill trong API yêu cầu Code Execution Tool beta, vì đây là môi trường bảo mật để skill chạy.

Cách khuyến nghị hiện tại

Hãy bắt đầu bằng cách đưa skill lên một repo public trên GitHub, kèm README rõ ràng cho người đọc, ví dụ sử dụng và screenshot. README này ở cấp repo, tách khỏi thư mục skill, vì thư mục skill không nên có README.md.

Sau đó, thêm phần vào tài liệu MCP để:

• Link tới skill.
• Giải thích vì sao dùng skill cùng MCP có giá trị.
• Cung cấp quick-start guide.

Các bước gợi ý:

1. Đưa skill lên GitHub.
2. Viết tài liệu trong repo MCP.
3. Tạo hướng dẫn cài đặt.

Mẫu 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 tải file ZIP từ Releases

2. Cài đặt trong Claude:
   - Mở Claude.ai > Settings > Skills
   - Bấm "Upload skill"
   - Chọn thư mục skill hoặc file zip

3. Bật skill:
   - Bật skill [Dịch vụ của bạn]

4. Kiểm thử:
   - Đảm bảo MCP server đã kết nối
   - Yêu cầu Claude: "Thiết lập một dự án mới trong [Dịch vụ của bạn]"

Trình bày giá trị của skill

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

Tập trung vào kết quả, không phải tính năng.

Ví dụ tốt:

Skill ProjectHub giúp các 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ì mất 30 phút làm thủ công.

Ví dụ chưa tốt:

Skill ProjectHub là một thư mục chứa YAML frontmatter và hướng dẫn Markdown,
có gọi các tool từ MCP server của chúng tôi.

Kể câu chuyện MCP + skill:

MCP server của chúng tôi cho Claude quyền truy cập vào các dự án Linear của bạn.
Skill của chúng tôi dạy Claude workflow lập kế hoạch sprint của team bạn.
Khi kết hợp, chúng tạo ra trải nghiệm quản lý dự án có AI hỗ trợ.

Chương 5: Mẫu triển khai và xử lý sự cố

Các pattern sau xuất hiện từ skill của những nhóm dùng sớm và các nhóm nội bộ. Đây là các hướng tiếp cận thường hiệu quả, không phải template bắt buộc.

Chọn cách tiếp cận: problem-first hay tool-first

Problem-first: người dùng nói "Tôi cần thiết lập workspace dự án". Skill điều phối đúng MCP call theo đúng thứ tự. Người dùng mô tả kết quả; skill xử lý tool.

Tool-first: người dùng nói "Tôi đã kết nối Notion MCP". Skill dạy Claude 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.

Hầu hết skill nghiêng về một hướng. Xác định góc tiếp cận phù hợp giúp chọn pattern đúng.

Pattern 1: Đ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ể.

Ví dụ:

# Workflow: Onboard khách hàng mới

## Bước 1: Tạo tài khoản
Gọi MCP tool: `create_customer`
Tham số: name, email, company

## Bước 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

## Bước 3: Tạo subscription
Gọi MCP tool: `create_subscription`
Tham số: plan_id, customer_id (từ Bước 1)

## Bước 4: Gửi email chào mừng
Gọi MCP tool: `send_email`
Template sử dụng: welcome_email_template

Kỹ thuật chính:

• Thứ tự bước rõ ràng.
• Có dependency giữa các bước.
• Validation ở từng giai đoạn.
• Hướng dẫn rollback khi có lỗi.

Pattern 2: Điều phối nhiều MCP

Dùng khi workflow trải qua nhiều dịch vụ.

Ví dụ: handoff từ design sang development.

# Phase 1: Export thiết kế (Figma MCP)
1. Export tài nguyên thiết kế từ Figma
2. Tạo đặc tả thiết kế
3. Tạo manifest tài nguyên

# Phase 2: Lưu trữ tài nguyên (Drive MCP)
1. Tạo thư mục dự án trong Drive
2. Upload toàn bộ tài nguyên
3. Tạo link chia sẻ

# Phase 3: Tạo task (Linear MCP)
1. Tạo task phát triển
2. Gắn link tài nguyên vào task
3. Giao task cho team engineering

# Phase 4: Thông báo (Slack MCP)
1. Đăng tóm tắt handoff lên #engineering
2. Kèm link tài nguyên và tham chiếu task

Kỹ thuật chính:

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

Pattern 3: Cải tiến qua nhiều vòng

Dùng khi chất lượng output tốt hơn sau nhiều vòng lặp.

Ví dụ: tạo report.

# Tạo report qua nhiều vòng cải tiến

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

## Kiểm tra chất lượng
1. Chạy script kiểm tra: `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

## Vòng cải tiến
1. Xử lý từng vấn đề đã phát hiện
2. Tạo lại các section bị ảnh hưởng
3. Kiểm tra lại
4. Lặp lại cho đến khi đạt ngưỡng chất lượng

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

Kỹ thuật chính:

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

Pattern 4: Chọn tool theo bối cảnh

Dùng khi cùng một kết quả nhưng công cụ thay đổi tùy bối cảnh.

Ví dụ: lưu file thông minh.

# Lưu file thông minh

## Cây quyết định
1. Kiểm tra loại file và dung lượng
2. Xác định nơi lưu phù hợp 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

## Thực hiện lưu trữ
Dựa trên quyết định:
- Gọi MCP tool phù hợp
- Áp dụng metadata riêng của từng dịch vụ
- Tạo link truy cập

## Cung cấp bối cảnh cho người dùng
Giải thích vì sao chọn nơi lưu đó

Kỹ thuật chính:

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

Pattern 5: Chuyên môn theo lĩnh vực

Dùng khi skill bổ sung chuyên môn vượt ngoài quyền truy cập tool.

Ví dụ: xử lý thanh toán có kiểm tra tuân thủ/compliance.

# Xử lý thanh toán có kiểm tra compliance

## Trước khi xử lý (kiểm tra compliance)
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 cấm vận
   - Xác minh quyền xử lý theo khu vực pháp lý
   - Đánh giá mức độ rủi ro
3. Ghi lại quyết định compliance

## Xử lý
NẾU đạt kiểm tra compliance:
- Gọi MCP tool xử lý thanh toán
- Áp dụng kiểm tra gian lận phù hợp
- Xử lý giao dịch

NẾU KHÔNG:
- Đánh dấu để review
- Tạo case compliance

## Audit trail
- Log toàn bộ kiểm tra compliance
- Ghi lại quyết định xử lý
- Tạo báo cáo audit

Kỹ thuật chính:

• Nhúng chuyên môn theo lĩnh vực vào logic.
• Kiểm tra compliance trước khi hành động.
• Tài liệu hóa đầy đủ.
• Cơ chế quản trị rõ ràng.

Xử lý sự cố

Skill không upload được

Lỗi:

Không tìm thấy SKILL.md trong thư mục đã upload

Nguyên nhân: file không được đặt tên chính xác là 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 và đảm bảo thấy SKILL.md.

Lỗi:

Frontmatter không hợp lệ

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

Ví dụ sai:

name: my-skill
description: Làm một số việc

---
name: my-skill
description: "Làm một số việc
---

Ví dụ đúng:

---
name: my-skill
description: Làm một số việc
---

Lỗi:

Tên skill không hợp lệ

Nguyên nhân: tên có khoảng trắng hoặc chữ hoa.

Sai:

name: My Cool Skill

Đúng:

name: my-cool-skill

Skill không tự bật

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

Cách sửa:

• Xem lại trường description.
• Kiểm tra description có quá chung chung không.
• Thêm cụm từ trigger mà người dùng thật sự sẽ nói.
• Nhắc tới file type liên quan nếu cần.

Gỡ lỗi:

Khi nào bạn sẽ dùng skill [tên skill]?

Claude sẽ phản hồi dựa trên description. Dùng câu trả lời đó để biết phần nào còn thiếu.

Skill tự bật quá thường xuyên

Triệu chứng: Claude tải skill cho truy vấn 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ê, hồi quy và clustering. KHÔNG dùng cho khám phá dữ liệu đơn giản (hãy dùng skill data-viz).

2. 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 pháp lý dạng PDF để review hợp đồng

3. Làm rõ phạm vi.

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

Claude không làm theo hướng dẫn

Triệu chứng: Claude tải skill nhưng không tuân theo hướng dẫn.

Nguyên nhân thường gặp:

• Hướng dẫn quá dài.
• Hướng dẫn quan trọng bị chôn sâu.
• Ngôn ngữ mơ hồ.

Cách sửa:

• Giữ hướng dẫn ngắn gọn.
• Dùng bullet và danh sách đánh số.
• Chuyển tham khảo dài sang file riêng.
• Đặt chỉ dẫn quan trọng ở đầu.
• Dùng heading như ## Important hoặc ## Critical.
• Lặp lại điểm then chốt khi cần.

Ví dụ chưa tốt:

Nhớ kiểm tra mọi thứ cho đúng

Ví dụ tốt:

## CRITICAL: Trước khi gọi create_project, hãy xác minh:

- Tên dự án không được để trống
- Có ít nhất một thành viên team được gán
- Ngày bắt đầu không nằm trong quá khứ

Kỹ thuật nâng cao: với validation quan trọng, hãy cân nhắc đóng gói script để kiểm tra bằng code. Code có tính quyết định cao hơn diễn giải ngôn ngữ tự nhiên.

Lỗi kết nối MCP

Triệu chứng: Claude tải skill nhưng MCP call bị lỗi.

Danh sách kiểm tra:

1. Kiểm tra MCP server đã kết nối.
   • Claude.ai: Settings > Extensions > [Dịch vụ của bạn]
   • Trạng thái nên là Connected.
2. Kiểm tra xác thực.
   • API key còn hạn.
   • Quyền hoặc scope đúng.
   • OAuth token đã refresh.
3. Test MCP độc lập.
   • Yêu cầu Claude gọi MCP trực tiếp, không dùng skill.
   • Ví dụ: "Dùng MCP của [Dịch vụ] để lấy danh sách dự án của tôi".
   • Nếu bước này cũng lỗi, vấn đề nằm ở 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 có phân biệt hoa thường.
   • Đối chiếu tài liệu MCP server.

Ghi chú về "model laziness": với việc quan trọng, người dùng có thể thêm nhắc nhở trực tiếp vào prompt:

Hãy làm việc này thật kỹ.
Chất lượng quan trọng hơn tốc độ.
Không bỏ qua các bước validation.

Thông thường, thêm các câu này vào prompt của người dùng hiệu quả hơn đặt trong SKILL.md.

Vấn đề context lớn

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.
• Bật quá nhiều skill cùng lúc.
• Tất cả nội dung được tải thay vì dùng 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/.
   • Link tới file tham khảo thay vì nhúng inline.
   • Giữ SKILL.md dưới khoảng 5.000 từ.
2. Giảm số skill được bật.
   • Đánh giá nếu bạn bật hơn 20-50 skill cùng lúc.
   • Khuyến nghị bật chọn lọc.
   • Cân nhắc đóng gói skill liên quan thành "pack".

Chương 6: Tài nguyên và tham khảo

Nếu bạn đang xây skill đầu tiên, hãy bắt đầu với Hướng dẫn best practice, sau đó tra API docs khi cần.

Tài liệu chính thức

Tài nguyên Anthropic:

• Hướng dẫn best practice.
• Tài liệu Skills.
• Tài liệu tham chiếu API.
• Tài liệu MCP.

Blog:

• Giới thiệu Agent Skills.
• Blog kỹ thuật: Trang bị cho agent trong thế giới thực.
• Giải thích về Skills.
• Cách tạo Skills cho Claude.
• Xây Skills cho Claude Code.
• Cải thiện thiết kế frontend bằng Skills.

Ví dụ skill

Repo public:

• GitHub: anthropics/skills.
• Chứa các skill do Anthropic tạo, có thể tùy chỉnh.

Công cụ và tiện ích

skill-creator:

• Có sẵn trong Claude.ai và Claude Code.
• Có thể tạo skill từ mô tả.
• Có thể review và đưa khuyến nghị.
• Câu dùng mẫu: "Giúp tôi xây một skill bằng skill-creator".

Validation:

• skill-creator có thể đánh giá skill.
• Câu dùng mẫu: "Đánh giá skill này và đề xuất cải thiện".

Hỗ trợ

Với câu hỏi kỹ thuật:

• Diễn đàn cộng đồng trong Claude Developers Discord.

Với bug report:

• GitHub Issues: anthropics/skills/issues.
• Nên kèm tên skill, thông báo lỗi và bước tái hiện.

Phụ lục A: Checklist nhanh

Dùng checklist này để kiểm tra skill trước và sau khi upload. Nếu muốn bắt đầu nhanh hơn, dùng skill-creator để tạo bản nháp đầu tiên rồi chạy qua checklist.

Trước khi bắt đầu

• Đã xác định 2-3 use case cụ thể.
• Đã xác định tool cần dùng, built-in hoặc MCP.
• Đã đọc guide này và ví dụ skill.
• Đã lên kế hoạch cấu trúc thư mục.

Trong lúc phát triển

• Thư mục đặt tên bằng kebab-case.
• Có file SKILL.md đúng chính tả và hoa thường.
• YAML frontmatter có delimiter ---.
• Trường name dùng kebab-case, không khoảng trắng, không chữ hoa.
• Trường description có cả skill làm gì và khi nào dùng.
• Không có XML tag < >.
• Hướng dẫn rõ ràng và có thể hành động.
• Có xử lý lỗi.
• Có ví dụ.
• File tham khảo được link rõ.

Trước khi upload

• Đã test trigger với yêu cầu hiển nhiên.
• Đã test trigger với cách nói khác.
• Đã xác minh skill không được dùng với chủ đề không liên quan.
• Functional test đã pass.
• Tích hợp tool hoạt động nếu có.
• Đã nén thành .zip nếu cần.

Sau khi upload

• Kiểm thử trong hội thoại thật.
• Theo dõi under-triggering và over-triggering.
• Thu thập phản hồi người dùng.
• Cải tiến description và hướng dẫn qua nhiều vòng.
• Cập nhật version trong metadata.

Phụ lục B: YAML frontmatter

Trường bắt buộc

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

Được phép

• Kiểu YAML chuẩn: string, number, boolean, list, object.
• Metadata tùy chỉnh.
• Trường description dài tối đa 1024 ký tự.

Bị cấm

• Dấu ngoặc nhọn XML < >.
• Code execution trong YAML. Parser dùng safe YAML parsing.
• Tên skill bắt đầu bằng claude hoặc anthropic.

Ví dụ đầy đủ các trường tùy chọn

---
name: skill-name
description: [mô tả bắt buộc]
license: MIT
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"
metadata:
  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
---

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

Để xem các skill production-ready thể hiện pattern trong guide này, tham khảo:

• Skill tài liệu: tạo PDF, DOCX, PPTX, XLSX.
• Skill ví dụ: nhiều pattern workflow khác nhau.
• Thư mục skill đối tác: skill từ các đối tác như Asana, Atlassian, Canva, Figma, Sentry, Zapier.

Các repo này được cập nhật và có thêm ví dụ ngoài phạm vi tài liệu. Bạn có thể clone, chỉnh theo use case của mình và dùng làm template.