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.
- Hiểu allowed-tools là cấp quyền sẵn, không phải danh sách chặn công cụ khác.
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ụ được cấp quyền dùng không cần hỏi lại trong lượt gọi skill. Trường này không chặn công cụ không được liệt kê. Hỗ trợ khác nhau giữa các nền tảng; xem thêm permission settings.
⛔ 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 cho phép gọi các công cụ được liệt kê mà không hỏi lại trong lượt skill được gọi; không loại bỏ công cụ khác. Muốn chặn công cụ trong Claude Code, dùng disallowed-tools hoặc permission deny rules. Không cấp Bash rộng nếu chỉ cần đọc. Xem tài liệu quyền công cụ và kiểm tra chính sách thực thi của nền tảng.📝 Đí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 06/11/2026. Mọi số liệu kỹ thuật lấy theo tài liệu chính thức.