Xây dựng Skills cho Claude — Phần 2: Thiết kế và Lập kế hoạch

Dịch và biên soạn từ "The Complete Guide to Building Skills for Claude" của Anthropic.

Ở Phần 1, bạn đã hiểu skill là gì và các nguyên tắc nền tảng. Giờ là lúc bắt tay vào thiết kế. Nguyên tắc quan trọng nhất: đừng viết code trước, hãy bắt đầu từ use case.

Bắt đầu từ Use Case

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ần hỗ trợ. Một use case tốt cần trả lời được các câu hỏi:

• Người dùng muốn hoàn thành việc gì?
• Quy trình nhiều bước nào cần thực hiện?
• Cần công cụ gì (built-in hay MCP)?
• Kiến thức chuyên môn hay best practices nào cần nhúng vào?

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ên kế hoạch sprint" hoặc "tạo sprint tasks"
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 và capacity của team
  3. Đề xuất thứ tự ưu tiên task
  4. Tạo tasks trong Linear với labels và estimates phù hợp
Kết quả: Sprint được lên kế hoạch đầy đủ với tasks đã tạo

Ba loại Skill phổ biến

Anthropic nhận thấy ba loại use case phổ biến nhất trong thực tế:

Loại 1: Tạo tài liệu và nội dung (Document and Asset Creation)

Dùng để tạo ra output nhất quán, chất lượng cao: tài liệu, bài thuyết trình, ứng dụng, thiết kế, code.

Ví dụ thực tế: Skill frontend-design, hoặc các skill tạo file docx, pptx, xlsx.

Kỹ thuật chính:

• Nhúng style guide và tiêu chuẩn thương hiệu
• Template cấu trúc cho output nhất quán
• Checklist chất lượng trước khi hoàn thiện
• Không cần công cụ bên ngoài, dùng khả năng built-in của Claude

Ví dụ Việt Nam: Bạn làm content marketing cho nhiều khách hàng. Tạo skill "blog-writer" với style guide riêng cho từng khách: giọng điệu, độ dài, cấu trúc bài viết, từ khoá SEO cần nhúng. Mỗi lần viết bài mới, Claude tự động áp dụng đúng chuẩn.

Loại 2: Tự động hoá quy trình (Workflow Automation)

Dùng cho quy trình nhiều bước cần phương pháp luận nhất quán, bao gồm phối hợp 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.

Kỹ thuật chính:

• Quy trình từng bước với các điểm kiểm tra (validation gates)
• 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 liên tục (iterative refinement loops)

Loại 3: Tăng cường MCP (MCP Enhancement)

Cung cấp hướng dẫn quy trình để tăng cường khả năng truy cập công cụ mà MCP server cung cấp.

Ví dụ thực tế: Skill sentry-code-review của Sentry, tự động phân tích và sửa bug trong GitHub Pull Requests bằng dữ liệu giám sát lỗi từ MCP server.

Kỹ thuật chính:

• Phối hợp nhiều lệnh MCP tuần tự
• Nhúng kiến thức chuyên môn
• Cung cấp ngữ cảnh mà người dùng không cần chỉ định
• Xử lý lỗi cho các vấn đề MCP phổ biến

Xác định tiêu chí thành công

Làm sao biết skill của bạn hoạt động tốt? Anthropic khuyến nghị kết hợp cả chỉ số định lượng và định tính. Đây là mục tiêu để phấn đấu, không phải ngưỡng chính xác.

Chỉ số định lượng

• Skill kích hoạt đúng trên 90% truy vấn liên quan — Cách đo: Chạy 10-20 truy vấn thử, theo dõi tỷ lệ skill tự động tải so với phải gọi thủ công
• Hoàn thành quy trình trong X lượt gọi công cụ — Cách đo: So sánh cùng tác vụ có và không có skill, đếm số tool calls và tổng token
• 0 lần gọi API thất bại trong mỗi quy trình — Cách đo: Theo dõi log MCP server, kiểm tra tỷ lệ retry và mã lỗi

Chỉ số định tính

• Người dùng không cần prompt thêm về bước tiếp theo — Cách đánh giá: Trong quá trình test, ghi nhận tần suất bạn phải redirect hoặc làm rõ
• Quy trình hoàn thành không cần người dùng sửa — Cách đánh giá: Chạy cùng một yêu cầu 3-5 lần, so sánh output về cấu trúc và chất lượng
• Kết quả nhất quán giữa các 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 không?

YAML Frontmatter chuyên sâu

Ở Phần 1, bạn đã biết cấu trúc cơ bản. Giờ hãy đi sâu vào cách viết description hiệu quả, yếu tố quyết định skill có được kích hoạt hay không.

Công thức viết description

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

Ví dụ description tốt

# Tốt - cụ thể và 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. 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 - bao gồm trigger phrases
description: Quản lý quy trình dự án Linear bao 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 đề cập "sprint", "Linear tasks", "project planning", hoặc yêu cầu "create tickets".

# Tốt - giá trị rõ ràng
description: Quy trình onboarding 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. Dùng khi người dùng nói "onboard new customer", "set up subscription", hoặc "create PayFlow account".

Ví dụ description tệ

# Quá chung chung
description: Helps with projects.

# Thiếu trigger
description: Creates sophisticated multi-page documentation systems.

# Quá kỹ thuật, không có trigger người dùng
description: Implements the Project entity model with hierarchical relationships.

Cấu trúc YAML đầy đủ

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

Viết Instructions hiệu quả

Sau phần frontmatter là nội dung hướng dẫn chính bằng Markdown. Anthropic khuyến nghị cấu trúc sau:

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

# Tên Skill

## Instructions
### Bước 1: [Bước đầu tiên]
Giải thích rõ ràng việc cần làm.

python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [mo ta ket qua mong doi]

### Bước 2: [Bước tiếp theo]
...

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

## Troubleshooting
Lỗi: [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]

Best Practices khi viết Instructions

Cụ thể và có thể hành động

# Tốt
Chạy `python scripts/validate.py --input {filename}` để kiểm tra định dạng dữ liệu.
Nếu validation thất bại, các lỗi phổ biến bao gồm:
- Thiếu trường bắt buộc (thêm vào file CSV)
- Định dạng ngày sai (dùng YYYY-MM-DD)

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

Tham chiếu tài liệu đi kèm rõ ràng

Trước khi viết query, tham khảo `references/api-patterns.md` về:
- Hướng dẫn rate limiting
- Patterns phân trang
- Mã lỗi và cách xử lý

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 chi tiết sang thư mục references/ và liên kết đến.

Bao gồm xử lý lỗi

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

Mẹo thực tế cho developer Việt Nam

• Viết description bằng tiếng Anh nếu skill dành cho cộng đồng quốc tế, hoặc tiếng Việt nếu dùng nội bộ
• Bao gồm trigger phrases bằng cả hai ngôn ngữ nếu team bạn dùng song ngữ
• Bắt đầu nhỏ: Tập trung vào một tác vụ duy nhất cho đến khi Claude thực hiện thành công, rồi mới mở rộng. Cách này nhanh hơn nhiều so với test rộng ngay từ đầu
• Dùng skill-creator: Nếu bạn có MCP server và biết rõ 2-3 workflow chính, bạn có thể build và test skill trong một buổi, thường trong 15-30 phút

Tổng kết Phần 2

Bạn đã nắm được cách:

• Xác định use case trước khi code
• Phân loại skill theo 3 loại: Document Creation, Workflow Automation, MCP Enhancement
• Đặt tiêu chí thành công cả định lượng và định tính
• Viết YAML frontmatter và description hiệu quả
• Cấu trúc instructions rõ ràng, có thể hành động

Trong Phần 3, chúng ta sẽ tìm hiểu cách test và tối ưu skill: 3 cấp độ testing, so sánh hiệu suất, và cách iterate dựa trên feedback.