Mổ xẻ cấu trúc một Skill: SKILL.md, scripts, references, assets

1. Sơ đồ thư mục đầy đủ

Một Skill là một thư mục có cấu trúc như sau:

ten-skill-cua-ban/
├── SKILL.md          # Bắt buộc — file hướng dẫn chính
├── scripts/          # Tùy chọn — mã thực thi
│   ├── process_data.py
│   └── validate.sh
├── references/       # Tùy chọn — tài liệu tham chiếu
│   ├── api-guide.md
│   └── examples/
└── assets/           # Tùy chọn — mẫu, template
    └── report-template.md

Chỉ SKILL.md là bắt buộc. Ba thư mục còn lại được thêm vào khi workflow cần đến.

2. Vai trò từng thành phần

2a. SKILL.md (bắt buộc)

File trung tâm, viết bằng Markdown, gồm hai phần:

• Phần khai báo YAML ở đầu file — quyết định khi nào Skill được kích hoạt (sẽ phân tích kỹ ở Bài 4).
• Phần thân — chứa hướng dẫn chi tiết Claude cần làm theo (Bài 5).

2b. scripts/ (tùy chọn)

Chứa mã thực thi như Python hoặc Bash. Dùng khi workflow cần xử lý xác định, có tính tự động — ví dụ một script kiểm tra định dạng dữ liệu đầu vào.

Một nguyên tắc quan trọng: với các kiểm tra mang tính then chốt (validation), nên đóng gói một script thực hiện kiểm tra bằng mã, thay vì chỉ dựa vào hướng dẫn bằng lời. Lý do: mã chạy có tính xác định, còn việc diễn giải ngôn ngữ thì không.

2c. references/ (tùy chọn)

Chứa tài liệu tham chiếu chi tiết. Đây là "lớp 3" trong cơ chế progressive disclosure đã nói ở Bài 1: Claude chỉ tìm đến và đọc khi cần. Mục tiêu là giữ SKILL.md gọn, đẩy phần dài vào đây.

Ví dụ nội dung phù hợp đặt trong references/: hướng dẫn phân trang API, bảng mã lỗi, hướng dẫn xử lý giới hạn truy vấn.

2d. assets/ (tùy chọn)

Chứa các tài nguyên dùng trong kết quả đầu ra: template báo cáo, font, icon. Khác với references/ (Claude đọc để hiểu), assets/ là vật liệu được dùng trực tiếp trong sản phẩm cuối.

3. Quy tắc đặt tên — phần dễ sai nhất

Đây là nhóm quy tắc gây lỗi nhiều nhất khi upload Skill. Cần tuân thủ chính xác.

3a. Tên file SKILL.md

• Phải đúng chính xác SKILL.md (phân biệt hoa thường).
• Không chấp nhận biến thể: SKILL.MD, skill.md, Skill.md đều sai.

3b. Tên thư mục Skill

Dùng kebab-case (chữ thường, nối bằng dấu gạch ngang):

3c. Không có file README.md trong thư mục Skill

• Không đặt README.md bên trong thư mục Skill.
• Mọi tài liệu nằm trong SKILL.md hoặc references/.
• Ngoại lệ: khi phân phối qua GitHub, vẫn nên có README ở cấp repo cho người đọc — nhưng đó là file riêng, không nằm trong thư mục Skill.

4. Ví dụ minh họa: phác cấu trúc một Skill cho tester

Giả sử cần một Skill sinh test case từ user story. Cấu trúc có thể như sau:

sinh-test-case-tu-user-story/
├── SKILL.md                        # Hướng dẫn chính + điều kiện kích hoạt
├── references/
│   └── test-case-template.md       # Template test case chuẩn của team
└── assets/
    └── testrail-import-format.csv  # Mẫu định dạng để import vào TestRail

Trong ví dụ này:

• SKILL.md dạy Claude khi nào và làm thế nào để sinh test case.
• references/test-case-template.md chứa quy ước viết test case để Claude tham chiếu khi cần.
• assets/testrail-import-format.csv là mẫu định dạng đầu ra.

Skill thực tế sẽ được dựng đầy đủ ở Bài 6 của chuỗi.

5. Checklist cấu trúc trước khi viết nội dung

• Thư mục đặt tên kebab-case, không dấu cách, không gạch dưới, không viết hoa.
• Có file SKILL.md (đúng chính tả, đúng hoa thường).
• Không có README.md bên trong thư mục Skill.
• Đã xác định có cần scripts/, references/, assets/ hay không.
• Tài liệu chi tiết được đẩy vào references/ thay vì nhồi hết vào SKILL.md.

6. Tổng kết bài 3

• Skill là một thư mục; chỉ SKILL.md là bắt buộc.
• scripts/ cho mã thực thi, references/ cho tài liệu tham chiếu nạp theo nhu cầu, assets/ cho vật liệu dùng trong đầu ra.
• Quy tắc đặt tên cần tuân thủ tuyệt đối: SKILL.md đúng chính tả, thư mục kebab-case, không README.md bên trong.
• Đẩy nội dung dài vào references/ để giữ SKILL.md gọn — đúng tinh thần progressive disclosure.

Bài tiếp theo (Bài 4): Viết phần khai báo YAML — thành phần quyết định Skill có được kích hoạt đúng lúc hay không, cùng cách viết trường description hiệu quả.