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
| Where it lives | Shared / in repo? | Nature | When it loads into context | |
|---|---|---|---|---|
| memory | outside the repo, private to the agent | no | about you / the working relationship + status | an always-on index; details on recall |
| doc | in the repo (doc/…) | yes | reference — how & why something works | on-demand (the agent opens the file) |
| skill | in the repo (.claude/skills/<name>/) | yes | procedure — do X, these steps | trigger always-on; body on-demand; /-invocable |
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 thedescription(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.