Canonical HTML: https://claudewiki.org/claude-skills/bai-4.html

# Viết Skill hiệu quả công thức Description vàng

Cách viết skill Claude AI hiệu quả bắt đầu từ description — trường quan trọng nhất, quyết định Claude có chọn đúng skill của bạn giữa hàng trăm skill khác hay không.

### ❓ cách viết skill claude ai hiệu quả — trả lời nhanh

Công thức description vàng: **[Hành động skill làm] + [Khi nào dùng / ngữ cảnh] + [Từ khoá kích hoạt]**. Luôn viết ở **ngôi thứ ba** vì description được chèn thẳng vào system prompt của Claude.

### 🎯 Mục tiêu bài học

- Viết description theo công thức What + When + Trigger để Claude chọn đúng skill.
- Đặt tên skill theo quy ước dạng danh động từ (gerund) mà Anthropic khuyến nghị.
- Áp dụng 4 best practice cho phần thân SKILL.md để tiết kiệm context.
- Chọn đúng mức độ tự do — khi nào viết hướng dẫn mở, khi nào bắt buộc script cứng.

CÔNG THỨC

## Ba thành phần của một description tốt

ĐỐI CHIẾU

## Mô tả tồi và mô tả chuẩn

|  | ⛔ BAD — mô tả tồi | ✅ GOOD — mô tả chuẩn |
|---|---|---|
| **Nội dung** | "Giúp làm báo cáo cho các dự án." | "Tạo báo cáo tuần dạng BLUF từ dữ liệu KPI. Dùng khi người dùng tải lên file Excel KPI hoặc yêu cầu tóm tắt tuần, weekly report, tổng kết tuần." |
| **Vấn đề / Ưu điểm** | Quá chung chung. Bắt nhầm trong mọi ngữ cảnh có chữ "báo cáo" — kể cả báo cáo tài chính hay báo cáo sự cố. | Rõ hành động, rõ ngữ cảnh, có từ khoá thực tế người dùng gõ. Kích hoạt chính xác đúng lúc. |
| **Ngôi kể** | "Tôi có thể giúp bạn làm báo cáo" — ngôi thứ nhất, gây nhiễu | "Tạo báo cáo tuần..." — ngôi thứ ba, thống nhất với system prompt |
| **Độ dài** | 7 từ — không đủ tín hiệu để phân biệt | Khoảng 40 từ — vẫn xa giới hạn 1.024 ký tự |

### ⚠️ Vì sao bắt buộc ngôi thứ ba

Description được **chèn thẳng vào system prompt** của Claude. Viết "Tôi có thể giúp bạn..." hay "Bạn có thể dùng cái này để..." tạo ra xung đột ngôi kể và gây lỗi khi Claude quyết định chọn skill. Luôn viết: *"Xử lý file Excel và sinh báo cáo"* — không phải *"Tôi giúp bạn xử lý file Excel"*.

QUY ƯỚC ĐẶT TÊN

## Anthropic khuyến nghị dạng danh động từ

##### Dạng gerund (nên dùng)

`processing-pdfs`, `analyzing-spreadsheets`, `writing-documentation` — mô tả rõ hoạt động skill cung cấp.

##### Dạng cụm danh từ (chấp nhận)

`pdf-processing`, `bao-cao-tuan`, `content-da-kenh` — vẫn rõ ràng, phổ biến trong thực tế.

##### Tên mơ hồ (tránh)

`helper`, `utils`, `tools`, `documents`, `data` — Claude không biết khi nào nên gọi.

##### Từ khoá cấm

`claude-tools`, `anthropic-helper` — chứa từ dành riêng, bị từ chối khi validate.

BỐN BEST PRACTICE

## Viết phần thân SKILL.md

#### Cụ thể, không mơ hồ

Hướng dẫn rõ từng bước. Định dạng đầu ra phải quy định chi tiết. Tránh từ ngữ như "phù hợp", "hợp lý", "nếu cần" mà không nói rõ tiêu chí.

#### Xử lý lỗi tường minh

Dạy Claude phản ứng khi thiếu dữ liệu đầu vào. Ví dụ: *"Nếu file upload trống hoặc thiếu cột doanh thu, hỏi lại người dùng thay vì tự suy đoán số liệu."*

#### Tham chiếu, không dán inline

Đừng dán toàn bộ SOP 40 trang vào SKILL.md. Trỏ đường dẫn tới `references/brand-guide.md` để file chính luôn gọn gàng.

#### Giữ file chính ngắn

Tài liệu chính thức khuyến nghị **thân SKILL.md dưới 500 dòng** và tầng hướng dẫn dưới **5.000 token**. Vượt ngưỡng thì tách file.

MỨC ĐỘ TỰ DO

## Khớp độ chi tiết với mức độ mong manh của tác vụ

#### Tự do cao — hướng dẫn bằng văn xuôi

Dùng khi nhiều cách tiếp cận đều đúng và quyết định phụ thuộc ngữ cảnh. Ví dụ review code: nêu tiêu chí cần xem xét, để Claude tự chọn cách. Ví như *cánh đồng trống — nhiều đường đều tới đích*.

#### Tự do trung bình — pseudocode hoặc script có tham số

Dùng khi đã có pattern ưa thích nhưng vẫn chấp nhận biến thể. Ví dụ hàm sinh báo cáo với tham số định dạng và có kèm biểu đồ hay không.

#### Tự do thấp — script cứng, ít hoặc không tham số

Dùng khi thao tác mong manh, dễ sai, và tính nhất quán là sống còn. Ví dụ migration database: *"Chạy chính xác lệnh này. Không sửa lệnh, không thêm cờ."* Ví như *cây cầu hẹp hai bên là vực*.

CÂU HỎI THƯỜNG GẶP

## FAQ — 3 câu hỏi thường gặp về cách viết skill claude ai hiệu quả

### **Công thức viết description tốt là gì?**

**[Hành động skill làm] + [Khi nào dùng] + [Từ khoá kích hoạt]**. Ví dụ chuẩn: *"Tạo báo cáo tuần dạng BLUF từ dữ liệu KPI. Dùng khi người dùng tải lên file Excel KPI hoặc yêu cầu tóm tắt tuần, weekly report."*

### **Vì sao description phải viết ở ngôi thứ ba?**

Vì description được **chèn thẳng vào system prompt** của Claude. Viết "Tôi có thể giúp bạn..." hay "Bạn có thể dùng cái này..." tạo xung đột ngôi kể và gây lỗi khi Claude chọn skill. Luôn viết: *"Xử lý file Excel và sinh báo cáo"*.

### **Khi nào nên viết hướng dẫn mở, khi nào bắt buộc script cứng?**

Khớp độ chi tiết với mức mong manh của tác vụ. **Tự do cao** khi nhiều cách đều đúng (như review code) — ví như cánh đồng trống. **Tự do thấp** khi thao tác dễ sai và tính nhất quán là sống còn (như migration database) — ví như cây cầu hẹp hai bên là vực.

**Nguồn:** Bài viết biên soạn dựa trên tài liệu *Xây dựng bộ Skills cho Claude* (Anthropic Academy, bản tiếng Việt do Nguyen Ngoc Tuan trình bày), đã viết lại và **đối chiếu với tài liệu Agent Skills chính thức của Anthropic** (platform.claude.com và code.claude.com), cập nhật 06/11/2026. Mọi số liệu kỹ thuật lấy theo tài liệu chính thức.

**Đối chiếu thông tin Claude: 06/11/2026.** Xem [các thay đổi, phạm vi truy cập và nguồn chính thức](https://claudewiki.org/cap-nhat-claude.html). Tính năng có thể triển khai theo đợt, khu vực và cấu hình tổ chức.

[← Bài trước**Bài 3 · Cấu trúc SKILL.md**](https://claudewiki.org/claude-skills/bai-3.html) · [Bài tiếp theo →**Bài 5 · Kiểm thử và lặp lại**](https://claudewiki.org/claude-skills/bai-5.html)
