Anthropic's skills playbook vs our custom knowledge layer

Source: Dev.to

Overview

Thariq Shihipar from Anthropic’s Claude Code team recently published a thread on how they use skills internally. Hundreds of them are 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 uses skills for that.

Sol LeWitt, The Location of Lines, 1975

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, and refund‑ID semantics.

Knowledge accumulates 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 mirrors 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

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 with a single extension point and a single 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 still use skills with scripts and hooks; the separation just means the context lives in its own files.

Example 1: A knowledge file documents a data pipeline (7 jobs, ontology, S3 conventions, Elasticsearch gotchas). Four generic skills read that file to run jobs, query the DB, query ES, and access S3. The knowledge changes per pipeline; the skills stay the same. In a skill‑only setup you’d duplicate that context across skills or wrap it in a dedicated pipeline‑knowledge skill—roughly the same end state.

Example 2: A skill runs our evaluation suite (44 lines: dataset names, CLI commands, timeouts). Interpreting results requires a separate knowledge file explaining what each dataset tests, known weak spots, and recent outcomes. When someone reads that knowledge file months later, they skip repeating the same investigation and don’t need to invoke the eval skill.

Where we land

Re‑examining the nine categories:

No one designed that split; it simply emerged in the taxonomy. The knowledge/action boundary surfaces 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.

Author: Jun Suzuki
Published on Dev.to