Kỹ Năng Có Thể Thực Thi Cho Agents Tốt Hơn Tài Liệu

57% nhóm tài liệu không theo dõi liệu tài liệu của họ có thúc đẩy kết quả kinh doanh nào không. 88% nói tài liệu quan trọng đối với quyết định mua hàng. (GitBook State of Docs 2026.) Trong khi đó, gần một nửa lưu lượng truy cập trang web tài liệu hiện đến từ AI agents — những người không thể cho bạn biết họ có tìm thấy những gì họ cần không (Mintlify).

Đối tượng của tài liệu đã thay đổi. Định dạng thì không.

Người Viết Đã Thay Đổi

Suốt hàng thập kỷ, quy trình đơn giản: con người viết spec, sau đó triển khai mã để khớp. Tài liệu là nguồn sự thật.

Thứ tự đó đã đảo ngược. AI agents tạo mã và tài liệu đồng thời, trong định dạng được thiết kế cho các agents khác tiêu thụ. Spec và triển khai giờ đây là cùng một sản phẩm.

graph TD
  subgraph era1 ["Trước 2025"]
      direction LR
      A["Nhà phát triển viết docs"] --> B["Nhà phát triển triển khai mã"]
  end
  subgraph era2 ["2023–2026"]
      direction LR
      C["AI agent viết mã"] --> D["AI agent cập nhật docs"]
  end
  subgraph era3 ["2026+"]
      direction LR
      E["AI agent viết docs + mã"] --> F["Agent khác tiêu thụ skills"]
  end
  B -.-> C
  D -.-> E

Thế hệ đầu tiên tài liệu hướng đến agent — OpenWiki, Mintlify, AGENTS.md — đã giải quyết vấn đề thực tế: agents cần context về các codebase không quen thuộc. Nhưng giải pháp tạo ra vấn đề mới: tạo tóm tắt dễ đọc cho con người về mã mà agent đã có thể đọc trực tiếp. Người trung gian là thừa nhưng cần bảo trì.

Các Phương Pháp Hiện Tại Không Hiệu Quả

Hệ sinh thái tài liệu hiện nay có bốn phương pháp. Mỗi phương pháp thất bại theo một cách khác nhau.

graph LR
  A["Tài liệu truyền thống"] -->|"Viết cho con người"| B["Không ai đọc"]
  B --> C["Cũ, không bảo trì"]

  D["Tài liệu code-first"] -->|"Tạo cho agents"| E["Agents có thể đọc mã trực tiếp"]
  E --> F["Người trung gian thừa"]

  G["Spec-driven"] -->|"Spec toàn diện"| H["Context rot giảm hiệu suất"]
  H --> I["Phản tác dụng"]

Chroma đã đánh giá 18 LLM vào tháng 7 năm 2025 và phát hiện rằng “hiệu suất model thay đổi đáng kể khi độ dài đầu vào thay đổi, ngay cả trên các tác vụ đơn giản” — hiện tượng mà họ gọi là context rot (Báo cáo kỹ thuật Chroma). Hướng dẫn context engineering của Anthropic (tháng 9 năm 2025) mô tả cùng vấn đề: “LLMs có ‘ngân sách attention’ mà chúng sử dụng khi phân tích volume context lớn. Mỗi token mới được giới thiệu đều giảm ngân sách này” (Anthropic).

ThoughtWorks Technology Radar Vol 34 (tháng 4 năm 2026) đã gắn cờ agent instruction bloat ở mức Caution: “Các file context như AGENTS.md và CLAUDE.md có xu hướng tích lũy theo thời gian… Hướng dẫn trở nên dài và đôi khi mâu thuẫn với nhau. Các model có xu hướng chú ý ít hơn đến nội dung bị chôn vùi ở giữa các context dài” (ThoughtWorks).

Tài Liệu Là Thừa Đối Với Agents

Vấn đề không phải là tài liệu được viết kém. Mà là mỗi trang tài liệu nhân bản mã đang ở bên cạnh nó.

Tài liệu code-first giải quyết vấn đề “tại sao” — Han Wang, đồng sáng lập Mintlify: “Mã chỉ cho bạn biết cái gì đã được xây dựng, không phải tại sao.” Nhưng giải pháp giới thiệu sự cũ kỹ, bảo trì và chi phí token. Mỗi trang tài liệu là phái sinh của mã bên cạnh nó. Đối với agent có thể đọc mã, phái sinh là thừa.

ThoughtWorks Technology Radar Vol 34 đã đánh giá context engineering ở mức Adopt và progressive context disclosure ở mức Trial — khuyến nghị là “bắt đầu với index nhẹ về những gì có sẵn, để agent xác định những gì liên quan và chỉ kéo vào những gì cần thiết” (ThoughtWorks).

Skills Thay Vì Tài Liệu

Phương án thay vì tạo tài liệu là tạo skills.

graph TD
  subgraph trad ["Tài liệu truyền thống"]
      direction LR
      A1["Con người viết"] --> A2["File markdown"]
      A2 --> A3["Agent đọc như context"]
  end
  subgraph code ["Tài liệu code-first"]
      direction LR
      B1["Mã đã tồn tại"] --> B2["Agent tạo markdown"]
      B2 --> B3["Agent khác đọc markdown"]
  end
  subgraph skill ["Skills"]
      direction LR
      C1["Chuyên gia lĩnh vực chat"] --> C2["Agent tạo skill"]
      C2 --> C3["Con người xác minh"]
      C3 --> C4["VM sandbox thực thi"]
  end
  A3 -.-> B1
  B3 -.-> C1

Skills sử dụng cùng đóng gói như tài liệu — markdown, YAML frontmatter, tham chiếu có cấu trúc. Nhưng chúng được tiêu thụ bởi agents, không phải con người. Sự khác biệt quan trọng: chúng chứa các hàm TypeScript có thể thực thi chạy trong VM sandbox trên mỗi tin nhắn khách hàng đến.

Chủ spa gõ: “massage sâu của chúng tôi giá $90 cho 60 phút, $120 cho 90 phút, và chúng tôi giảm giá 10% cho thành viên.” Nền tảng tạo hàm quoteOrder() trả về $108 cho đặt chỗ 90 phút của thành viên. Mỗi lần.

export function quoteOrder(order: Order): QuoteResult {
  const item = order.items[0];
  const base = offerings[item.service].durations[item.duration];
  const memberDiscount = order.member ? 0.9 : 1.0;
  return { total: base * memberDiscount };
}

Kết quả nằm trong các thư mục skill có cấu trúc:

/sales-assistant/skills/
  offerings/
    skill.md              # YAML frontmatter + hướng dẫn
    reference.md          # Danh mục sản phẩm có cấu trúc
    schema/
      schema.json         # JSON Schema (nguồn sự thật)
      schema.ts           # Kiểu TypeScript (tự động tạo)
  pricing-rules/
    skill.md
    reference.md          # Quy tắc giá trong markdown có cấu trúc
    scripts/
      function.js         # quoteOrder(order) -> QuoteResult

Quy Trình

graph LR
  A["Chuyên gia mô tả quy tắc kinh doanh"] -->|"Ngôn ngữ tự nhiên"| B["Agent tạo skill"]
  B --> C{"Con người xem xét"}
  C -->|"Phê duyệt"| D["Skill phiên bản hóa trong MongoDB"]
  C -->|"Chỉnh sửa"| E["Được sửa đổi và phê duyệt lại"]
  D --> F["Được tải khi chạy"]
  F --> G["VM sandbox thực thi"]
  G --> H["Kết quả xác định với audit trail"]

Xác Minh Của Con Người: Vẫn Cần Thiết

Skills được viết cho agents, nhưng con người xác minh chúng trước khi triển khai. Mỗi thay đổi skill đều qua cổng phê duyệt. Chủ doanh nghiệp xem mã được tạo, có thể chỉnh sửa hoặc từ chối.

Điều này phục vụ hai mục đích. Thứ nhất, chuyên gia lĩnh vực xác nhận skill khớp với ý định — họ mô tả quy tắc bằng ngôn ngữ tự nhiên, và bây giờ họ thấy phiên bản có thể thực thi. Thứ hai, phê duyệt của con người tạo audit trail cho tuân thủ.

Skills dễ đọc cho con người để xác minh có thể thực hiện. Vai trò của con người là phán đoán, không phải sáng tạo.

Xác Nhận Từ Thị Trường

ThoughtWorks Technology Radar Vol 34 đã đánh giá hai mẫu liên quan:

• Agent Skills ở mức Trial: “Agents chỉ tải skills khi cần dựa trên mô tả của chúng, giúp giảm chi phí token và giảm thiểu sự cạn kiệt context window cũng như các vấn đề như agent instruction bloat” (ThoughtWorks).
• Progressive context disclosure ở mức Trial: “Thay vì làm cho agent ngợp hướng dẫn ngay từ đầu, bạn cung cấp giai đoạn khám phá nhẹ trong đó agent chọn những gì nó cần dựa trên prompt của người dùng, tải thông tin chi tiết vào context window chỉ khi nó trở nên liên quan” (ThoughtWorks).

Cả hai mẫu mô tả cùng giải pháp: cung cấp cho agent menu skills, để nó chọn những gì cần, chỉ thực thi những gì liên quan.

graph LR
  A["Agent nhận task"] --> B{"Index"}
  B -->|"pricing"| C["Skill pricing-rules"]
  B -->|"scheduling"| D["Skill scheduling"]
  B -->|"validation"| E["Skill validation"]
  C --> F["Thực thi"]
  D --> F
  E --> F
  F --> G["Kết quả xác định"]

Khi Nào Dùng Gì

Điều Gì Thay Đổi

Tài liệu không lỗi thời. Markdown hoạt động cho con người. Nhưng khi AI agents là người đọc chính, định dạng hữu ích nhất không phải văn xuôi về mã — mà là mã.

Skills biến quy tắc kinh doanh thành các hàm có thể thực thi. Agents tải chúng, chạy chúng, và trả về kết quả xác định. Con người xác minh thay vì viết. Hệ thống tạo lại skills khi quy tắc thay đổi.

Sự chuyển đổi là từ mô tả hành vi sang mã hóa nó.

Đọc Thêm

• OpenWiki vs QuotyAI — hai dự án LangChain DeepAgents, hai kiến trúc
• Spec-Driven vs Code-First vs Chat-to-code — ba triết lý để dạy AI về doanh nghiệp của bạn
• Determinism as Infrastructure — tại sao nền tảng AI cần thực thi xác định
• Open Knowledge Format vs Agent Skills — tại sao thực thi xác định tốt hơn file kiến thức tĩnh

Câu Hỏi Thường Gặp

Nếu agents có thể đọc mã, tại sao chúng cần tài liệu? Chi phí token. Đọc 5 file source tốn hàng nghìn token. Một file skill được cấu trúc tốt tốn ít hơn và chỉ chứa những gì agent cần. Progressive context disclosure có nghĩa là agent tải skills theo yêu cầu, không phải tất cả cùng lúc (ThoughtWorks).

Sự khác biệt giữa skill và tài liệu là gì? Tài liệu mô tả mã làm gì. Skills là mã — có thể thực thi, phiên bản hóa, xác nhận và chạy trong VM sandbox trên mỗi request. Một trang tài liệu nói với agent “pricing hoạt động như thế này.” Một skill cung cấp cho agent hàm quoteOrder() trả về $108.

Tại sao không dùng AGENTS.md hoặc CLAUDE.md? Đây là các file tĩnh, do con người viết, bị suy giảm theo thời gian. ThoughtWorks đánh giá sự phình to hướng dẫn agent là mức Caution — “Hướng dẫn trở nên dài và đôi khi mâu thuẫn với nhau. Các model có xu hướng chú ý ít hơn đến nội dung bị chôn vùi ở giữa các context dài” (ThoughtWorks).

Skills cho agents có phải chỉ là tài liệu với thêm bước? Không. Tài liệu là context thụ động. Skills là thực thi chủ động. Một trang tài liệu nói với agent “pricing hoạt động như thế này.” Một skill cung cấp cho agent hàm quoteOrder() chạy và trả về $108. Sự khác biệt giống như việc đọc về một hàm so với gọi nó.

Ai duy trì skills khi quy tắc kinh doanh thay đổi? Chủ doanh nghiệp mô tả thay đổi bằng ngôn ngữ tự nhiên. Hệ thống tạo lại tất cả skills bị ảnh hưởng tự động. Chủ doanh nghiệp phê duyệt. Không cần cập nhật tài liệu, không còn trang cũ cần xử lý.

Tags: documentation agent-skills context-engineering ai-agents coding-agents context-rot deterministic-ai progressive-context-disclosure agent-instruction-bloat