3.3 · Progressive disclosure: giữ SKILL.md dưới 500 dòng

Vấn đề của skill quá dài

SKILL.md được nạp toàn bộ vào context ngay khi kích hoạt. Một file 2.000 dòng chiếm chỗ ngang một tài liệu tham khảo lớn — dù 90% nội dung chỉ cần trong các ca hiếm gặp.

Nguyên tắc progressive disclosure

• SKILL.md chỉ chứa: mô tả, quy trình chính, 2-3 ví dụ ngắn — dưới 500 dòng
• Chi tiết dài (bảng tra cứu, quy tắc edge-case) tách vào references/*.md
• SKILL.md trỏ rõ: "nếu gặp trường hợp X, đọc references/x.md" — Claude chỉ mở khi cần

Cấu trúc ví dụ

skill-name/
├── SKILL.md              # < 500 dòng: quy trình chính
├── references/
│   ├── edge-cases.md      # các trường hợp đặc biệt
│   └── api-details.md     # tham chiếu API đầy đủ
└── scripts/
    └── validate.py