PostHog’s 226 skills need a maintenance system

PostHog says its teams published 226 skills to an internal store, with 187 SKILL.md files across 28 products. Its lesson is not to preload every instruction: descriptions should route agents to the right context, while detailed references load only when needed. Why it matters: A skill that hard-codes paths and steps becomes stale as the product moves. But a vague skill only moves the guesswork into the agent run. The useful boundary is durable intent and guardrails, backed by live source material for the volatile details.

Try this: Pick one skill your team uses repeatedly. Remove one brittle path-level instruction, add a concrete completion check, and point the changing detail to its source of truth. Then run the same task again and compare where the agent hesitates or retries.