Anthropic's skills playbook vs our custom knowledge layer

Thariq Shihipar from Anthropic's Claude Code team recently published a thread on how they use skills internally. Hundreds of them in active use, clustering into nine categories once cataloged, from library references to runbooks to CI/CD automation. I read the thread right after publishing a post about building a knowledge layer on top of CLAUDE.md to capture repo-scoped domain context. The thread answered a question I'd been sitting with: where does deep domain knowledge go when Anthropic themselves recommend keeping CLAUDE.md under 200 lines?

Turns out their team use skills for that.

Same architecture, different packaging

If we look at their nine categories, at least three are primarily knowledge containers. The action wrapper (a slash command, a trigger description) makes them discoverable. But the core content is context, not automation.

Their "Build a Gotchas Section" tip makes it explicit: the highest-signal content in any skill is the gotchas section. Add a line each time Claude trips on something. Day 1, the billing-lib skill says "How to use the internal billing library." Month 3, it has four gotchas covering proration rounding, test-mode webhook gaps, idempotency key expiration, refund ID semantics. Knowledge accumulating over time. Exactly what our .claude/knowledge/ files do.

Their queue-debugging skill uses a hub and spoke structure: a 30-line SKILL.md with a symptom-to-file routing table, and spoke files (stuck-jobs.md, dead-letters.md, retry-storms.md) for the detail. This is structurally identical to our CLAUDE.md knowledge table pointing to .claude/knowledge/*.md files. Same progressive disclosure. Same "keep the hub lean, push detail to the spokes" principle.

One primitive or two

Tbh, if this thread had existed two months ago, we might not have built a separate knowledge layer at all. Their approach handles the same problem. One extension point, one concept to learn. Simpler.

What we ended up building adds one seam: knowledge files hold domain context (what Claude should know), skills hold executable actions (what Claude should do). We do use skills with scripts and hooks. The separation just means the context lives in its own files.

For e.g., we have a knowledge file documenting a data pipeline: 7 jobs in sequence, ontology structure, S3 path conventions, Elasticsearch gotchas. That file is read by four different generic skills for running jobs, querying the database, querying ES, and accessing S3. The knowledge changes depending on which pipeline you're working on. The skills don't. In a skill-only setup, you'd either duplicate that context across skills or wrap it in a dedicated pipeline-knowledge skill, which gets you to roughly the same place.

Another example: a skill that runs our evaluation suite. 44 lines: dataset names, CLI commands, timeouts. Clean and procedural. But interpreting results requires a separate knowledge file explaining what each dataset tests, known weak spots, and the outcome of recent eval sessions, etc. When someone reads that knowledge file months later, they skip repeating the same investigation. They don't need to invoke the eval skill to get there.

Where we land

Going back to their nine categories. Library & API Reference is edge cases and code snippets for internal libraries. Incident Runbooks map symptoms to investigation steps. Both are knowledge containers wearing a skill wrapper. On the other end, CI/CD & Deployment and Scaffolding & Templates are pure automation. Data & Analysis and Code Quality & Review sit somewhere in between: reference data plus scripts, style rules plus enforcement. No one designed that split. It just showed up in the taxonomy. The knowledge/action boundary seems to surface whether you formalize it or not.

One last thought. Skills didn't exist a year ago. Claude Code launched with commands, then skills arrived, the two overlapped for a couple of months, and eventually commands folded into skills. The core abstraction for extending Claude Code changed twice in twelve months.

That's the environment we're all building in. The extra seam we added (knowledge separate from skills) is a bet on adaptability. When the next abstraction shift comes, the knowledge stays put. The wiring around it can change.