LLM Skills vs Docs vs Memory

Three ways to give an AI coding agent (e.g. Claude Code) persistent knowledge. They are not interchangeable — each answers a different question.

One-line mental model: doc = what I know · skill = what I do · memory = what I remember about you.

The three at a glance

Doc — passive reference

A Markdown file in the codebase. It just sits there, entering the agent’s context only when someone explicitly reads it (or a top-level index points to it and the agent opens it).

• Mood: descriptive. “Here is how this works, and why — the trade-offs, the gotchas.”
• Strength: deep, version-controlled, the single source of truth for the why.
• Weakness: no trigger. Nothing decides “now is the moment”; it relies on the agent remembering to open the right file.

Skill — an actively-dispatched procedure

A folder (SKILL.md + optionally scripts, templates, examples) with a name and a description in its frontmatter.

• Mood: imperative. “When the user wants X, do these steps, then validate.” A runbook.
• Two ways it fires: the user types /skill-name, or the agent auto-invokes it because the request matches the description (which acts as a routing rule).
• Progressive disclosure (the key win): only the one-line description is always in context; the full body loads only when invoked. So a skill can be long and detailed at zero standing context cost — unlike stuffing the same procedure into an always-loaded index.
• Portable & self-contained: a movable, shareable package.
• Reliable: the explicit trigger makes the right procedure get followed reproducibly.

Memory — private, about you

Notes the agent keeps outside the repo about the person and the collaboration: role, preferences, feedback, and status that maps onto no code. Not version-controlled, not shared. Danger: if project knowledge leaks in here it becomes shadow documentation nobody else sees — when a memory note grows into a recipe, that’s the signal it belongs in a doc.

Why not make everything a skill?

Every skill’s description occupies a little permanent context and enlarges the routing decision space. Too many skills → noise, worse matching, wrong-skill risk. So create a skill only after real, recurring, procedural friction (“done it 3×”), not preemptively. One-off knowledge or pure explanation → a doc.

The decision rule

• Repeatable action (recipe, ordered steps, “do it right every time”) → skill.
• Reference knowledge (how & why, trade-offs, gotchas) → doc.
• About you / the collaboration, or status → memory.

Best practice: compose, don’t duplicate — a thin skill (the how / when) with a pointer to a doc (the why, the source of truth). The skill orchestrates; the doc explains; edit the doc once and the skill still points at the current truth.