Skill System: Từ SKILL.md đến progressive disclosure — Giải pháp cho bệnh 'ngập context' của AI agent

Nếu bạn từng thấy Claude Code bỗng nhiên "quên" cách viết test dù đã dặn kỹ ở turn thứ 3, hoặc agent bắt đầu tự bịa cú pháp sau 30 phút làm việc — đó không phải lỗi model. Đó là "context rot": hiện tượng attention mechanism của LLM bị pha loãng khi phải ôm đồm quá nhiều thủ tục trong một prompt duy nhất. Skill System ra đời để giải quyết bài toán này: làm sao để agent "nhớ" cách làm việc mà không phải mang theo cuốn hướng dẫn 5000 từ trong đầu suốt cả ngày.

Vấn đề

Truyền thống "prompt engineering" thường đi vào lối mòn monolithic: nhét toàn bộ quy trình làm việc, tiêu chuẩn code, và danh sách công cụ vào một system prompt dài 3K–8K tokens. Kết quả? Agent bị "lost in the middle" — nó nhớ rõ những gì ở đầu và cuối prompt, nhưng các chỉ dẫn quan trọng ở giữa bị attention mechanism "làm ngơ" sau 10–20 turn hội thoại.

Vấn đề còn tệ hơn khi bạn có nhiều domain: một agent đồng thời phải biết "cách viết Python", "cách query SQL", "cách vẽ chart", và "cách đọc CSV". Các thủ tục này "chảy máu" vào nhau (interference), khiến agent dùng cú pháp SQL trong file Python, hoặc quên validate data trước khi vẽ biểu đồ. Càng thêm nhiều hướng dẫn, hiệu suất càng giảm — đây là context dilution, không phải do thiếu dung lượng context window, mà do cách chúng ta "ép" LLM phải chú ý đến quá nhiều thứ đồng thời.

Ý tưởng cốt lõi

Progressive disclosure (tiết lộ dần dần) là kiến trúc chia nhỏ kiến thức thành 3 tầng, chỉ load khi cần — giống như bác sĩ ở bệnh viện không mang theo 50 cuốn giáo khoa y khoa trong túi, mà chỉ cần tấm thẻ triage trên cổ tay ghi "Nếu đau ngực → gọi khoa Tim".

Tầng 1: Metadata (Routing Index)

Khi agent "thức dậy", nó chỉ load index card từ tất cả skill: name (tối đa 64 ký tự) và description (tối đa 200 ký tự, theo chuẩn Anthropic). Đây là "bản đồ sitemap" cho agent biết khi nào nên dùng skill nào, nhưng chưa chứa nội dung thực thi.

Ví dụ cấu trúc thư mục:

~/.claude/skills/
├── data-analysis/
│   ├── SKILL.md          # Tier 2 & 3
│   └── assets/
│       └── pandas_helpers.py
└── sql-query/
    └── SKILL.md

Nội dung SKILL.md — phần YAML frontmatter (Tier 1):

name: analyze_csv
description: "Use this when user asks about CSV statistics, data cleaning, or visualization. Requires file_path input. Do NOT use for Excel files."
---

200 ký tự trong description này đóng vai trò routing hash: agent so sánh semantic similarity giữa yêu cầu người dùng với description để quyết định có nên "mở sách" hay không. Chi phí token cho việc này cực rẻ: ~50–100 tokens/skill, so với 2000+ tokens nếu load cả hướng dẫn.

Tầng 2: Instructions (Execution Context)

Khi description match, toàn bộ SKILL.md được load vào context window. Phần sau dấu --- (Markdown body) chứa:

• Workflow bước bước: "1. Validate schema, 2. Check nulls, 3. Generate chart"
• Negative constraints: "KHÔNG ĐƯỢC dùng matplotlib nếu user yêu cầu interactive"
• Tool schemas: Các MCP tool hoặc Python script được phép gọi

Lúc này, context window chỉ chứa một nhiệm vụ chuyên sâu thay vì 10 nhiệm vụ chồng chéo. Đây là khoảnh khắc "à, chỉ vậy thôi": agent không còn bị phân tâm bởi SQL syntax khi đang làm việc với Pandas, vì nó chỉ "cầm" một cuốn sách lúc một thời điểm.

Tầng 3: Lazy Assets (Cold Storage)

Các file nặng — Python scripts, CSV mẫu, hoặc tài liệu tham khảo — nằm trong subfolders (assets/, references/). Chúng chỉ được đọc khi skill đang chạy và gọi explicit read (ví dụ: @read_file assets/pandas_helpers.py). Điều này tránh "nghẽn" context window bởi code dài khi agent chỉ cần biết "có thể dùng helper này".

Packaging & Distribution

Skill là folder-based: một thư mục skill phải được ZIP với tên thư mục làm root (không zip lẻ tẻ file rời). Cấu trúc này cho phép:

• Versioning: Skill là immutable package, giống như Docker image
• Sharing: Copy folder là chuyển được "cách làm việc" sang project khác
• Auto-discovery: Agent scan ~/.claude/skills/ hoặc .claude/skills/ (project-local) để load index

Tại sao nó hoạt động

Tách biệt "biết đường" khỏi "biết làm" (Separation of Routing vs Execution Knowledge) là nguyên lý then chốt.

Trong kiến trúc monolithic, LLM phải đồng thời: (1) quyết định có nên dùng pandas không, và (2) nhớ cách dùng pandas. Hai tác vụ này chiếm cùng một không gian attention, gây interference. Progressive disclosure tách chúng ra:

• Routing layer (Tier 1): Chỉ cần fuzzy matching semantic — "user nói về CSV → match analyze_csv"
• Execution layer (Tier 2): Sau khi quyết định xong, toàn bộ attention được dành cho việc thực thi đúng một nhiệm vụ.

Trade-off ở đây là cold start latency: lần đầu gọi skill mất thêm 50–200ms để đọc file và parse Markdown. Nhưng sau đó, trong khi skill đang active, context window "sạch" hơn nhiều so với việc giữ nguyên 5000 token hướng dẫn từ đầu session. Với session dài (>20 turns), chi phí này được đền bù gấp bội bởi độ chính xác tăng và lỗi "quên lệnh" giảm.

Một lợi ích phụ: Description field ép buộc tính rõ ràng. Giới hạn 200 ký tự buộc người viết skill phải định nghĩa intent (khi nào dùng) thay vì implementation (làm thế nào). Điều này ngăn agent dùng skill sai ngữ cảnh — ví dụ skill "data-analysis" không bị trigger bởi câu "analyze this poem" vì description rõ ràng ghi "Use for CSV data only".

Ý nghĩa thực tế

Benchmark từ SkillsBench (2025): Skill descriptions thường nén 500–2000 tokens thủ tục thành 100–200 tokens routing text, giảm "lost in the middle" error rate từ ~15% xuống <2% trên các tác vụ dài hạn.

Ai đang dùng:

• Claude Code: Hỗ trợ 5–50 skills đồng thời (thay vì một prompt 5K tokens), giới thiệu tháng 10/2025, mở chuẩn tháng 12/2025
• OpenAI Codex: Áp dụng mô hình tương tự với "commands"
• GitHub Copilot: Workspace prompts đóng vai trò Tier 2 (lazy load theo context)

Hạn chế:

• Không phải cho personality: Skill xử lý thủ tục (procedures), không xử lý tính cách (personality). Nếu muốn agent luôn "lịch sự và ngắn gọn", dùng CLAUDE.md (SOUL.md) — file định danh được load mọi lúc, không phải skill.
• Optimization loop: Viết description sai (quá chung chung hoặc quá hẹp) dẫn đến under-triggering (skill không bao giờ chạy) hoặc over-triggering (skill chạy lung tung). Cần iterative testing giống như hyperparameter tuning.
• Cold start I/O: Skill lớn với nhiều assets có thể gây lag ở lần đầu, cần caching ở tầng infrastructure.

Đào sâu hơn

Tài liệu chính thức:

• Anthropic Claude Help Center — Custom Skills: Quy định chuẩn YAML frontmatter và giới hạn 200 ký tự description
• GitBook — skill.md explained: Pattern progressive disclosure cho documentation

Cùng cụm (Skills & Tools):

Đọc tiếp:

Tài liệu mở rộng:

• Paper "Agent Skills for Large Language Models" (arXiv:2602.12430, 2025): Phân tích kiến trúc skill từ góc độ security và acquisition
• Reddit r/ClaudeCode — Reverse engineering Claude's skill system: Insight thực chiến về cách Claude quyết định load skill nào khi có 5–50 skill cùng lúc