How the Claude Code team builds and ships internal skills

Thariq Shihipar from Anthropic's Claude Code team wrote up how the team manages hundreds of internal skills, the folder-based extensions that give Claude task-specific knowledge. The post is a practitioner guide more than a product pitch, and it lands on a few lessons that go against how most teams structure their first skills.

The strongest point is that the gotchas section is the highest-signal content in any skill. The team builds it by watching Claude fail on real edge cases and adding only those, instead of writing exhaustive documentation up front. A second lesson is that skills should be narrow and category-pure. The team identifies nine types, including library references, data fetching, runbooks, and CI/CD, and warns against mixing them in one skill. Progressive disclosure matters too: a SKILL.md file should be a short pointer, with details split into separate files that Claude reads only when needed. The team uses the ${CLAUDE_PLUGIN_DATA} environment variable to give skills persistent state across runs, so a standup skill can remember what it posted yesterday.

The description field, Shihipar notes, is not for humans. It is the text the model uses to decide whether to load the skill at all, so it should be written for that decision. At scale, the team finds an internal plugin marketplace works better than scattered repo-based distribution.

Why it matters

If you are building skills or considering them, the temptation is to front-load detail and cover every case. This post is a clear argument for the opposite: ship narrow, light skills, then let real failures drive the gotchas. That changes how you budget time in week one.