Cấu trúc thư mục AI Skill chuẩn: SKILL.md, scripts, references và assets

Một AI Skill tốt không được đánh giá bằng số lượng tệp, mà bằng khả năng giúp AI tìm đúng hướng dẫn, thực hiện đúng quy trình và kiểm tra được đầu ra. Ở mức tối giản, Skill chỉ cần một file `SKILL.md`. Khi công việc có mã thực thi, tài liệu dài hoặc tệp mẫu, cấu trúc nên mở rộng thành `scripts`, `references` và `assets`.

Nếu bạn mới tiếp cận khái niệm này, hãy đọc trước bài AI Skill là gì? để hiểu sự khác nhau giữa một prompt dùng một lần và một quy trình có thể tái sử dụng.

Cấu trúc thư mục AI Skill là gì?

Cấu trúc thư mục AI Skill là cách sắp xếp hướng dẫn, mã thực thi, kiến thức tham chiếu và tài nguyên đầu vào trong một gói công việc. Mục tiêu là để AI biết tệp nào cần đọc trước, thông tin nào chỉ tải khi cần và công cụ nào phải dùng ở từng bước.

Không phải nền tảng AI nào cũng yêu cầu tên thư mục giống hệt nhau. Tuy vậy, mô hình gồm một tệp hướng dẫn chính và các thư mục hỗ trợ là cách tổ chức dễ hiểu, dễ mở rộng và phù hợp với nguyên tắc tiết lộ dần thông tin theo ngữ cảnh.

Bốn thành phần chính của một AI Skill

SKILL.md là điểm bắt đầu

`SKILL.md` là bản đồ vận hành của Skill. Tệp này nên trả lời được năm câu hỏi: Skill dùng để làm gì, khi nào được kích hoạt, cần dữ liệu gì, phải thực hiện theo thứ tự nào và kết quả đạt chuẩn ra sao.

Không nên biến `SKILL.md` thành kho chứa mọi thông tin. Nếu tệp quá dài, AI phải đọc nhiều nội dung không liên quan trước khi bắt đầu làm việc. Hãy giữ trong đó phần định tuyến và quy tắc cốt lõi; chuyển tài liệu chuyên sâu sang `references/` và chỉ dẫn rõ khi nào cần đọc.

Bạn có thể xem thêm cách Markdown hỗ trợ cấu trúc nội dung trong bài File .MD là gì?.

scripts dành cho thao tác cần tính lặp lại

Thư mục `scripts/` phù hợp với những bước khó thực hiện ổn định chỉ bằng câu lệnh ngôn ngữ tự nhiên. Ví dụ: kiểm tra cấu trúc dữ liệu, chuyển đổi định dạng, tính toán, đổi tên hàng loạt hoặc chạy một quy trình kiểm định.

Một script tốt nên có đầu vào rõ ràng, thông báo lỗi dễ hiểu và không tự ý thực hiện hành động ngoài phạm vi. Trong `SKILL.md`, hãy ghi cụ thể script nào được dùng, dùng ở bước nào và điều kiện nào phải dừng để người dùng kiểm tra.

references giúp tách kiến thức khỏi quy trình

`references/` là nơi phù hợp cho tài liệu dài như tiêu chuẩn biên tập, hướng dẫn API, bảng thuật ngữ, quy tắc thương hiệu hoặc checklist chuyên môn. Cách tách này giữ cho tệp chính ngắn gọn nhưng vẫn bảo toàn kiến thức cần thiết.

Không nên yêu cầu AI đọc toàn bộ thư mục tham chiếu trong mọi lần chạy. Thay vào đó, hãy viết quy tắc định tuyến: nhiệm vụ nào cần tài liệu nào, đọc đến phần nào và thông tin nào được xem là nguồn chính.

assets chứa tài nguyên dùng để tạo đầu ra

`assets/` không phải nơi lưu hướng dẫn. Đây là nơi dành cho tệp mẫu, hình minh họa, bố cục, dữ liệu ví dụ hoặc tài nguyên sẽ được sao chép hay biến đổi trong quá trình làm việc.

Tên tệp nên mô tả đúng chức năng, tránh những tên chung như `mau-moi-final-2`. Nếu có nhiều phiên bản, hãy ghi rõ phiên bản nào đang được dùng và không để AI đoán tệp phù hợp.

Cây thư mục AI Skill mẫu

ten-skill/ SKILL.md scripts/ — validate-input.js, export-result.js references/ — brand-guidelines.md, quality-checklist.md assets/ — article-template.md, cover-placeholder.webp

Cây thư mục này chỉ là mẫu tổ chức, không phải quy định bắt buộc. Nếu Skill chỉ hướng dẫn một quy trình ngắn và không cần mã hay tài nguyên cố định, thêm thư mục trống sẽ làm cấu trúc rườm rà hơn mà không tạo thêm giá trị.

Khi nào chỉ cần một file SKILL.md?

Bạn chỉ cần `SKILL.md` khi quy trình ngắn, dữ liệu đầu vào đơn giản, không có mã thực thi và toàn bộ hướng dẫn vẫn dễ đọc trong một tệp. Đây thường là lựa chọn phù hợp cho checklist, quy trình viết, hướng dẫn phân tích hoặc tác vụ có ít nhánh xử lý.

• Hướng dẫn chính quá dài và khó tìm thông tin.
• Một đoạn mã được viết lại nhiều lần cho cùng một thao tác.
• Nhiều nhiệm vụ cần dùng chung một tài liệu chuyên môn.
• Đầu ra phải dựa trên mẫu, hình ảnh hoặc tệp cố định.
• Việc cập nhật một thành phần thường làm ảnh hưởng những phần không liên quan.

Cách tổ chức AI Skill từng bước

Bước 1: Xác định đầu ra và điều kiện kích hoạt

Trước khi tạo thư mục, hãy viết một câu mô tả đầu ra mong muốn và những tình huống Skill nên được dùng. Nếu chưa xác định rõ phạm vi, việc chia tệp chỉ làm sự mơ hồ phân tán sang nhiều nơi.

Bước 2: Viết quy trình tối thiểu trong SKILL.md

Đưa vào tệp chính mục tiêu, đầu vào, các bước thực hiện, giới hạn và checklist. Chạy thử với một vài tình huống thực tế trước khi tạo thêm thành phần hỗ trợ.

Bước 3: Tách phần có chức năng riêng

Chuyển mã lặp lại sang `scripts/`, tài liệu dài sang `references/` và tệp mẫu sang `assets/`. Mỗi lần tách phải có lý do sử dụng rõ ràng, không tách chỉ để cấu trúc trông chuyên nghiệp hơn.

Bước 4: Viết chỉ dẫn định tuyến

Trong `SKILL.md`, ghi rõ thời điểm đọc từng tài liệu hoặc chạy từng script. Chỉ dẫn nên cụ thể như “đọc checklist trước bước kiểm định” thay vì câu chung chung như “tham khảo tài liệu khi cần”.

Bước 5: Kiểm tra đường dẫn và tình huống lỗi

Xác minh tất cả đường dẫn tương đối, tên tệp và phần mở rộng. Thử trường hợp thiếu tệp, sai định dạng hoặc dữ liệu không hợp lệ để bảo đảm Skill biết dừng và giải thích vấn đề thay vì tạo kết quả đoán mò.

Nguyên tắc progressive disclosure trong AI Skill

Progressive disclosure có thể hiểu là chỉ cung cấp mức thông tin phù hợp với bước đang xử lý. AI đọc mô tả và quy tắc chính trước; tài liệu chi tiết chỉ được mở khi nhiệm vụ thực sự cần đến.

Cách tổ chức này giúp giảm nhiễu ngữ cảnh, nhưng không có nghĩa là giấu những quy tắc quan trọng. Các giới hạn an toàn, điều kiện dừng và yêu cầu chất lượng cốt lõi vẫn phải xuất hiện trong `SKILL.md`. Chỉ những kiến thức chuyên sâu hoặc tài nguyên nặng mới nên được tải theo nhu cầu.

Những lỗi thường gặp khi xây dựng cấu trúc Skill

• Tạo đủ mọi thư mục dù không có nội dung thực sự cần dùng.
• Đưa quy tắc quan trọng vào tài liệu phụ nhưng không chỉ dẫn AI phải đọc.
• Lưu cùng một hướng dẫn ở nhiều tệp, dẫn đến phiên bản mâu thuẫn.
• Dùng tên tệp mơ hồ khiến AI phải đoán mục đích.
• Đặt script có khả năng thay đổi dữ liệu nhưng không quy định bước xác nhận.
• Không kiểm tra đường dẫn sau khi đổi tên hoặc di chuyển tệp.
• Đưa tài nguyên mẫu vào references hoặc đưa tài liệu hướng dẫn vào assets.

Checklist kiểm tra trước khi đóng gói AI Skill

• SKILL.md mô tả rõ mục tiêu, phạm vi và điều kiện kích hoạt.
• Mỗi bước đều có đầu vào, hành động và tiêu chí hoàn tất.
• Tài liệu tham chiếu chỉ được đọc khi có chỉ dẫn phù hợp.
• Script có tên rõ ràng, xử lý lỗi và không vượt phạm vi.
• Asset có phiên bản, định dạng và mục đích sử dụng cụ thể.
• Không có nội dung trùng lặp hoặc quy tắc mâu thuẫn giữa các tệp.
• Mọi đường dẫn tương đối hoạt động sau khi đóng gói.
• Skill đã được thử với trường hợp bình thường và trường hợp thiếu dữ liệu.

Câu hỏi thường gặp

Kết luận

Cấu trúc AI Skill tốt bắt đầu từ nhu cầu thực tế, không bắt đầu từ số lượng thư mục. Hãy dùng `SKILL.md` làm bản đồ vận hành, bổ sung `scripts` cho xử lý có thể lặp lại, `references` cho kiến thức chuyên sâu và `assets` cho tài nguyên tạo đầu ra. Khi mỗi thành phần có một vai trò duy nhất và được gọi đúng lúc, Skill sẽ dễ hiểu, dễ kiểm tra và dễ mở rộng hơn.

Bạn có thể khám phá thêm các quy trình AI thực hành tại Aiskill Việt Nam.