Năm bài học từ 226 agent skill của PostHog

Dennis Ivy · PostHog

Năm bài học PostHog rút ra khi viết 226 agent skill: skill là router, không phải code, skill mục theo thời gian, hỏi agent trước, và khi nào không cần skill.

Đã duyệt độc lập · cập nhật 30/10/2026 · 12 min

1. Skill của bạn có thể đang làm agent tệ đi

Dennis Ivy mở đầu bằng một cảnh báo: có thể bạn chưa để ý, nhưng rất có khả năng các skill bạn viết đang làm agent của bạn tệ đi (theo Dennis, video đăng ngày 29/10/2026). Nhiều người nghĩ viết skill tốt hơn nghĩa là đưa cho nó nhiều thông tin hơn, nên họ nhồi vào càng nhiều chi tiết càng tốt. Nhưng theo anh, mỗi dòng bạn thêm vào là thêm một thứ agent phải sàng lọc, và những chi tiết thật sự quan trọng thì có thể bị lạc mất giữa đường.

Dennis Ivy trình bày video này cho kênh PostHog, ngồi trước micro trong một căn phòng ánh đèn vàng.

Theo Dennis (video đăng ngày 29/10/2026), ở PostHog anh và đồng nghiệp đã viết 226 skill trải trên 28 sản phẩm, và đã học được cái gì thật sự hiệu quả, cái gì không. Anh nói thêm rằng trong nhiều trường hợp, anh và nhóm phải học điều đó theo cách đau đớn. Theo phần mô tả video, video dựa trên một bài viết của Ian Vanagas, còn Dennis Ivy viết và trình bày.

Anh hứa sẽ đi qua năm điều đội PostHog học được trong lúc viết những skill này: cách nhận ra các lỗi hiển nhiên, và cách đội PostHog viết những skill hữu ích, có khả năng tự cải thiện (theo video đăng ngày 29/10/2026).

2. Skill là gì: description và details

Trước khi vào năm bài học, Dennis nhắc lại skill là gì. Theo anh (video đăng ngày 29/10/2026), người ta viết skill để khỏi phải lặp lại chính mình. Ý tưởng là ghi một số luật vào file SKILL.md, rồi agent biết lúc nào cần với tới nó mỗi khi bạn làm một loại việc nhất định. Nhờ vậy, bạn không phải prompt lại mọi thứ từ đầu.

Theo Dennis (video đăng ngày 29/10/2026), mỗi skill có hai phần chính: một description (mô tả) và phần details (chi tiết) của skill đó. Phần details là nơi bạn đưa vào hướng dẫn, tài nguyên, và những thứ tương tự.

Hình minh hoạ file SKILL.md chia hai phần Description và Details — Hình minh hoạ trong video (đăng ngày 29/10/2026): phần Description ghi "Use when drafting release notes", phần Details là ba bước "Collect the merged PRs", "Group: New, Improved, Fixed", "One line per change".

Theo Dennis (video đăng ngày 29/10/2026), khi bạn bắt đầu một session, agent biết về tất cả skill của bạn. Dù bạn có 5, 10 hay 100 skill, agent sẽ nạp tất cả vào context của nó. Nhưng nó không nạp toàn bộ skill, mà chỉ nạp phần description. Đó là thứ agent dùng để biết nên với tới skill nào và vào lúc nào. Phần details chỉ được nạp khi agent thật sự gọi skill đó. Tài liệu skill của Claude Code cũng mô tả cùng cơ chế: description luôn nằm trong context, toàn bộ nội dung skill chỉ nạp khi được gọi (đọc ngày 30/10/2026).

Và đây, theo anh, là chỗ mọi người làm cái việc tưởng như hiển nhiên: nhồi càng nhiều thông tin càng tốt vào một skill cụ thể. Dennis gọi đó là lỗi đầu tiên mà ai cũng mắc (video đăng ngày 29/10/2026), và nó dẫn tới bài học thứ nhất.

3. Bài học 1: skill là router, không phải sổ tay

Bài học đầu tiên: một skill là một router, không phải một cuốn sổ tay hướng dẫn (manual). Dennis lấy ví dụ skill truy vấn dữ liệu PostHog của đội anh (video đăng ngày 29/10/2026). Agent cần biết dùng skill này mỗi khi viết một query trên dữ liệu, hoặc khi muốn gọi tool execute-sql. Description được viết để nói rõ điều đó: nói khi nào cần đọc skill, khi nào dùng nó, và nó làm gì. Theo anh, nhóm giữ nó ngắn gọn nhưng đảm bảo nó đi thẳng vào việc.

Description của skill truy vấn dữ liệu PostHog, được tô màu theo từng phần — Description của skill truy vấn dữ liệu PostHog trong video (đăng ngày 29/10/2026), tô ba màu: câu đầu "Required reading before writing any HogQL/SQL or calling execute-sql against PostHog", đoạn giữa nói khi nào dùng (tìm, lọc, tổng hợp insights, dashboards, cohorts, feature flags…; query trends, funnels, retention, logs, sessions, LLM traces), đoạn cuối được gắn nhãn "what it does": HogQL khác ClickHouse SQL ở đâu, schema bảng hệ thống, hàm có sẵn, ví dụ query và workflow khám phá schema.

Theo Dennis (video đăng ngày 29/10/2026), cần nhớ rằng description là phần duy nhất agent có trong context, nên nó phải biết skill này là gì ngay lúc chọn skill. Còn khi agent mở skill ra thì thật ra bên trong không có nhiều thứ: chỉ là một workflow ngắn, link ra 26 file schema, 22 mẫu query ví dụ và một bảng chỉ mục hàm (function index). Anh lưu ý điều nhóm anh đang làm ở đây: thay vì đặt mọi thứ vào skill, nhóm link ra các tài nguyên chứa nhiều thông tin hơn.

4. Chỉ mở đúng file mà câu hỏi cần

Vì sao không đặt hết vào một skill? Theo Dennis (video đăng ngày 29/10/2026), lý do là phần lớn câu hỏi chỉ đụng tới một phần nhỏ của nó. Nếu tất cả nằm trong một file, mọi câu hỏi sẽ nạp vào mọi schema, mọi ví dụ, tức là nạp nhiều hơn agent thật sự cần. Thay vào đó, agent tự tìm ra câu hỏi cần những gì và chỉ mở đúng những file đó.

SKILL.md querying-posthog-data nối tới sáu file tham chiếu, ví dụ và script — `SKILL.md` tên `querying-posthog-data`, description "Use before writing HogQL or calling execute-sql", chỉ liệt kê ba mục Data schema, Query examples, Scripts, mỗi mục trỏ ra file riêng như `references/models-cohorts.md`, `examples/trends-unique-users.md`, `scripts/run-query.py`.

Đó là ý anh khi nói skill là một router: skill không chứa mọi thứ, nó chỉ biết mọi thứ nằm ở đâu và đưa agent tới đó. Dennis ví nó như một mục lục: bạn không cần đọc cả cuốn sách chỉ để tìm một chương. Lời khuyên của anh (video đăng ngày 29/10/2026): giữ skill ngắn và để nó trỏ tới mọi thứ khác.

5. Bài học 2: skill không phải là code

Nhưng theo Dennis (video đăng ngày 29/10/2026), dù một skill được viết ngắn gọn, nó vẫn phải được viết đúng cách. Từ đó tới bài học thứ hai: skill không phải là code. Anh đưa ra một skill viết như một chuỗi chỉ thị:

SKILL.md reviewing-risky-changes viết thành bốn bước cứng — Ví dụ skill viết kiểu code trong video (đăng ngày 29/10/2026): tên `reviewing-risky-changes`, bốn bước cứng với tên file và số dòng cụ thể.

Nội dung file trên màn hình:

---
name: reviewing-risky-changes
description: Use when reviewing recent commits for changes
  that might break something.
---

# Reviewing risky changes

1. Run git log --oneline -20.
2. If you see a commit with "fix" in it, check the diff.
3. If the diff touches auth.py, read lines 40–120.
4. If the function is over 50 lines, flag it.

Dennis đọc lại: chạy git log; nếu thấy commit có chữ "fix" thì xem diff; nếu diff đụng tới auth.py thì đọc từ dòng 40 tới 120; nếu hàm dài quá 50 dòng thì đánh dấu. Theo anh (video đăng ngày 29/10/2026), skill này trông rất chính xác, nhưng nó gãy ngay khi repo không khớp với những gì nó chờ đợi. Chẳng hạn bạn đổi tên file, thêm code, hoặc chỉ thêm luật cần theo. Skill vẫn đi tìm auth.py, và cụ thể là dòng 40 tới 120. Nếu không khớp, nó có thể bỏ sót mọi thứ nằm ngoài giới hạn đó.

Điều buồn cười, theo Dennis, là lập trình viên đã viết luật cứng từ rất lâu, nên đó là một thói quen ăn sâu. Nhưng agent khác đi nhiều, và anh cho rằng chúng ta sẽ phải điều chỉnh theo chúng (video đăng ngày 29/10/2026). Sau đó anh đưa ra cùng skill đó, nhưng viết cho agent; theo lời anh, bản này ghi:

Find recent changes that look risky and explain why. Start with the commit history.

Theo Dennis (video đăng ngày 29/10/2026), agent cực kỳ có năng lực nếu ta để chúng làm. Nếu cố liệt kê từng bước một, ta chỉ đang nhốt chúng vào một cái hộp, và lấy mất đúng phần làm cho agent thông minh.

6. Hackathon skill sửa video: càng thêm luật càng tệ

Dennis kể một chuyện ở một buổi hackathon trong offsite của PostHog (video đăng ngày 29/10/2026): team của anh làm một skill để sửa video. Ban đầu nó chạy tốt, nhưng rồi anh và team bắt đầu thêm luật, cố cải thiện skill, bắt nó làm thế này thế kia. Và cả team nhận ra skill càng tệ đi khi càng thêm vào.

Giải pháp, theo anh, thật ra là đập nó xuống: thu gọn skill, làm cho chỉ dẫn bớt dài dòng và mơ hồ hơn, để agent có nhiều khoảng trống hơn. Điều buồn cười là điểm cân bằng nằm ở chỗ nói rõ mục tiêu cuối cùng, đảm bảo biết "xong" trông như thế nào, nhưng không chỉ định quá chi tiết (theo Dennis, video đăng ngày 29/10/2026).

Hình 6.1Bài học từ buổi hackathon Dennis kể (video đăng ngày 29/10/2026): skill sửa video tệ đi khi thêm luật; cách sửa là thu gọn, nói rõ mục tiêu và tiêu chí xong, không chỉ định quá chi tiết.

7. Bài học 3: skill mục ruỗng theo thời gian

Theo Dennis (video đăng ngày 29/10/2026), ngay cả khi làm đúng hết những điều trên, skill cũng không đúng mãi. Bài học thứ ba: skill mục ruỗng (rot) theo thời gian. Hãy hình dung một skill trỏ tới vài file hoặc vài endpoint. Từ lúc bạn viết skill đó, sản phẩm đã thay đổi: có thể một endpoint giờ làm việc khác, có endpoint khác, hoặc file bị dời chỗ một chút. Skill không biết gì về chuyện đó, nó cứ gọi tiếp các endpoint cũ, và agent có thể không báo cho bạn biết rằng có gì đó sai.

Theo anh (video đăng ngày 29/10/2026), nhiều người sẽ cố viết một bản vá cho skill: thêm ghi chú, cố sửa hành vi của nó. Một skill lúc đó giống một codebase cũ: bạn không muốn đổi cách nó hoạt động vì nó tạm chạy được, nên cứ đắp thêm vào. Chẳng bao lâu, sau vài vòng, bạn có một skill phình to và lỗi thời, các luật mâu thuẫn nhau, và bạn thậm chí không muốn nhìn vào nó. Đó chính là lúc skill bắt đầu mục ruỗng.

Cách sửa Dennis đưa ra (video đăng ngày 29/10/2026): tách phần hay thay đổi khỏi phần không đổi. Những thứ ổn định, như mục tiêu và cách tiếp cận một việc cụ thể, thì đưa vào skill. Còn những thứ hay thay đổi thì trỏ tới nguồn sự thật (source of truth), như docs hay API endpoint, thay vì chép chúng vào skill.

Theo Dennis (video đăng ngày 29/10/2026), khi một skill lỗi thời, đội anh không vá nó mà sinh lại nó, vì nó đang trỏ tới nguồn sự thật. Agent có thể quay lại, xem docs mới nhất tại thời điểm đó và viết lại skill từ đầu. Như vậy nó nhận được bất cứ thứ gì đã thay đổi, thay vì chồng bản vá này lên bản vá khác.

8. Context mill: 120 integration skill không ai phải vá tay

Theo Dennis (video đăng ngày 29/10/2026), team wizard and docs của PostHog đẩy cách làm này đi khá xa. Thay vì bảo trì bằng tay 120 integration skill, team này giữ mỗi skill trong một thư mục nhỏ, phần lớn chỉ trỏ tới docs của PostHog. Sau đó một bước build mà họ gọi là context mill kéo docs mới nhất về, đóng gói skill và publish lên MCP server và install wizard của PostHog. Khi docs thay đổi, lần build kế tiếp cập nhật skill, và không ai phải vá bằng tay.

File cấu hình feature flag skills, chỉ chứa link tới docs PostHog — Cấu hình một nhóm skill trong video (đăng ngày 29/10/2026): "Feature flag skills, docs-only", gồm `shared_docs` và các biến thể React, Next.js, mỗi biến thể chỉ liệt kê `docs_urls` trỏ tới trang docs PostHog.

Repo context mill công khai của PostHog mô tả nó gom nội dung mới từ docs, prompt và code ví dụ thành các skill có version, rồi wizard tải skill từ bản release mới nhất, còn MCP server phơi chúng ra cho client MCP dưới dạng resource (đọc ngày 30/10/2026).

9. Bài học 4: hỏi agent trước

Theo Dennis (video đăng ngày 29/10/2026), một điều làm tất cả những việc trên dễ hơn là không phải tự tay viết skill. Bài học thứ tư: hỏi agent trước. Anh cho rằng agent khá giống con người ở chỗ chúng làm tốt nhất khi bạn hiểu chúng thật sự cần gì. Khi tự viết skill, ta đưa vào rất nhiều giả định về cách mọi thứ hoạt động, về những luật muốn cài vào. Và ta là người, nên luôn có khả năng mắc lỗi hoặc đơn giản là quên một thứ gì đó.

Vậy ai giỏi viết skill hay luật cho agent? Theo Dennis (video đăng ngày 29/10/2026), chính là agent: chúng rất giỏi việc này, chúng nhớ mình có quyền dùng tool nào, lần trước bị kẹt ở đâu, và biết mình thích nhận chỉ dẫn theo kiểu nào. Khi bạn tự viết một skill, agent sẽ cố hết sức làm theo, nhưng luôn có khả năng skill đó không hoàn hảo.

Dennis kể đây là thói quen anh có trong công việc hằng ngày, ngoài chuyện viết skill (video đăng ngày 29/10/2026). Khi build một project nào đó, giả sử anh đã biết tech stack và cách tiếp cận, thay vì nói hết những điều đó cho agent, anh nói mục tiêu cuối cùng, thứ anh đang muốn build, và để agent giải thích nó muốn đi theo hướng nào.

Cửa sổ Claude Code với prompt về app sửa video, bên cạnh Dennis Ivy — Ví dụ trên màn hình (video đăng ngày 29/10/2026): trong Claude Code, project `~/video-editor`, prompt đang gõ dở "I'm building a video editing app. It needs to trim clips, add captions, and export fast. Let's brainstorm the best stack toget…": nêu mục tiêu rồi mời agent cùng bàn stack.

10. Để agent tự nói nó cần gì khi viết skill

Theo Dennis (video đăng ngày 29/10/2026), anh nhận được hai thứ từ cách làm này. Thứ nhất, anh kiểm chứng được cách tiếp cận của chính mình có ổn không: nếu agent đồng ý, điều đó thường khá hữu ích. Nhưng phần hay hơn là nhiều khi agent nêu ra một điều anh chưa để ý, có thể là một phần khác của stack, hoặc một cách làm khác mà anh thấy đáng thử. Anh sẽ không có được điều đó nếu chỉ ra lệnh cho agent phải làm gì.

Khi hỏi, anh vừa kiểm chứng được suy nghĩ của agent, vừa có thêm ý tưởng mới, và theo anh điều đó đúng cả với skill. Cách anh gợi ý (video đăng ngày 29/10/2026): khi cần một skill, hãy giải thích cho agent bạn đang muốn làm gì, hỏi nó cần gì từ bạn và nên viết skill này thế nào; nó sẽ nói cho bạn tất cả. Nếu skill chạy không tốt và có vấn đề, hãy nói cho agent biết cái gì đang sai, cách bạn có thể đổi hướng tiếp cận, và có thể yêu cầu nó phân tích sâu chính skill đó. Theo Dennis, agent sẽ tự tìm ra chỗ cần sửa.

Hình 10.1Cách Dennis gợi ý để agent tham gia viết skill (video đăng ngày 29/10/2026): nói mục tiêu, hỏi agent cần gì, rồi báo lại khi skill có vấn đề để nó phân tích.

11. Bài học 5: không phải việc gì cũng đáng có một skill

Nhưng đôi khi, theo Dennis (video đăng ngày 29/10/2026), câu trả lời thành thật là bạn không cần skill nào cả. Anh thừa nhận đây có lẽ là lỗi chính anh hay mắc. Bài học thứ năm: không phải việc gì cũng đáng có một skill. Mỗi skill chiếm chỗ trong context của agent, và phải có ai đó quản lý từng skill một. Vì vậy, theo anh, PostHog dùng một phép thử đơn giản: chỉ viết skill khi công việc chạm một trong bốn điều kiện.

Bảng Only write a skill when với hai mục đầu, bên cạnh Dennis Ivy — Bảng "Only write a skill when…" trong video (đăng ngày 29/10/2026), đang hiện hai mục đầu: "You do it over and over" và "Agents are bad at it by default".

Bạn làm đi làm lại việc đó. Bạn đã làm ít nhất ba lần và nhiều khả năng sẽ còn làm thêm ba lần nữa (phép thử của PostHog theo video đăng ngày 29/10/2026).
Agent làm kém việc đó theo mặc định. Thường là cách làm riêng của bạn. Với PostHog, theo Dennis (video đăng ngày 29/10/2026), agent viết query SQL giỏi, nhưng dữ liệu của PostHog dùng phiên bản SQL riêng mang hơi hướng ClickHouse, và đó là chỗ agent hay vấp. Một cách dễ để kiểm tra có cần skill không là bảo agent làm thử: nếu nó làm ổn, có thể bạn không cần skill.
Agent cần context mà model không có sẵn. Ví dụ, theo Dennis (video đăng ngày 29/10/2026), nhiều dữ liệu trong PostHog như AI observability hay log có payload lồng nhau hoặc không hiển nhiên. Một skill đảm bảo agent không phải khám phá lại hình dạng dữ liệu đó mỗi lần bắt đầu một cuộc hội thoại.
Việc có thể chạy tự động (autopilot). Như trông chừng pull request hay truy lùng test chập chờn (flaky test): bạn đưa cho nó một mục tiêu, một cách để tự kiểm tra kết quả, rồi cứ để nó chạy (ví dụ của Dennis, video đăng ngày 29/10/2026).

Event $ai_generation dạng JSON với các trường lồng nhau được tô xanh — Ví dụ payload lồng nhau trong video (đăng ngày 29/10/2026): event `$ai_generation` có `$ai_input` và `$ai_output_choices`, mỗi phần là mảng message với `content` chứa từng mục `text` hoặc `image`, như câu hỏi "What's in this image?" và câu trả lời "I can see a hedgehog in the image."

Theo Dennis (video đăng ngày 29/10/2026), nếu việc không qua được phép thử này thì đừng viết skill.

12. Tìm ý tưởng skill, audit định kỳ và điều rút ra

Nếu đang tìm ý tưởng, Dennis gợi ý (video đăng ngày 29/10/2026) bạn có thể bảo agent xem lại công việc 30 ngày qua của bạn và tìm xem có việc nào bạn cứ lặp lại mà có thể làm thành skill. Theo anh, agent khá giỏi tìm ra những thứ như vậy, và đó có thể là skill tiếp theo của bạn.

Cửa sổ Claude Code với prompt Review my last 30 days of work — Prompt trên màn hình (video đăng ngày 29/10/2026), trong Claude Code ở project `~/posthog`: "Review my last 30 days of work."

Review my last 30 days of work.

Nhưng thường thì, theo Dennis (video đăng ngày 29/10/2026), anh nghĩ mọi người đang viết quá nhiều skill. Anh thừa nhận chính mình đã phá luật này: đang làm một việc, agent đề xuất một skill, anh tự động duyệt luôn kiểu "ừ, sao không", rồi phát hiện mình có hai skill làm những việc khá giống nhau và bắt đầu đá nhau.

Cách anh chống lại chuyện đó (video đăng ngày 29/10/2026): khoảng vài tuần một lần anh chạy một đợt audit skill, bảo agent cho anh biết anh đang có những skill nào, anh thật sự dùng chúng vào việc gì, có dùng thường xuyên không, và xem có skill nào xung đột nhau không. Anh nói anh luôn đảm bảo xoá nhiều skill hơn là mình thật sự cần, vì skill tích tụ lại rất nhanh.

Điều rút ra từ tất cả những điều trên, theo Dennis (video đăng ngày 29/10/2026): skill tốt nhất thường là những skill nhỏ nhất, những skill trỏ agent tới đúng tài nguyên nó cần, và chừa chỗ cho agent tự suy nghĩ. Anh kết thúc video ở đó và nói hy vọng người xem thích nó.

Nguồn và liên kết 8 nguồn

Tên gốc: What nobody tells you about writing agent skills
Sự kiện: YouTube
Video gốc: https://www.youtube.com/watch?v=BzfTzPls9S0 youtube.com
Kênh YouTube PostHog (Dennis Ivy): youtube.com/channel/UCn4mJ4kK5KVSvozJre645LA youtube.com
Tài liệu skill của Claude Code, bảng "When loaded into context": description luôn trong context, toàn bộ skill nạp khi được gọi (đọc ngày 30/10/2026): code.claude.com/docs/en/skills code.claude.com
Repo context mill của PostHog, mô tả cách gom docs thành skill cho wizard và MCP server (đọc ngày 30/10/2026): github.com/PostHog/context-mill github.com
Docs PostHog về event, trang mà skill weekly-signups viết lại trỏ tới (đọc ngày 30/10/2026): posthog.com/docs/data/events posthog.com
Docs PostHog về query API, trang thứ hai skill đó trỏ tới (đọc ngày 30/10/2026): posthog.com/docs/api/query posthog.com