✍️ Goon's Solo Playbook

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)

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

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

Con số

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

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

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

—

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

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:

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ả:

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:

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.

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ể:

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.

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.

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

Link nội dung: https://superkids.edu.vn/november-dump-la-gi-a32147.html