                        (Show All)_ · **Bài 3/6** · [🌐 English](../../en/03-configuration-and-multi-file-skills/en.md)

← Bài trước · 📋 Mục lục khoá · Bài sau →

Configuration and multi-file skills

👨‍💻 Track: Developer Track · 📚 Course: Introduction to Agent Skills · ⏱ 20 phút · 🧭 Path C

📖 Nội dung bài học

Nội dung bài học

Thời gian ước tính: 20 phút

Sau bài học này, bạn sẽ có thể:

Cấu hình các trường metadata nâng cao của skill bao gồm allowed-tools và model
Viết mô tả skill hiệu quả để kích hoạt (trigger) chính xác theo yêu cầu
Dùng allowed-tools để giới hạn những gì Claude có thể làm khi một skill đang hoạt động
Tổ chức các skill phức tạp bằng cách sử dụng cấu trúc tiết lộ dần dần (progressive disclosure) và đa tệp

Cấu hình và skill đa tệp

(4 phút)

Video này hướng dẫn các kỹ thuật nâng cao giúp skill mạnh mẽ hơn: bộ các trường metadata đầy đủ, cách viết mô tả để kích hoạt tin cậy, giới hạn quyền truy cập tool cho các luồng công việc nhạy cảm về bảo mật, và tổ chức các skill lớn trên nhiều tệp bằng phương pháp tiết lộ dần dần (progressive disclosure). Bạn sẽ học cách giữ cho skill hoạt động hiệu quả trong khi vẫn hỗ trợ được các trường hợp sử dụng phức tạp.

Các điểm chính cần lưu ý

name và description là bắt buộc — allowed-tools và model là các tùy chọn bổ sung mạnh mẽ.
Một mô tả tốt trả lời được hai câu hỏi: Skill này làm gì? Khi nào Claude nên dùng nó?
allowed-tools giới hạn các tool mà Claude có thể dùng khi skill đang hoạt động — hữu ích cho các luồng công việc chỉ đọc (read-only) hoặc nhạy cảm về bảo mật.
Tiết lộ dần dần (progressive disclosure): giữ tệp SKILL.md dưới 500 dòng và liên kết đến các tệp hỗ trợ (tài liệu tham khảo, script, tài nguyên) mà Claude chỉ đọc khi cần thiết.
Script thực thi mà không cần tải nội dung vào context — chỉ có kết quả đầu ra (output) là tiêu tốn token, giúp tối ưu context.

Một skill cơ bản có thể hoạt động chỉ với tên và mô tả, nhưng có một số kỹ thuật nâng cao có thể giúp skill của bạn hiệu quả hơn nhiều trong Claude Code. Hãy cùng tìm hiểu các trường chính, cách viết mô tả tốt nhất, giới hạn tool và cách cấu trúc các skill lớn.

Các trường Metadata của Skill

Tiêu chuẩn mở dành cho agent skills hỗ trợ một số trường trong frontmatter của SKILL.md. Hai trường đầu tiên là bắt buộc, các trường còn lại là tùy chọn:

name (bắt buộc) — Định danh skill của bạn. Chỉ dùng chữ cái viết thường, số và dấu gạch ngang. Tối đa 64 ký tự. Phải khớp với tên thư mục.
description (bắt buộc) — Cho Claude biết khi nào cần dùng skill. Tối đa 1.024 ký tự. Đây là trường quan trọng nhất vì Claude dùng nó để khớp lệnh.
allowed-tools (tùy chọn) — Giới hạn các tool mà Claude có thể dùng khi skill đang hoạt động.
model (tùy chọn) — Chỉ định model Claude nào sẽ được dùng cho skill.

Viết mô tả hiệu quả

Hãy đưa ra chỉ dẫn rõ ràng. Nếu ai đó nói với bạn "nhiệm vụ của bạn là hỗ trợ tài liệu", bạn sẽ không biết phải làm gì — và Claude cũng vậy.

Một mô tả tốt cần trả lời hai câu hỏi:

Skill này làm gì?
Khi nào Claude nên dùng nó?

Nếu skill của bạn không kích hoạt như mong đợi, hãy thử thêm các từ khóa khớp với cách bạn thường đặt câu hỏi thực tế. Mô tả là thứ Claude dùng để quyết định xem một skill có phù hợp hay không, nên ngôn ngữ rất quan trọng.

Giới hạn Tool với allowed-tools

Đôi khi bạn muốn một skill chỉ có thể đọc tệp mà không được sửa đổi. Điều này hữu ích cho các luồng công việc nhạy cảm về bảo mật, các tác vụ chỉ đọc, hoặc bất kỳ tình huống nào bạn muốn thiết lập rào chắn bảo vệ (guardrails).

Trong ví dụ này, trường allowed-tools được thiết lập là Read, Grep, Glob, Bash. Khi skill này hoạt động, Claude chỉ có thể dùng các tool đó mà không cần hỏi ý kiến — không chỉnh sửa, không ghi tệp.

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

Nếu bạn bỏ qua hoàn toàn allowed-tools, skill sẽ không giới hạn gì cả. Claude sẽ dùng cơ chế phân quyền thông thường.

Tiết lộ dần dần (Progressive Disclosure)

Các skill chia sẻ context window của Claude với cuộc hội thoại của bạn. Khi Claude kích hoạt một skill, nó sẽ tải nội dung của tệp SKILL.md đó vào context. Nhưng đôi khi bạn cần các tài liệu tham khảo, ví dụ, hoặc script tiện ích mà skill phụ thuộc vào.

Nhồi nhét mọi thứ vào một tệp dài 2.000 dòng gây ra hai vấn đề: tốn nhiều không gian context window và rất khó bảo trì.

Phương pháp tiết lộ dần dần (progressive disclosure) giải quyết vấn đề này. Hãy giữ các chỉ dẫn thiết yếu trong SKILL.md và đặt các tài liệu tham khảo chi tiết vào các tệp riêng biệt mà Claude chỉ đọc khi cần thiết.

Tiêu chuẩn mở gợi ý tổ chức thư mục skill của bạn gồm:

scripts/ — Mã thực thi
references/ — Tài liệu bổ sung
assets/ — Hình ảnh, template hoặc các tệp dữ liệu khác

Sau đó trong SKILL.md, hãy liên kết đến các tệp hỗ trợ với chỉ dẫn rõ ràng về việc khi nào cần tải chúng:

Trong ví dụ này, Claude chỉ đọc architecture-guide.md khi có người hỏi về thiết kế hệ thống. Nếu họ hỏi về việc thêm một component, nó sẽ không bao giờ tải tệp đó. Nó giống như việc có một mục lục trong context window thay vì toàn bộ văn bản.

Một quy tắc nhỏ: hãy giữ SKILL.md dưới 500 dòng. Nếu vượt quá con số đó, hãy cân nhắc chia nhỏ nội dung vào các tệp tham khảo riêng biệt.

Sử dụng Script hiệu quả

Các script trong thư mục skill có thể chạy mà không cần tải nội dung của chúng vào context. Script thực thi và chỉ có kết quả đầu ra (output) là tiêu tốn token. Chỉ dẫn quan trọng cần đưa vào SKILL.md là yêu cầu Claude chạy (run) script chứ không phải đọc (read) nó.

Điều này đặc biệt hữu ích cho:

Kiểm tra môi trường (Environment validation)
Chuyển đổi dữ liệu cần sự nhất quán
Các thao tác đáng tin cậy hơn khi chạy bằng mã đã kiểm thử so với mã do AI tạo ra

Ôn tập bài học

Hãy nghĩ về một skill bạn muốn xây dựng có liên quan đến nhiều tệp. Bạn sẽ cấu trúc SKILL.md so với các tệp tham khảo hỗ trợ như thế nào?
Có luồng công việc nào trong nhóm của bạn mà việc giới hạn quyền truy cập tool bằng allowed-tools sẽ thêm một lớp bảo mật quan trọng không?

Bước tiếp theo

Trong bài học tiếp theo, chúng ta sẽ so sánh skill với các cách tùy chỉnh Claude Code khác — CLAUDE.md, subagents, hooks và MCP server — để bạn có thể chọn đúng công cụ cho từng tình huống.

Phản hồi

Trong quá trình học, chúng tôi rất muốn nghe cách bạn đang dùng skill trong công việc, cũng như bất kỳ phản hồi nào. Chia sẻ phản hồi của bạn tại đây.

🎬 Bản ghi video

Source video: 98KaK_rn5rQ

📜 Mở rộng bản ghi (đã chỉnh sửa + dịch AI)

Một skill cơ bản có thể hoạt động chỉ với tên và mô tả, nhưng dưới đây là những mẹo nâng cao giúp các skill của bạn thực sự hiệu quả trong Claude Code. Tiêu chuẩn mở agentskills.io cung cấp nhiều trường dữ liệu để tối ưu hóa cách các agent vận hành.

Metadata và các trường cốt lõi

Chúng ta đã nắm qua các yêu cầu cơ bản cho một skill:

Name (Tên): Định danh skill của bạn. Tên chỉ được dùng chữ cái viết thường, số và dấu gạch ngang, tối đa 64 ký tự. Tên này phải khớp với tên thư mục của bạn.
Description (Mô tả): Đây là trường bắt buộc (tối đa 1.024 ký tự) nhằm chỉ dẫn cho Claude khi nào nên sử dụng skill. Đây là trường quan trọng nhất vì Claude dựa vào đó để thực hiện khớp ý định (intent matching).

Ngoài ra, chúng ta có thể thêm các trường tùy chọn:

allowed_tools: Giới hạn những tool nào Claude được phép sử dụng khi skill đang hoạt động.
model: Chỉ định model Claude cụ thể cho skill đó.

Viết mô tả chất lượng cao

Hãy cố gắng đưa ra các chỉ dẫn tường minh. Ví dụ, nếu ai đó nói công việc của tôi là "hỗ trợ tài liệu", tôi sẽ không biết chính xác mình phải làm gì. Chúng ta nên giả định rằng Claude cũng tư duy theo cách tương tự.

Một mô tả tốt cần trả lời được hai câu hỏi:

Skill này làm nhiệm vụ gì?
Khi nào Claude nên sử dụng nó?

Nếu skill của bạn không được kích hoạt đúng lúc, hãy thêm các từ khóa sát với cách bạn thường đặt yêu cầu một cách tự nhiên. Một bản mô tả công việc được định nghĩa rõ ràng sẽ giúp Claude tự tin hơn để hoàn thành nhiệm vụ.

Kiểm soát quyền truy cập công cụ với `allowed_tools`

Đôi khi bạn muốn một skill chỉ có quyền đọc file mà không được chỉnh sửa. Điều này rất hữu ích cho các quy trình làm việc nhạy cảm về bảo mật, các tác vụ chỉ đọc (read-only) hoặc các hoạt động kiểm thử (audit) chuyên biệt.

Chúng ta sử dụng trường allowed_tools để thực hiện điều này. Khi skill này được kích hoạt, Claude chỉ có thể sử dụng các tool được chỉ định mà không cần hỏi thêm quyền. Điều này đồng nghĩa với:

Không chỉnh sửa.
Không ghi file.
Không dùng lệnh bash (trừ khi được cho phép rõ ràng).

Nếu bạn bỏ qua trường allowed_tools, skill sẽ không hạn chế bất cứ điều gì và Claude sẽ mặc định tuân theo mô hình phân quyền thông thường.

Quản lý ngữ cảnh và Tiết lộ thông tin lũy tiến (Progressive Disclosure)

Các skill chia sẻ context window của Claude với cuộc hội thoại của bạn. Khi Claude quyết định sử dụng một skill, nó sẽ tải nội dung của skill đó vào ngữ cảnh. Tuy nhiên, việc nhồi nhét các tài liệu tham khảo, ví dụ hoặc các script tiện ích vào một file văn bản duy nhất dài 2.000 dòng sẽ tiêu tốn quá nhiều không gian trong context window và gây khó khăn cho việc bảo trì.

Đây là lúc phương pháp Tiết lộ thông tin lũy tiến (Progressive Disclosure) phát huy tác dụng. Bạn nên duy trì cấu trúc:

skill.md: Chỉ chứa các chỉ dẫn thiết yếu (giữ dưới 500 dòng).
Các file riêng biệt: Chứa tài liệu tham khảo chi tiết mà Claude chỉ đọc khi cần thiết.

Tiêu chuẩn mở gợi ý một cấu trúc thư mục như sau:

/scripts: Chứa mã nguồn có thể thực thi.
/references: Chứa tài liệu bổ sung.
/assets: Chứa hình ảnh, template hoặc các file dữ liệu khác.

Trong file skill.md, bạn chỉ cần dẫn link tới các file hỗ trợ này. Ví dụ, Claude có thể chỉ đọc architecture.md khi người dùng hỏi về thiết kế hệ thống. Nếu họ chỉ hỏi về việc thêm một component vào đâu, file đó sẽ không bao giờ được tải lên. Cách tiếp cận này giống như việc cung cấp một Mục lục cho context window thay vì tải toàn bộ tài liệu.

Thực thi Script hiệu quả

Các script trong thư mục skill của bạn có thể chạy mà không cần tải toàn bộ mã nguồn vào context window. Khi Claude chạy một script, script đó sẽ thực thi và chỉ có kết quả đầu ra (output) là tiêu tốn token.

Claude "chạy" script chứ không "đọc" script. Điều này cực kỳ hữu ích cho:

Kiểm tra môi trường (Environment validation).
Chuyển đổi dữ liệu nhất quán.
Các thao tác đòi hỏi sự tin cậy của mã nguồn đã qua kiểm thử thay vì mã nguồn do AI tự tạo.

Tóm tắt về Metadata của Skill

Để tổng kết, các skill hiệu quả cần tận dụng:

Name & Description: Bắt buộc để định danh và kích hoạt chính xác.
allowed_tools: Giới hạn các tool khả dụng để đảm bảo bảo mật và sự tập trung.
model: Chỉ định phiên bản model Claude cụ thể.
Progressive Disclosure: Giữ skill.md dưới 500 dòng và liên kết với các tài liệu tham khảo bên ngoài để tối ưu hóa context window.
Executable Scripts: Thực hiện các tác vụ phức tạp mà không lãng phí token cho mã nguồn.

🔁 Bài học liên quan

Bài tiếp: Skills vs. other Claude Code features
Bài trước: Creating your first skill
Cùng section: What are skills? · Creating your first skill · Skills vs. other Claude Code features
Thuộc lộ trình: Path C
Docs tham khảo: Glossary · Skills atlas · By use-case

📚 Nguồn & ghi nhận

Bài học gốc Anthropic Academy: https://anthropic.skilljar.com/introduction-to-agent-skills/434526
Crawl: 2026-04-23 · Chuẩn hoá: 2026-05-01