Tôi đã sai về Agent Skills và cách tôi tái cấu trúc chúng

Thật đáng xấu hổ vì giải pháp đã nằm ngay trước mặt tôi cả thời gian. Tôi đã đối xử với agent skills như những đống tài liệu thay vì những gì chúng thực sự là: vấn đề về context engineering.

Chuyện gì đã xảy ra

Agent Skills ra mắt ngày 16 tháng 10. Tôi bắt đầu xây dựng chúng ngay lập tức. Trong vòng hai tuần, tôi đã có skill cloudflare với 1,131 dòng, skill shadcn-ui với 850 dòng, skill nextjs với 900 dòng, skill chrome-devtools với >1,200 dòng.

Repo của tôi nhanh chóng đạt hơn 400 sao.

Nhưng...

Mỗi khi Claude Code kích hoạt nhiều skill liên quan, tôi thấy context window phình to đáng kể. Nạp 5-7 skill có nghĩa là 5,000-7,000 dòng tràn vào context window ngay lập tức.

Tôi nghĩ đây là cách duy nhất phải làm.

Cho tất cả mọi thứ vào một file SKILL.md khổng lồ để agent có đầy đủ thông tin ngay từ đầu.

Nhiều thông tin hơn = kết quả tốt hơn, đúng không?

Sai.

—

Sự thật…

Thật đáng xấu hổ vì giải pháp đã nằm ngay trước mặt tôi cả thời gian.

Tôi đã đối xử với agent skills như những đống dump tài liệu thay vì những gì chúng thực sự là: vấn đề về context engineering.

Phần đáng thất vọng là tôi thậm chí đã ghi lại nguyên tắc “progressive disclosure” trong chính skill skill-creator.

Tôi đã viết nó ra.
Tôi chỉ không hiểu nó thực sự có nghĩa gì trong thực tế.

Đây là điều thực sự khiến tôi bực mình: Tôi đã lãng phí hai tuần để debug các vấn đề về “context tăng trưởng” và thời gian kích hoạt chậm khi vấn đề hoàn toàn do chính tôi gây ra. Mỗi một trong những file SKILL.md khổng lồ đó đều nạp thông tin không liên quan 90% thời gian.

—

Chi tiết kỹ thuật

Trước đây: 🫣

.claude/skills/
├── cloudflare/           1,131 dòng
├── cloudflare-workers/   ~800 dòng
├── nextjs/               ~900 dòng
├── shadcn-ui/            ~850 dòng
├── chrome-devtools/      ~1,200 dòng
└── (30 file phình to tương tự khác)

Tổng cộng: ~15,000 dòng trên 36 skills (Khoảng 120K đến 300K tokens)

Vấn đề: Kích hoạt context devops (Cloudflare hoặc Docker hoặc GCloud liên tục) có nghĩa là nạp 2,500+ dòng ngay lập tức. Hầu hết trong đó không bao giờ được dùng.

Sau này: Kiến trúc Progressive Disclosure

Tôi đã tái cấu trúc bằng hệ thống nạp 3 tầng:

Tầng 1: Metadata (luôn được nạp)

• Chỉ YAML frontmatter

• ~100 từ

• Vừa đủ để Claude quyết định xem skill có liên quan không

Tầng 2: Entry point SKILL.md (được nạp khi skill kích hoạt)

• Tối đa ~200 dòng

• Tổng quan, quick start, bản đồ điều hướng

• Trỏ đến references nhưng không bao gồm nội dung của chúng

Tầng 3: Reference files & scripts (nạp theo yêu cầu)

• 200-300 dòng mỗi file

• Tài liệu chi tiết Claude chỉ đọc khi cần

• Modular và tập trung vào từng topic riêng lẻ

Con số

Tái cấu trúc skill claude-code:

• Trước: 870 dòng trong một file

• Sau: 181 dòng + 13 reference files

• Giảm: 79% (hiệu quả token tốt hơn 4.8 lần)

Tái tổ chức hoàn chỉnh Giai đoạn 1 & 2:

• Trước: 15,000 dòng trên 36 skill riêng lẻ

• Sau: Hợp nhất thành 20 nhóm skill tập trung (2,200 dòng nạp ban đầu + 45 reference files)

  • devops (Cloudflare, Docker, GCloud - 14 công cụ)

  • web-frameworks (Next.js, Turborepo, RemixIcon)

  • ui-styling (shadcn/ui, Tailwind, canvas-design)

  • databases (MongoDB, PostgreSQL)

  • ai-multimodal (Gemini API - 5 modalities)

  • media-processing (FFmpeg, ImageMagick)

  • chrome-devtools, code-review, sequential-thinking, docs-seeker, mcp-builder,...

• Giảm: 85% khi kích hoạt ban đầu

Tác động thực tế:

• Thời gian kích hoạt: ~500ms → <100ms

• Context overflow: Nhanh → Chậm

• Tỷ lệ thông tin liên quan: ~10% → ~90%

—

Phân tích nguyên nhân gốc rễ

Sai lầm cơ bản:
Tôi đã nhầm lẫn giữa “thông tin có sẵn” với “thông tin được nạp”.

Nhưng một lần nữa, có một sự hiểu lầm sâu xa hơn: Agent skills không phải là tài liệu.

Chúng là khả năng và kiến thức cụ thể cho quy trình phát triển. Mỗi skill đại diện cho một năng lực:

• devops không phải là “tài liệu Cloudflare” - đó là khả năng triển khai serverless functions

• ui-styling không phải là “tài liệu Tailwind” - đó là khả năng thiết kế giao diện nhất quán

• sequential-thinking không phải là hướng dẫn - đó là phương pháp giải quyết vấn đề

Tôi đã có 36 skill riêng lẻ vì tôi đối xử với mỗi công cụ như thể cần một đống dump tài liệu riêng. Sai rồi. Skills nên được tổ chức theo khả năng quy trình làm việc, không phải theo công cụ.

Đó là lý do tại sao việc hợp nhất hiệu quả:

• 36 skill theo công cụ cụ thể → 20 nhóm khả năng quy trình làm việc

• “Đây là mọi thứ về Cloudflare” → “Đây là cách xử lý triển khai DevOps với Cloudflare, GCloud, Docker, Vercel.”

• Tư duy tài liệu → Tư duy quy trình phát triển

Giới hạn 200 dòng không phải tùy ý — dù tôi đã “bịa” ra nó — nhưng nó có cơ sở.

Nó dựa trên lượng context mà LLM có thể quét hiệu quả để quyết định nạp gì tiếp theo. Giữ entry point dưới ~200 dòng, và Claude có thể nhanh chóng:

• Hiểu skill cung cấp gì

• Quyết định reference file nào cần đọc

• Chỉ nạp file đó (thêm ~200-300 dòng)

Tổng cộng: 400-700 dòng context cực kỳ liên quan thay vì 1,131 dòng với độ liên quan lẫn lộn.

Đây là “context engineering” và tôi đã bỏ lỡ nó.

Bài học kinh nghiệm

1. Quy tắc 200 dòng quan trọng - Đây không phải là gợi ý. Đó là sự khác biệt giữa điều hướng nhanh và bùn lầy context.

2. Progressive disclosure không phải tùy chọn - Mọi skill trên 200 dòng đều nên được tái cấu trúc. Không ngoại lệ. Nếu bạn không thể cho hướng dẫn cốt lõi vào 200 dòng, bạn đang đặt quá nhiều vào entry point.

3. References là công dân hạng nhất - Tôi đã đối xử với references/ như “tài liệu bổ sung tùy chọn.” Sai rồi. References là nơi công việc thực sự diễn ra. SKILL.md chỉ là bản đồ.

4. Test cold start - Xóa context của bạn, kích hoạt skill, và đo lường. Nếu nó nạp hơn 500 dòng khi kích hoạt lần đầu, bạn đang làm sai.

5. Metrics không bao giờ nói dối - Hiệu quả token tốt hơn 4.8 lần không phải cải thiện nhỏ. Đó là sự khác biệt giữa “đôi khi hoạt động” và “hoạt động đáng tin cậy.”

Cách làm này đã được kiểm chứng.

---

Túm lại

Skills ≠ Tài liệu

Skills là khả năng kích hoạt trong các thời điểm quy trình làm việc cụ thể:

• Viết tests → kích hoạt code-review

• Debug production → kích hoạt sequential-thinking

• Deploy infrastructure → kích hoạt devops

• Xây dựng UI → kích hoạt ui-styling + web-frameworks

Mỗi skill dạy Claude cách thực hiện một tác vụ phát triển cụ thể, không phải công cụ làm gì.

Đó là lý do tại sao đối xử với chúng như tài liệu thất bại.
Tài liệu là tài liệu tham khảo thụ động.

Skills là kiến thức quy trình làm việc chủ động.

Progressive disclosure hoạt động vì nó khớp với cách phát triển thực sự diễn ra:

1. Quét metadata → Khả năng này có liên quan đến tác vụ hiện tại không?

2. Đọc entry point → Skill này cho phép những mô hình quy trình làm việc nào?

3. Nạp reference cụ thể → Lấy chi tiết triển khai cho bước hiện tại

Mỗi bước đều nhỏ, tập trung và có mục đích. Đó là cách bạn xây dựng skills thực sự giúp ích thay vì áp đảo về số lượng.

---

Phần đau đớn không phải là tôi đã sai ngay từ đầu — Agent Skills hoàn toàn mới (3 tuần tuổi).

Phần đau đớn là tôi đã tự viết ra giải pháp mà không hoàn toàn hiểu nó.

Hai tuần cắm đầu.
Một cuối tuần tái cấu trúc.

Bài học:
Context engineering không phải về việc nạp nhiều thông tin hơn.
Đó là về việc nạp đúng thông tin vào đúng thời điểm.

Nếu bạn muốn xem repo thì có thể bấm các link bên dưới:

• Trước (v1 branch): https://github.com/mrgoonie/claudekit-skills/tree/v1

• Sau (main branch): https://github.com/mrgoonie/claudekit-skills/tree/main