Anatomy Of A Skill

Level: L4 — AI Skills (Bài 2/12)

1. Mục tiêu học tập

Sau bài này, bạn có thể:

Vẽ được sơ đồ 1 Skill gồm những phần nào: SKILL.md (bắt buộc), file tài nguyên bổ sung (tùy chọn), script thực thi (tùy chọn).
Đọc hiểu YAML frontmatter của 1 SKILL.md thật.
Biết Skill được lưu ở đâu và điều đó quyết định ai dùng được nó.
Tự audit được cấu trúc 1 Skill có sẵn (dùng ví dụ thật của chính dự án này).

2. Khái niệm cốt lõi

Mỗi Skill là 1 thư mục, với SKILL.md là file bắt buộc duy nhất — mọi file khác đều tùy chọn:

my-skill/
├── SKILL.md           # Bắt buộc — hướng dẫn chính
├── template.md        # Tùy chọn — mẫu để Claude điền vào
├── examples/
│   └── sample.md       # Tùy chọn — ví dụ output mong muốn
└── scripts/
    └── validate.sh      # Tùy chọn — script Claude có thể chạy

[S74]

SKILL.md có 2 phần bắt buộc phân biệt rõ:

YAML frontmatter (giữa 2 dòng ---) — metadata: name, description (2 trường Anthropic công bố là bắt buộc/khuyến nghị) [S75], cùng nhiều trường tùy chọn khác (chi tiết ở bài 32/34).
Nội dung markdown — hướng dẫn thực sự Claude sẽ làm theo khi Skill được kích hoạt.

3 tầng nội dung, 3 thời điểm load khác nhau (progressive disclosure) — nguyên lý kiến trúc quan trọng nhất của toàn bộ Skill:

Tầng	Nội dung	Khi nào load	Chi phí ngữ cảnh
1 — Metadata	`name` + `description` trong frontmatter	Luôn luôn, ngay từ đầu phiên	~100 token/skill [S75]
2 — Instructions	Toàn bộ nội dung markdown chính của `SKILL.md`	Chỉ khi Skill được kích hoạt	Dưới 5.000 token [S75]
3+ — Resources/Scripts	File đính kèm (template, script, tài liệu tham khảo)	Chỉ khi được tham chiếu tới, đọc qua từng file riêng lẻ	Gần như không giới hạn — không tính vào ngữ cảnh nếu không được đọc [S75]

Đây là lý do 1 Skill có thể “cồng kềnh” (nhiều tài liệu tham khảo) mà không làm nặng ngữ cảnh mỗi phiên — chỉ tầng 1 luôn có mặt, tầng 2-3 chỉ xuất hiện khi thật sự cần.

3. Tại sao nội dung này quan trọng

Hiểu đúng “bản đồ” 4 thành phần (frontmatter, instructions, resources, scripts) là điều kiện để bạn tự đọc/tự viết được bất kỳ Skill nào sau này — bài 35-40 sẽ liên tục quay lại đúng 4 thành phần này. Không hiểu đúng cấu trúc dễ dẫn tới lỗi phổ biến nhất người mới hay mắc: nhồi hết mọi thứ vào 1 file SKILL.md duy nhất thay vì tách ra đúng tầng, khiến Skill vừa khó bảo trì vừa tốn ngữ cảnh không cần thiết.

4. Cơ chế hoạt động

Khi Skill được kích hoạt, Claude đọc SKILL.md qua lệnh bash thực sự (không phải “load ngầm”) — nghĩa là về mặt kỹ thuật, đây là thao tác đọc file filesystem, không phải 1 API đặc biệt. Nếu nội dung SKILL.md tham chiếu tới file khác, Claude đọc thêm file đó cũng qua bash, chỉ khi thực sự cần tới. Khi chạy 1 script đính kèm, Claude chạy qua bash và chỉ nhận kết quả đầu ra — bản thân mã nguồn script không đi vào ngữ cảnh [S74] [S75]. Đây là lý do 1 script có thể chứa hàng nghìn dòng code mà không tốn 1 token ngữ cảnh nào nếu không được chạy.

Tên lệnh gõ sau / (trong Claude Code) lấy từ tên thư mục, không phải trường name trong frontmatter (trừ 1 ngoại lệ: Skill nằm ở gốc 1 plugin) [S74] — điểm dễ gây nhầm nếu bạn đổi name trong frontmatter mà tưởng lệnh gọi cũng đổi theo.

Vị trí lưu quyết định phạm vi chia sẻ:

Vị trí	Phạm vi áp dụng
Enterprise (managed settings)	Toàn bộ người dùng trong tổ chức
Personal (`~/.claude/skills/`)	Mọi project của riêng bạn
Project (`.claude/skills/`)	Chỉ project này
Plugin (`<plugin>/skills/`)	Nơi plugin được bật
[S74]

5. Mental model

Tiếp nối ẩn dụ “hồ sơ đào tạo” từ bài 29, giờ zoom vào bên trong 1 hồ sơ cụ thể: hồ sơ đào tạo có bìa hồ sơ (frontmatter — tóm tắt ngắn gọn, không cần mở ra đọc hết), nội dung chính (instructions — chỉ đọc khi thật sự cần dùng tới hồ sơ này), và phụ lục đính kèm (resources/scripts — biểu mẫu, tài liệu tham khảo, công cụ, chỉ lật tới khi hướng dẫn chính bảo bạn lật tới).

6. Hướng dẫn từng bước

Cách tự audit cấu trúc 1 Skill có sẵn:

Tìm thư mục gốc của Skill — xác nhận có đúng 1 file SKILL.md.
Mở SKILL.md, đọc phần frontmatter — ghi lại name và description. Đây là những gì Claude “biết” về Skill này ngay cả khi chưa kích hoạt.
Đọc phần nội dung markdown còn lại — đây là hướng dẫn thực thi.
Liệt kê mọi file/thư mục khác trong Skill — với mỗi file, xác định: tài liệu tham khảo (resource) hay script thực thi (code)?
Kiểm tra SKILL.md có tham chiếu rõ ràng tới từng file phụ đó không — nếu có file phụ không được tham chiếu, Claude sẽ không biết khi nào nên đọc nó.

7. Ví dụ thực tế

Áp dụng đúng 5 bước ở mục 6 cho Skill vận hành chính dự án này:

.claude/skills/ai-mastery-bible/
├── SKILL.md                              ← Tầng 1+2: frontmatter (name,
│                                            description) + hướng dẫn quy
│                                            trình biên tập 12 bước
├── references/ (10 file .md)             ← Tầng 3: kiến thức, chỉ đọc khi
│   chapter-writing-system.md,              SKILL.md chỉ định
│   chapter-standard.md, ...
├── assets/ (2 file template)             ← Tầng 3: mẫu output
│   chapter-template.md,
│   research-matrix-row-template.md
└── scripts/
    └── check_source_access.sh            ← Tầng 3: script, chạy qua bash,
                                             không load mã nguồn vào ngữ cảnh

Đối chiếu đúng 4 thành phần đã học: SKILL.md (bắt buộc, có frontmatter với name: ai-mastery-bible và 1 description dài mô tả rõ khi nào nên dùng) + references/ (tầng 3) + assets/ (tầng 3) + scripts/ (tầng 3). Đây chính là ví dụ đang chạy thật đã được giới thiệu ở bài 29.

8. Prompt/template/workflow

ten-skill-cua-ban/
├── SKILL.md              # Bắt buộc — viết ở bài 32
├── REFERENCE.md          # Tùy chọn — nếu có kiến thức nền cần tra cứu
├── examples/
│   └── example-01.md     # Tùy chọn — ví dụ output mẫu
└── scripts/
    └── (nếu cần tự động hoá 1 bước cụ thể)

Câu hỏi tự kiểm tra trước khi coi 1 Skill “đủ thành phần”:

SKILL.md có frontmatter với name + description chưa?
Mọi file phụ có được tham chiếu rõ trong SKILL.md chưa?
SKILL.md có dưới 500 dòng không (khuyến nghị chính thức)? [S74]

9. Visual hoặc diagram cần thiết

Hình 4.2 — 3 tầng progressive disclosure: Frontmatter (luôn tải) → Instructions (tải khi kích hoạt) → Resources/Scripts (tải khi cần).

10. Bài tập thực hành

Mở thư mục .claude/skills/ai-mastery-bible/ (hoặc bất kỳ Skill nào bạn đang có quyền truy cập) và áp dụng đúng 5 bước audit ở mục 6.
Vẽ lại cấu trúc thư mục Skill đó theo đúng 3 tầng progressive disclosure.
Với 1 trong 4 Skill dựng sẵn của Anthropic (pptx/xlsx/docx/pdf — bài 29), thử đoán: Skill đó có khả năng chứa những loại resources/scripts nào? (Bài tập suy luận dựa trên cấu trúc đã học.)

11. Checklist

Vẽ được đúng cấu trúc 4 thành phần của 1 Skill.
Đọc hiểu 1 frontmatter YAML thật (name, description).
Giải thích được vì sao progressive disclosure giúp Skill "cồng kềnh" mà không tốn ngữ cảnh.
Tự audit được 1 Skill có sẵn theo đúng 5 bước ở mục 6.

12. Lỗi thường gặp

Nhồi hết mọi thứ vào 1 file SKILL.md thay vì tách resources/scripts ra riêng — vi phạm khuyến nghị “dưới 500 dòng” [S74].
Tạo file phụ nhưng không tham chiếu trong SKILL.md — Claude sẽ không biết file đó tồn tại hoặc khi nào nên đọc.
Nhầm name trong frontmatter với tên lệnh gõ sau / — 2 thứ này không phải lúc nào cũng giống nhau (mục 4).

13. Giới hạn & khi nào KHÔNG nên áp dụng

Bài này chỉ dạy “bản đồ” — không dạy cách viết nội dung instructions tốt (bài 32), không dạy cách tổ chức resources hiệu quả (bài 33), không dạy thiết kế input/output (bài 34).
Không áp dụng cho Prompt đơn lẻ hay nội dung Project Knowledge base (Level 2/3) — đó là 2 kiến trúc khác hẳn, không có SKILL.md.

14. An toàn & quản trị (Safety/Governance)

Vì tầng 3 (resources/scripts) có thể chứa code thực thi được, việc audit cấu trúc 1 Skill (mục 6) cũng chính là bước đầu tiên của việc kiểm tra an toàn trước khi tin dùng 1 Skill từ nguồn không phải do bạn tự viết — xem lại toàn bộ file trong Skill, không chỉ đọc SKILL.md, đặc biệt chú ý script trong thư mục scripts/ [S75]. Ràng buộc đặt tên cũng đáng lưu ý: name không được chứa từ “anthropic” hay “claude” [S75].

15. Best practices

Giữ SKILL.md dưới 500 dòng — đẩy chi tiết ra file tham khảo riêng [S74].
Luôn tham chiếu rõ ràng file phụ từ SKILL.md.
Khi audit 1 Skill lạ, luôn đọc hết mọi file trong thư mục trước khi tin dùng, không chỉ đọc SKILL.md.

16. Nội dung nâng cao (không bắt buộc)

Claude Code hỗ trợ Skill lồng nhau theo thư mục con (monorepo) — 1 Skill ở gốc dự án và 1 Skill cùng tên ở thư mục con có thể cùng tồn tại, phân biệt qua tên đủ đường dẫn (apps/web:deploy); và hỗ trợ symlink — 1 thư mục Skill có thể là symlink trỏ tới nơi khác trên đĩa [S74].

17. Nguồn tham khảo

[S74] Extend Claude with skills, Anthropic (code.claude.com/docs/en/skills) — cấu trúc thư mục, quy tắc đặt tên lệnh, khuyến nghị 500 dòng, Skill lồng nhau/symlink · [S75] Agent Skills (Overview), Anthropic — bảng 3 tầng progressive disclosure, ràng buộc name/description, cảnh báo an toàn.

18. Ngày kiểm chứng

Toàn bộ claim kỹ thuật kiểm chứng qua nguồn Tier 1 (S74, S75) ngày 2026-07-12. Cấu trúc thư mục ví dụ (ai-mastery-bible) xác nhận trực tiếp bằng cách đọc filesystem thực tế cùng ngày.