Khi một SKILL.md không còn đủ
Skill "viết tài liệu kỹ thuật chuẩn công ty" của bạn phình to: quy tắc chung, template cho 4 loại tài liệu, 10 ví dụ mẫu, glossary thuật ngữ... Nhồi hết vào SKILL.md = 3000 dòng không ai (kể cả AI) đọc nổi một cách hiệu quả.
Kiến trúc thư viện
tai-lieu-ky-thuat/
├── SKILL.md # Mục lục + quy trình lõi (NGẮN)
├── templates/
│ ├── design-doc.md
│ ├── api-spec.md
│ └── runbook.md
├── examples/
│ ├── design-doc-mau.md
│ └── api-spec-mau.md
└── reference/
├── glossary.md
└── style-rules.md
SKILL.md đóng vai trò "người điều phối"
## Quy trình
1. Xác định loại tài liệu user cần:
- Design doc → đọc templates/design-doc.md + examples/design-doc-mau.md
- API spec → đọc templates/api-spec.md + examples/api-spec-mau.md
- Runbook → đọc templates/runbook.md
2. Mọi loại tài liệu đều tuân theo reference/style-rules.md
3. Thuật ngữ chuyên ngành: tra reference/glossary.md trước khi tự dịch
Nhờ progressive disclosure, khi user cần API spec, Claude chỉ nạp đúng 2-3 file liên quan — phần còn lại của "thư viện" nằm im không tốn context.
Quy tắc tổ chức
- SKILL.md dưới 200 dòng — nó là bản đồ, không phải kho chứa
- Mỗi file phụ một chủ đề duy nhất — dễ tham chiếu, dễ cập nhật
- Đặt tên file tự mô tả:
api-spec-mau.mdtốt hơnvd2.md - Tham chiếu tường minh trong SKILL.md — file không được nhắc đến là file vô hình với AI
💡 Đây cũng chính là cách Anthropic tổ chức các skill xử lý docx/pptx/xlsx chính thức: SKILL.md mỏng + thư mục tài liệu kỹ thuật dày. Mở repo anthropics/skills ra học trực tiếp.