Start a skill as a few lines plus one gotcha — grow a Gotchas section from real failures, don't over-spec upfront
Anthropic/Claude·medium signal
In 'Lessons from building Claude Code: How we use skills,' Anthropic says the highest-value skill content is a Gotchas section grown from real failures, e.g. 'the subscriptions table is append-only — take the row with the highest version, not the latest created_at.' Begin a skill as a few lines and one gotcha, then append edge cases each time the agent trips on them. This beats writing an exhaustive spec upfront, which over-specifies and 'railroads' the model out of adapting to novel situations.