Knowledge & Resources

Level: L4 — AI Skills (Bài 4/12)

Đây là lần thứ 3 từ “Knowledge”/“file” mang nghĩa khác nhau xuyên curriculum.

	L3 bài 21 — Project Knowledge base	L4 bài 33 — Skill Resources
Ai tải lên	Người dùng, thủ công, qua giao diện Project	Người viết Skill, đóng gói sẵn cùng Skill
Mục đích	Ngữ cảnh nền để trả lời câu hỏi trong hội thoại	Tài liệu/script hỗ trợ Skill hoàn thành 1 quy trình
Cơ chế	RAG (tìm kiếm ngữ nghĩa qua nhiều file)	Đọc trực tiếp qua bash khi được `SKILL.md` tham chiếu
Khi nào load	Tự động theo mức độ liên quan tới câu hỏi	Chỉ khi `SKILL.md` chỉ định rõ

Bài này không dạy lại RAG hay cách tổ chức Project Knowledge base (bài 21) — chỉ dạy cách tổ chức resources bên trong 1 Skill.

1. Mục tiêu học tập

Sau bài này, bạn có thể:

Phân biệt rõ “Knowledge” trong Skill (bài này) với “Knowledge base” của Project (bài 21) — không nhầm lẫn 2 cơ chế.
Áp dụng 3 pattern tổ chức tài nguyên chính thức: high-level guide with references, domain-specific organization, conditional details.
Biết quy tắc “1 tầng sâu” và “mục lục cho file dài” để tránh Claude đọc thiếu nội dung.
Phân biệt khi nào nên dùng tài liệu tham khảo (đọc), khi nào nên dùng script (thực thi).

2. Khái niệm cốt lõi

Resources là nội dung ở Tầng 3 của progressive disclosure (bài 31) — chỉ load khi SKILL.md (Tầng 2) tham chiếu tới, và gần như không giới hạn dung lượng vì không tính vào ngữ cảnh nếu không được đọc [S75].

3 pattern tổ chức chính thức (S77):

High-level guide with references — SKILL.md tóm tắt ngắn gọn, kèm link tới file chi tiết riêng (FORMS.md, REFERENCE.md). Dùng khi Skill có 1 luồng chính + vài tính năng nâng cao ít dùng.
Domain-specific organization — chia tài liệu theo từng miền chủ đề riêng (finance.md, sales.md, product.md…), để khi người dùng hỏi về 1 miền, Claude chỉ đọc đúng file đó, không load nhầm miền khác [S77].
Conditional details — nội dung cơ bản để thẳng trong SKILL.md, chỉ link ra file riêng cho phần nâng cao/hiếm dùng.

2 quy tắc cấu trúc bắt buộc phải nhớ:

Giữ tham chiếu 1 tầng sâu tính từ SKILL.md. Nếu SKILL.md link tới A, A lại link tới B, B lại link tới C — Claude có xu hướng chỉ đọc lướt (kiểu head -100) khi gặp tham chiếu lồng nhau nhiều tầng, dẫn tới đọc thiếu nội dung [S77]. Mọi file tham khảo nên được link trực tiếp từ SKILL.md.
File tham khảo dài hơn 100 dòng nên có mục lục ở đầu — giúp Claude thấy được toàn bộ phạm vi nội dung ngay cả khi chỉ đọc lướt trước [S77].

Phân biệt “tài liệu tham khảo” (đọc) và “script” (thực thi):

“Instructions: Additional markdown files… containing specialized guidance. Code: Executable scripts… that Claude runs via bash; scripts provide deterministic operations without consuming context. Resources: Reference materials like database schemas, API documentation, templates.” [S74]

Instructions/tài liệu là để Claude đọc và áp dụng linh hoạt; script là để Claude chạy và chỉ nhận kết quả đầu ra — không đọc mã nguồn script vào ngữ cảnh. Hướng dẫn trong SKILL.md cần nói rõ Claude nên chạy hay nên đọc 1 file cụ thể — nhập nhằng ở đây gây lãng phí [S77].

3. Tại sao nội dung này quan trọng

Đây là lý do 1 Skill có thể “cồng kềnh” về nội dung (hàng chục file tham khảo, dataset lớn) mà không làm nặng ngữ cảnh mỗi phiên — nhưng chỉ khi tổ chức đúng theo 3 pattern trên. Tổ chức sai (dồn hết vào 1 file dài, hoặc lồng tham chiếu quá sâu) triệt tiêu toàn bộ lợi ích của progressive disclosure.

4. Cơ chế hoạt động

Khi SKILL.md được kích hoạt và nội dung tham chiếu tới 1 file resource cụ thể, Claude đọc file đó qua 1 lệnh bash riêng — file khác không được tham chiếu tới trong tác vụ hiện tại vẫn nằm nguyên trên filesystem, không tốn 1 token ngữ cảnh nào [S74] [S75]. Đây là lý do pattern “domain-specific organization” hiệu quả: nếu người dùng chỉ hỏi về doanh số, Claude chỉ đọc sales.md, hoàn toàn không chạm tới finance.md hay marketing.md.

5. Mental model

Tiếp nối ẩn dụ “hồ sơ đào tạo”: nếu instructions (bài 32) là nội dung chính của hồ sơ, thì resources là phụ lục đính kèm — biểu mẫu tham khảo, sổ tay tra cứu, công cụ đi kèm. 1 phụ lục tốt được dẫn chiếu rõ ràng ngay trong nội dung chính — không phải phụ lục dẫn tới phụ lục khác dẫn tới phụ lục khác nữa (vi phạm quy tắc “1 tầng sâu”).

6. Hướng dẫn từng bước

Liệt kê mọi kiến thức/tài liệu Skill cần dùng ngoài quy trình chính.
Với mỗi tài liệu, hỏi: đây là kiến thức để đọc (tài liệu tham khảo) hay thao tác để chạy (script)?
Nếu có nhiều miền chủ đề độc lập → dùng pattern “domain-specific” (chia theo file riêng từng miền).
Nếu chỉ có 1 luồng chính + vài tính năng phụ hiếm dùng → dùng pattern “conditional details” hoặc “high-level guide with references”.
Đảm bảo mọi file được link trực tiếp từ SKILL.md — không lồng qua trung gian.
Với file dài hơn 100 dòng, thêm mục lục ở đầu.
Với mỗi script, ghi rõ trong SKILL.md: “Chạy [tên script] để…” (thực thi) hoặc “Xem [tên script] để biết logic…” (đọc tham khảo) — không để nhập nhằng.

7. Ví dụ thực tế

Áp dụng đúng pattern “domain-specific organization” — ví dụ chính thức (S77):

bigquery-skill/
├── SKILL.md (tóm tắt, link tới từng miền)
└── reference/
    ├── finance.md (doanh thu, billing)
    ├── sales.md (pipeline, cơ hội bán hàng)
    ├── product.md (sử dụng API, tính năng)
    └── marketing.md (chiến dịch, attribution)

Khi người dùng hỏi về doanh số, Claude chỉ đọc sales.md — 3 file còn lại “nằm im” trên filesystem, không tốn token [S77].

Ví dụ thật — ai-mastery-bible dùng đúng pattern “high-level guide with references”: SKILL.md của dự án này có 1 “Reference index” (bảng ánh xạ tình huống → file cần đọc), dẫn thẳng tới đúng 1 trong 10 file references/*.md tương ứng — không có file nào trong references/ dẫn tiếp sang file khác (đúng quy tắc “1 tầng sâu”). Bằng chứng thực tế cho thấy dự án đang tự áp dụng đúng nguyên tắc S77 mô tả, dù được viết trước khi bài học này tồn tại.

8. Prompt/template/workflow

Skill của bạn có...
- Nhiều miền chủ đề độc lập, ít liên quan nhau? → Domain-specific organization
- 1 luồng chính + vài tính năng nâng cao hiếm dùng? → Conditional details
- 1 luồng chính, cần thêm chi tiết tra cứu riêng? → High-level guide with references

## Tài nguyên đi kèm
- **[ten-file.md](ten-file.md)** — [1 câu mô tả nội dung, khi nào cần đọc]
- **[ten-script.py](scripts/ten-script.py)** — Chạy để [mục đích]. KHÔNG
  cần đọc mã nguồn, chỉ cần chạy.

9. Visual hoặc diagram cần thiết

Hình 4.4 — 3 pattern tổ chức resources: high-level guide, domain-specific, conditional details. [S77]

10. Bài tập thực hành

Với Skill giả định từ bài 29/32, liệt kê ít nhất 3 tài liệu/script cần đóng gói — phân loại từng cái là “đọc” hay “chạy”.
Chọn 1 trong 3 pattern (mục 8) và vẽ cây thư mục tương ứng.
Kiểm tra lại: có file nào bị lồng quá 1 tầng tham chiếu không? Nếu có, tổ chức lại cho phẳng.
Mở .claude/skills/ai-mastery-bible/SKILL.md và tìm phần “Reference index” — xác nhận đúng là pattern “high-level guide with references”.

11. Checklist

Phân biệt rõ 'Knowledge' của Skill (bài này) với 'Knowledge base' của Project (bài 21) — không dùng lẫn 2 khái niệm.
Chọn đúng 1 trong 3 pattern tổ chức resources cho 1 tình huống cụ thể.
Áp dụng đúng quy tắc '1 tầng sâu' và 'mục lục cho file dài'.
Ghi rõ trong hướng dẫn: file nào để đọc, file nào để chạy.

12. Lỗi thường gặp

Nhầm Skill resources với Project Knowledge base — 2 cơ chế hoàn toàn khác nhau (xem bảng đầu bài).
Tham chiếu lồng quá 1 tầng — SKILL.md → A → B → C — khiến Claude đọc thiếu do chỉ lướt qua các tầng sâu [S77].
Không ghi rõ “chạy” hay “đọc” cho 1 file resource — Claude có thể đọc hết mã nguồn 1 script dài thay vì chỉ chạy nó, lãng phí token không cần thiết.
Dồn hết nội dung vào 1 file duy nhất — mất hoàn toàn lợi ích progressive disclosure.

13. Giới hạn & khi nào KHÔNG nên áp dụng

Không áp dụng cho Project Knowledge base (bài 21) — khác cơ chế hoàn toàn, dù cùng dùng chữ “Knowledge”/“file”.
Skill đơn giản, không cần tài liệu/script phụ nào → không cần áp dụng 3 pattern này, giữ mọi thứ trong SKILL.md (miễn dưới 500 dòng, bài 31) là đủ.

14. An toàn & quản trị (Safety/Governance)

Vì script trong resources có thể thực thi được, phần audit an toàn đã nêu ở bài 31 áp dụng trực tiếp ở đây: đọc hết mọi file trong thư mục resources/scripts trước khi tin dùng 1 Skill không do bạn tự viết — không chỉ đọc SKILL.md. Tài liệu/script tham chiếu tới nguồn dữ liệu bên ngoài (API, database) cần được xem xét kỹ hơn vì rủi ro rò rỉ dữ liệu nếu Skill từ nguồn không đáng tin.

15. Best practices

Ưu tiên script cho thao tác cần độ chính xác/nhất quán tuyệt đối (mức độ tự do thấp, bài 32); ưu tiên tài liệu tham khảo cho kiến thức cần áp dụng linh hoạt.
Đặt tên file mô tả rõ nội dung (form_validation_rules.md, không phải doc2.md) [S77].
Luôn kiểm tra lại quy tắc “1 tầng sâu” mỗi khi thêm file resource mới.

16. Nội dung nâng cao (không bắt buộc)

Với Skill nhiều miền chủ đề lớn, pattern “domain-specific organization” có thể kết hợp với 1 kỹ thuật tìm kiếm nhanh: hướng dẫn Claude dùng lệnh grep để tìm từ khóa cụ thể trong các file reference/ trước khi quyết định đọc toàn bộ file nào [S77] — hữu ích khi số lượng file tham khảo lớn tới mức người viết Skill khó liệt kê hết trong SKILL.md.

17. Nguồn tham khảo

[S77] Skill authoring best practices, Anthropic — 3 pattern tổ chức, quy tắc 1 tầng sâu, mục lục file dài · [S74] Extend Claude with skills, Anthropic — phân biệt Instructions/Code/Resources theo cách Claude truy cập · [S75] Agent Skills (Overview), Anthropic — bảng 3 tầng progressive disclosure, chi phí token từng tầng · Ví dụ thực tế: .claude/skills/ai-mastery-bible/ (cấu trúc references/ thật, đối chiếu mục 7).

18. Ngày kiểm chứng

Claim kỹ thuật kiểm chứng qua nguồn Tier 1 (S74, S75, S77) ngày 2026-07-12.