Bên trong một Claude Skill — SKILL.md, cơ chế nạp dần và bảo mật

Playbook này dành cho ai?

Bạn đã đọc Skill, Prompt, Project, MCP — chọn cách dạy AI đúng việc và biết khi nào nên viết skill. Trước khi tạo skill đầu tiên, bạn muốn hiểu bản chất của skill — không phải một khái niệm trừu tượng, mà mở nó ra xem nó lưu gì, file nào quan trọng, AI đọc theo thứ tự nào.

Hiểu cấu trúc bên trong giúp bạn tạo skill nhanh hơn khi bắt tay vào bài Tạo Claude Skill đầu tiên (không phải đoán file nào để ở đâu), gỡ lỗi nhanh hơn ở bài Debug + maintain skill (biết lỗi nằm ở frontmatter, body, hay references), và an toàn khi cài skill từ người khác — đọc được mã và phần hướng dẫn trước khi cho phép chạy trên máy.

Bạn sẽ đạt được gì?

• Đọc và hiểu được một file SKILL.md bất kỳ — frontmatter + body, cái nào bắt buộc, cái nào tuỳ chọn
• Hiểu progressive disclosure 3 tầng — cơ chế cho phép một agent dùng hàng trăm skill mà không hết token
• Biết khi nào cần thêm thư mục references/, scripts/, assets/ (và khi nào không)
• Có checklist 3 bước để kiểm tra một skill từ bên ngoài trước khi cài lên máy

Bạn cần chuẩn bị gì?

• Đã đọc bài Skill, Prompt, Project, MCP — chọn cách dạy AI đúng việc — hoặc ít nhất biết "skill là cái lấp khoảng trống procedural memory"
• Một trình soạn thảo đọc được markdown (Notepad cũng được)
• Tuỳ chọn: mở folder .claude/skills/ trong một project Claude Code có sẵn (hoặc xem repo công khai anthropic/skills) để vừa đọc bài vừa nhìn skill thật

Bức tranh toàn cảnh

Một Claude Skill thực chất chỉ là một folder. Trong folder bắt buộc có 1 file duy nhất: SKILL.md. Có thể kèm 3 thư mục con tuỳ chọn — references/, scripts/, assets/ — skill nào phức tạp thì mới cần các thư mục này.

Đây là ưu điểm lớn trong thiết kế của skill: viết bằng ngôn ngữ tự nhiên, giao tiếp như bình thường, không cần cài thêm phần mềm nào khác. Bạn copy folder SKILL sang nền tảng AI khác, skill chạy được ở đó (miễn nền tảng hỗ trợ chuẩn SKILL.md).

Điểm đặc biệt là cách agent đọc folder này. Nó không đọc cả folder vào bộ nhớ một lần — nó nạp dần theo nhu cầu, qua 3 tầng thông tin. Hiểu cơ chế nạp dần này là chìa khoá để bạn không phải lo "mình cài 50 skill thì có nặng quá không?".

1. Skill = 1 folder + 1 file bắt buộc

Toàn bộ cấu trúc một skill nằm trong một thư mục. Lấy ví dụ skill tom-tat-email:

tom-tat-email/
├── SKILL.md            ← file chính, BẮT BUỘC
├── references/         ← tuỳ chọn — tài liệu phụ
│   └── giong-van.md
├── scripts/            ← tuỳ chọn — code thực thi
│   └── extract_pdf.py
└── assets/             ← tuỳ chọn — file tĩnh
    └── email-template.html

Bắt buộc chỉ có một thứ: file SKILL.md ngay trong root folder. Nếu đặt tên khác (skill.md, instructions.md, README.md), agent sẽ không nhận diện được skill của bạn.

Ba thư mục phụ là tuỳ chọn. Một skill đơn giản như "tóm tắt email theo định dạng chuẩn" chỉ cần mỗi SKILL.md — không cần references/, scripts/, hay assets/. Mục 5 dưới đây bàn khi nào thực sự cần thêm chúng.

Tên folder = tên skill trong nhiều nền tảng. Đặt tên ngắn, dùng chữ thường, nối bằng dấu gạch ngang, thể hiện rõ công việc — tom-tat-email; tránh đặt tên folder chung chung, mơ hồ như skill-1 hay MySkill_v2.

Một skill thật trông như thế nào trong trình soạn thảo:

Đây là skill youtube-thumbnail mình viết để Claude soạn câu lệnh tạo ảnh thumbnail YouTube theo màu brand của CoreLearn. Đối chiếu với cây thư mục mẫu phía trên: cùng cấu trúc, chỉ khác là folder thật + file thật trong trình soạn thảo thật. Để ý: folder của skill này chỉ có đúng một file SKILL.md, không có references/, scripts/, hay assets/. Đó là minh hoạ cho điểm phía trên: một skill đơn giản không cần 3 subfolder phụ. Khi nào thực sự cần những thư mục này, mục 5 dưới đây sẽ bàn rõ.

2. Frontmatter: name + description quyết định khi nào skill chạy

File SKILL.md gồm 2 phần. Phần đầu tiên là YAML frontmatter — vài dòng metadata nằm giữa hai dấu ---:

---
name: tom-tat-email
description: Tóm tắt email hoặc tin nhắn dài thành bản ngắn gọn bằng tiếng Việt.
  Dùng khi người dùng gửi nội dung email, báo cáo, hoặc tin nhắn cần tóm tắt.
---
 
# (body bắt đầu ở đây)
...

Lưu ý: YAML chỉ là một cách trình bày thông tin theo quy ước — mỗi dòng một cặp "tên: giá trị", tất cả đặt giữa hai dấu ---. Bạn không cần học YAML: khi tạo skill, Claude tự viết phần này cho bạn (xem Tạo Claude Skill đầu tiên), bạn chỉ cần đọc hiểu là đủ.

Chỉ hai trường thông tin bắt buộc: