Cấu hình và skill nhiều file

Bài này đi qua các kỹ thuật nâng cao giúp skill mạnh hơn: đầy đủ các field metadata, cách viết description để kích hoạt đáng tin cậy, giới hạn quyền truy cập tool cho các quy trình nhạy cảm về bảo mật, và cách tổ chức skill lớn qua nhiều file bằng progressive disclosure.

Các field metadata của skill

Chuẩn mở agent skills hỗ trợ vài field trong frontmatter của SKILL.md. Hai field bắt buộc, còn lại tùy chọn:

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

Viết description hiệu quả

Hãy cụ thể với chỉ dẫn của bạn. Nếu ai đó bảo bạn “việc của bạn là hỗ trợ tài liệu”, bạn sẽ không biết chính xác phải làm gì - Claude cũng suy nghĩ tương tự vậy.

Một description tốt trả lời hai câu hỏi:

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

Nếu skill của bạn không kích hoạt khi bạn mong đợi, hãy thử thêm nhiều từ khóa hơn khớp với cách bạn thực sự diễn đạt yêu cầu.

Giới hạn tool bằng allowed-tools

Đôi khi bạn muốn một skill chỉ có thể đọc file, không được sửa chúng. Điều này hữu ích cho các quy trình nhạy cảm về bảo mật, tác vụ chỉ-đọc, hoặc bất kỳ tình huống nào bạn muốn có rào chắn.

Ví dụ YAML:

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

Khi skill này đang hoạt động, Claude chỉ có thể dùng những tool đó mà không cần hỏi permission - không chỉnh sửa, không ghi file.

Nếu bạn bỏ hẳn allowed-tools, skill sẽ không giới hạn gì cả. Claude dùng model permission thông thường của nó.

Ví dụ field allowed-tools giới hạn skill chỉ được dùng các tool chỉ-đọc.

Progressive disclosure

Skill dùng chung cửa sổ ngữ cảnh với hội thoại của bạn. Khi Claude kích hoạt một skill, nó nạp toàn bộ nội dung SKILL.md vào ngữ cảnh.

Nhồi nhét mọi thứ vào một file 2.000 dòng gây ra hai vấn đề: nó chiếm rất nhiều dung lượng cửa sổ ngữ cảnh, và không hề dễ chịu để bảo trì.

Progressive disclosure giải quyết điều này. Giữ các chỉ dẫn thiết yếu trong SKILL.md, và đặt tài liệu tham chiếu chi tiết vào các file riêng mà Claude chỉ đọc khi thực sự cần.

Chuẩn mở đề xuất tổ chức thư mục skill của bạn với:

• scripts/ - code có thể thực thi.
• references/ - tài liệu bổ sung.
• assets/ - hình ảnh, template, hoặc các file dữ liệu khác.

Trong pattern này, Claude chỉ đọc một file như architecture-guide.md khi ai đó hỏi về kiến trúc hệ thống.

Một quy tắc tốt: giữ SKILL.md dưới 500 dòng.

Tổ chức thư mục skill theo progressive disclosure: scripts/, references/, assets/.

Dùng script hiệu quả

Script trong thư mục skill của bạn có thể chạy mà không cần nạp nội dung của chúng vào ngữ cảnh. Script thực thi, và chỉ output của nó tiêu tốn token.

Chỉ dẫn quan trọng cần đưa vào SKILL.md là bảo Claude chạy script đó, không phải đọc nó.

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

• Kiểm tra môi trường (environment validation).
• Các phép biến đổi dữ liệu cần tính nhất quán.
• Các thao tác đáng tin cậy hơn khi là code đã được kiểm thử, thay vì code do Claude tự sinh ra.

Nguồn

Dịch từ bài giảng “Configuration and multi-file skills”, khóa Introduction to agent skills trên Claude Academy.