Công cụ kiểm tra định dạng SKILL.md cho AI Agent

Tệp SKILL.md là thành phần cốt lõi trong quy chuẩn Agent Skills, đóng vai trò cung cấp hướng dẫn chuyên biệt cho các mô hình AI agent khi thực thi tác vụ. Cấu trúc của một kỹ năng chuẩn bao gồm một thư mục chứa tệp SKILL.md, được chia thành hai phần riêng biệt: phần đầu YAML frontmatter nằm giữa hai cặp dấu ba gạch ngang và phần thân Markdown chứa nội dung chỉ dẫn chi tiết.

Khi AI agent quét kho kỹ năng, hệ thống không tải toàn bộ nội dung ngay lập tức. Agent chỉ đọc trường tên và phần mô tả trong frontmatter để nắm được năng lực của kỹ năng đó. Khi yêu cầu từ người dùng khớp với mô tả, agent mới kích hoạt và nạp toàn bộ phần thân Markdown vào ngữ cảnh làm việc. Cơ chế này giúp tối ưu hóa chi phí token và tránh làm loãng bộ nhớ ngữ cảnh của mô hình.

Việc chuẩn hóa định dạng tệp giúp kỹ năng có thể tái sử dụng linh hoạt trên nhiều môi trường agent khác nhau. Công cụ Kiểm tra SKILL.md giúp lập trình viên phát hiện sớm các sai lệch về cấu trúc trước khi triển khai vào dự án thực tế.

Phần YAML frontmatter đặt ở đầu tệp SKILL.md bắt buộc phải tuân thủ nghiêm ngặt các quy tắc về kiểu dữ liệu và độ dài ký tự do đặc tả Agent Skills quy định.

Lỗi thường gặp nhất trong frontmatter là sai cú pháp YAML, chẳng hạn như dùng dấu tab thay vì dấu cách, thiếu dấu ngoặc kép khi chuỗi chứa ký tự hai chấm hoặc đặt sai cấp độ thụt lề. Nếu bạn lưu trữ cấu hình dưới dạng đối tượng, bạn có thể kiểm tra qua công cụ chuyển đổi YAML sang JSON để đảm bảo dữ liệu không bị lỗi phân tích cú pháp trước khi dán vào SKILL.md.

Trường description trong frontmatter quyết định trực tiếp việc AI agent có chọn đúng kỹ năng khi xử lý câu lệnh của người dùng hay không. Nếu mô tả quá ngắn hoặc mơ hồ, agent sẽ bỏ qua kỹ năng dù phần thân chỉ dẫn được viết rất chi tiết.

Công cụ Kiểm tra SKILL.md sẽ đưa ra cảnh báo nếu trường description ngắn hơn 60 ký tự hoặc thiếu cụm từ chỉ định ngữ cảnh sử dụng. Một mô tả chuẩn mực cần nêu rõ hai yếu tố: kỹ năng làm được việc gì và thời điểm cụ thể cần kích hoạt kỹ năng đó.

1. Mô tả yếu: Tự động tạo báo cáo tài chính hàng tháng. (Quá ngắn, thiếu ngữ cảnh và từ khóa kích hoạt).
2. Mô tả chuẩn: Tự động tổng hợp doanh thu, chi phí và xuất bảng cân đối kế toán từ tệp CSV. Sử dụng kỹ năng này khi người dùng yêu cầu báo cáo tài chính định kỳ, phân tích dòng tiền quý hoặc quyết toán thuế.

Việc bổ sung các cụm từ kích hoạt rõ ràng như Sử dụng kỹ năng này khi... hoặc Kích hoạt khi người dùng muốn... giúp mô hình AI phân loại ý định chính xác, hạn chế tình trạng gọi nhầm công cụ trong quy trình làm việc phức tạp.

Phần thân của tệp SKILL.md bắt đầu ngay sau khối frontmatter, đóng vai trò là sổ tay hướng dẫn từng bước cho agent. Đặc tả Agent Skills khuyến nghị phần thân nên duy trì dưới 500 dòng và không vượt quá khoảng 5.000 token ước tính.

Công cụ tính toán dung lượng dựa trên định mức ước lượng 4 ký tự cho mỗi token. Với văn bản tiếng Việt có dấu, mật độ token thực tế có thể cao hơn đôi chút so với ký tự Latin tiêu chuẩn, do đó việc tinh giản câu chữ là rất cần thiết. Nếu phần thân có dung lượng dưới 20 từ hoặc bị bỏ trống, công cụ Kiểm tra SKILL.md sẽ ghi nhận lỗi vi phạm đặc tả.

Để giữ tệp gọn gàng, bạn nên tách các bảng dữ liệu tra cứu lớn, tệp mẫu hoặc lược đồ phức tạp vào thư mục con references/. Khi dẫn chiếu đến các tệp này, chỉ sử dụng đường dẫn tương đối cấp một, ví dụ references/schema.json. Tránh sử dụng đường dẫn tuyệt đối hoặc lồng ghép thư mục quá sâu. Lập trình viên cũng cần rà soát và xóa bỏ toàn bộ các đoạn văn bản giữ chỗ như TODO hoặc Lorem Ipsum trước khi phát hành.

Một tệp SKILL.md có thể hoạt động trên nhiều nền tảng agent khác nhau, nhưng mức độ hỗ trợ các trường mở rộng sẽ có sự khác biệt giữa chuẩn mở và các công cụ chuyên biệt như Claude Code.

Chuẩn Agent Skills cơ bản chỉ ghi nhận các trường tiêu chuẩn gồm name, description, license, compatibility, metadata và allowed-tools. Trong khi đó, Claude Code hỗ trợ thêm các trường cấu hình chuyên sâu như model, hooks và argument-hint. Khi bạn đưa các trường này vào SKILL.md, công cụ Kiểm tra SKILL.md sẽ đánh dấu dưới dạng ghi chú thông tin thay vì báo lỗi. Điều này giúp bạn nhận biết tệp vẫn hoạt động tốt trong Claude Code nhưng các agent khác sẽ bỏ qua những trường mở rộng đó.

Đối với các thông tin tùy biến của riêng dự án, phương pháp an toàn nhất là đặt chúng bên trong trường metadata dưới dạng khóa phụ. Riêng trường allowed-tools, đặc tả hiện tại quy định định dạng là một chuỗi văn bản phân tách bằng dấu cách thay vì danh sách mảng YAML. Nếu bạn cần chuyển đổi cấu trúc danh sách sang YAML hợp lệ, có thể tham khảo bộ chuyển đổi JSON sang YAML để kiểm tra cấu trúc dữ liệu.

Báo cáo từ công cụ Kiểm tra SKILL.md phân loại kết quả thành ba cấp độ rõ ràng giúp lập trình viên nhanh chóng xử lý vấn đề trong tệp chỉ dẫn.

1. Lỗi (Error): Các vi phạm nghiêm trọng đối với đặc tả như thiếu frontmatter, sai quy tắc đặt tên, thiếu mô tả hoặc phần thân trống. Tệp chỉ được xác nhận là hợp lệ khi không còn bất kỳ lỗi nào.
2. Cảnh báo (Warning): Các điểm chưa tối ưu theo khuyến nghị, bao gồm mô tả dưới 60 ký tự, độ dài vượt quá 500 dòng, chứa văn bản giữ chỗ hoặc liên kết tệp quá sâu.
3. Ghi chú (Note): Các thông tin hữu ích về tính tương thích, chẳng hạn như trường chỉ hỗ trợ trên Claude Code hoặc trường allowed-tools đang ở giai đoạn thử nghiệm.

Bên cạnh bảng chi tiết vấn đề, công cụ còn cung cấp bảng thống kê số dòng, số từ, ký tự frontmatter và ước lượng token. Người dùng có thể xuất kết quả kiểm tra sang tệp CSV để lưu trữ hoặc chia sẻ với đội ngũ phát triển.

Toàn bộ quá trình phân tích và xử lý cú pháp diễn ra hoàn toàn cục bộ trên trình duyệt của bạn. Nội dung tệp SKILL.md cùng các quy trình nội bộ không bị gửi lên bất kỳ máy chủ nào, đảm bảo tính riêng tư tuyệt đối cho mã nguồn dự án.