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

> Bài 3 trong chuỗi 8 bài "Xây dựng Skill cho Claude Code dành cho tester". Bài này phân tích từng thành phần của một Skill và các quy tắc đặt tên bắt buộc. Nắm chắc bài này trước khi viết nội dung Skill ở các bài sau.

- **URL canonical**: https://itlearn.edu.vn/blog/mo-xe-cau-truc-mot-skill-skill-md-scripts-references-assets
- **Published**: 2026-06-15T22:56:00+07:00
- **Modified**: 2026-06-16T01:06:46+07:00
- **Author**: IT LEARN
- **Category**: AI for Tester (https://itlearn.edu.vn/blog/cat/ai-for-tester)
- **Reading time**: 7 phút
- **Source site**: IT LEARN — Học viện Software Testing tiếng Việt

---

## 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):

Cách viết

Hợp lệ?

`notion-project-setup`

Đúng

`Notion Project Setup` (có dấu cách)

Sai

`notion_project_setup` (gạch dưới)

Sai

`NotionProjectSetup` (viết hoa)

Sai

### 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:

 

 

text

`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ả.