Cấu trúc SKILL.md
YAML frontmatter và quy tắc bắt buộc
Cấu trúc file SKILL.md gồm YAML frontmatter và phần thân markdown. Hệ thống kiểm tra rất khắt khe — sai tên file hoặc thêm trường lạ là skill bị từ chối ngay.
🎯 Mục tiêu bài học
- Viết đúng YAML frontmatter với 6 trường hợp lệ theo chuẩn Agent Skills.
- Nắm giới hạn ký tự và ký tự cấm cho từng trường — tránh bị từ chối upload.
- Tuân thủ quy tắc đặt tên file và thư mục để skill được nhận diện.
- Dùng allowed-tools để khoá giới hạn quyền thực thi, giảm rủi ro bảo mật.
YAML frontmatter đầy đủ 6 trường
---
name: bao-cao-tuan-chuan
description: Tạo báo cáo tuần theo khung BLUF từ dữ liệu KPI. Dùng khi
người dùng tải lên file Excel KPI, xin bản tóm tắt tuần, hoặc nhắc tới
báo cáo tuần, weekly report, tổng kết tuần.
license: MIT
compatibility: Cần Claude.ai hoặc Claude Code có bật code execution.
metadata:
author: Transform Group
version: 1.0.0
allowed-tools: Read, Write, Bash
---
# Báo cáo tuần chuẩn
## Quy trình
1. Đọc file KPI người dùng cung cấp...Chuẩn Agent Skills chỉ chấp nhận đúng 6 trường này
name — BẮT BUỘC
Tối đa 64 ký tự. Chỉ chữ thường, số và dấu gạch ngang. Không chứa thẻ XML. Không chứa từ khoá claude hoặc anthropic.
description — BẮT BUỘC
Không được rỗng, tối đa 1.024 ký tự. Không chứa thẻ XML. Phải nói cả skill làm gì và khi nào dùng.
license — tùy chọn
Giấy phép áp dụng cho skill, ví dụ MIT. Thuộc chuẩn Agent Skills. Quan trọng khi bạn chia sẻ skill ra ngoài tổ chức.
compatibility — tùy chọn
Yêu cầu môi trường: sản phẩm hỗ trợ, điều kiện hệ thống. Tối đa 500 ký tự. Ghi rõ để người nhận biết skill chạy được ở đâu.
metadata — tùy chọn
Map YAML tự do cho dữ liệu riêng của bạn: author, version, mã danh mục nội bộ. Công cụ của bạn đọc, Claude không tác động.
allowed-tools — tùy chọn
Danh sách công cụ Claude được dùng mà không cần hỏi phép trong lượt gọi skill. Đây là rào chắn bảo mật theo nguyên tắc đặc quyền tối thiểu.
⛔ Thêm trường lạ = lỗi ngay khi validate
Upload skill có trường ngoài danh sách 6 trường trên sẽ báo lỗi kiểu: Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name. Riêng Claude Code chấp nhận thêm một số trường mở rộng (như disable-model-invocation, argument-hint, context) nhưng những trường đó KHÔNG dùng được khi upload lên Claude.ai hay qua Skills API.
Sai một trong ba là skill không hoạt động
| Quy tắc | ✅ Đúng | ⛔ Sai |
|---|---|---|
| Tên file entry point viết hoa toàn bộ | SKILL.md | skill.md, Skill.md, SKILL.MD |
| Tên thư mục dùng kebab-case | bao-cao-tuan | BaoCaoTuan, bao_cao, báo-cáo |
| Tên skill không chứa từ khoá dành riêng | viet-content-da-kenh | claude-helper, anthropic-tools |
| Không dùng thẻ XML trong name và description | Mô tả bằng văn xuôi thuần | Mô tả có <task> hay </note> |
| Đường dẫn dùng dấu gạch chéo xuôi | references/guide.md | references\guide.md |
allowed-tools đúng mức tối thiểu skill cần. Chỉ cần đọc file thì đừng cấp Write hay Bash. Và tuyệt đối chỉ cài skill từ nguồn bạn tin cậy hoặc tự viết.📝 Đính chính so với tài liệu lưu hành nội bộ
Một số bản trình bày về Skills nói rằng "tuyệt đối không được có README.md trong thư mục skill". Tài liệu chính thức của Anthropic không có quy tắc này — ví dụ chính thức còn để FORMS.md và REFERENCE.md ngay thư mục gốc. Nguyên tắc thật là: đặt tài liệu phụ vào file riêng và trỏ link trực tiếp từ SKILL.md, để phần thân file chính luôn gọn.
FAQ — 3 câu hỏi thường gặp về cấu trúc file SKILL.md
SKILL.md bắt buộc có những trường nào?
Chỉ hai trường bắt buộc: name và description. Chuẩn Agent Skills chấp nhận tổng cộng 6 trường: thêm license, compatibility, metadata, allowed-tools. Thêm trường ngoài danh sách này là lỗi validate.
Giới hạn ký tự của name và description là bao nhiêu?
name tối đa 64 ký tự, chỉ chữ thường, số và gạch ngang; không chứa thẻ XML; không chứa từ khoá claude hoặc anthropic. description không được rỗng, tối đa 1.024 ký tự, cũng không chứa thẻ XML.
Có bắt buộc không được để README.md trong thư mục skill không?
Không — tài liệu chính thức không có quy tắc này. Ví dụ chính thức của Anthropic còn để FORMS.md và REFERENCE.md ngay thư mục gốc. Nguyên tắc thật là: đặt tài liệu phụ vào file riêng và trỏ link trực tiếp từ SKILL.md để file chính luôn gọn.
Nguồn: Bài viết biên soạn dựa trên tài liệu Xây dựng bộ Skills cho Claude (Anthropic Academy, bản tiếng Việt do Nguyen Ngoc Tuan trình bày), đã viết lại và đối chiếu với tài liệu Agent Skills chính thức của Anthropic (platform.claude.com và code.claude.com), cập nhật 15/08/2026. Mọi số liệu kỹ thuật lấy theo tài liệu chính thức.