PostHog has 187 SKILL.md files. Here is what it learned
The company says its teams have published 226 agent skills internally. Its engineering newsletter sets out the rules that keep them useful, and the failure modes that don't.
Agents forget. Every new conversation they rediscover the codebase, pick the wrong tool and repeat old mistakes.
PostHog's answer is skills: instructions written once, in files an agent loads when it decides they are relevant. On the company's own account, its teams have published 226 skills to an internal skill store, and the codebase holds 187 SKILL.md files across 28 products.
The first rule in its write-up is progressive disclosure. Context is normally dumped in at the start, which caps how much an agent has to work with. A skill loads only when needed.
That makes the name and description the important part. PostHog writes them to say when to reach for the skill, not what it does, because those lines are the only part always in the agent's context.
Its SQL skill is the worked example. The name and first sentence say when to read it, the middle sentence says when to use it, the last says what it covers. The body is a thin workflow that links out to 26 schema files, 22 example query patterns and a function index.
More skills is not better. PostHog says it built too many for its AI product and watched effectiveness decline as the descriptions filled the context window. It cites Databricks finding that agents pick the wrong skill more often as the count grows.
The second rule is that skills are not code. An instruction that names a file and a line range breaks the moment the repo changes. An instruction to find recent risky changes and explain why survives, because the agent can look at what is in front of it.
So be precise about three things: the goal, including how the agent can verify it is done; the constraints; and context the agent cannot derive, such as where the data lives. Be vague about the steps, the failure modes and anything about runtime — line numbers, counts, versions, outputs.
The third rule is that skills rot. APIs, CLIs and models change. PostHog's fix is to separate durable structure from volatile content, point at a single source of truth such as a docs URL, and regenerate a skill from a stable base rather than patching it repeatedly.
It runs that as a pipeline — sourcing docs and example apps, packaging them into a versioned zip, shipping to its MCP and install wizard — to maintain what it says is 120-plus skills on integrating PostHog. The article says the three principles also work by hand, which is the relevant point for a team of five.
Fourth: ask the agent what it needs. It knows which tools it has and what broke on the last run. Guessing that is how you burn tokens.
Fifth: most work does not deserve a skill. Each one costs context and maintenance. PostHog's test is whether the agent already does the job efficiently — it does not need a skill to write SQL, but it might need one for PostHog's ClickHouse dialect.
For a small team, the cheapest version of all this is one afternoon: name your three most repeated agent conversations, write a file for each with the goal and constraints spelled out and the steps left open, and point every one at a URL rather than a copied paragraph.