| name | memory-placement |
| description | Use when user says "remember this", when deciding where to store learnings or documentation, when about to edit CLAUDE.md, or when creating new plugin content (skills, commands, agents). Routes info to CLAUDE.md, skills, commands, or logs. |
Memory Placement Guide
Quick reference for deciding where information should be stored across Claude sessions.
Progressive Disclosure (Hop Cost)
Each additional "hop" (need to notice a skill, then open it, then open a referenced doc) adds time and increases the risk the instruction is missed.
Use hop cost intentionally:
- Put only universal guardrails in
CLAUDE.md (L0)
- Keep
agents/skills/*/SKILL.md as a small set of entrypoints (L1)
- Put deeper specifics in referenced notes (L2+) and promote them upward only when they prove high-risk or frequently missed
Semantic Recall (Search Prior Conversations)
If you're stuck, repeating a failure mode, or suspect "I've solved this before", search conversation history semantically before inventing a new approach:
agent-recall search "<query>"
This is cross-runtime and can pull from both Claude and Codex histories (depending on what's present locally).
Subagents, Tasks, and Context Management
Delegation can reduce time-to-correctness, but it can also create context fragmentation.
Metacognitive checks:
- Prefer a single thread when shared state is high (many coupled files, tricky invariants, complex verification).
- Delegate when work is separable (research, codebase mapping, isolated implementation) and you can verify the output independently.
- Before dispatching a subagent, write down the minimal handoff context (goal, constraints, current findings, relevant files, acceptance checks) so it doesn't guess.
- Use a persistent artifact (plan note / atom / task list) to avoid losing intermediate decisions across threads.
Core Decision: Where Should This Go?
Ask yourself: "Do I need this most of the time when assisting, or might I make a mistake without it?"
- YES → Put it in CLAUDE.md
- User-level:
~/.claude/CLAUDE.md (all projects)
- Project-level:
./CLAUDE.md (this project)
- NO → Create a skill or command in a plugin
Where This Repo Stores Skills / Knowledge
- Entrypoint skills (cross-runtime):
~/.dotfiles/agents/skills/ (canonical)
- Compatibility:
~/.dotfiles/claude/skills/ is a symlink to ~/.dotfiles/agents/skills/
- Deeper notes (atoms):
~/.dotfiles/agents/knowledge/atoms/
- User profile (operational defaults):
~/.dotfiles/agents/knowledge/atoms/michael-user-info.md
- Repo-local skills (per-repo):
- Codex CLI:
./skills/<skill-name>/SKILL.md auto-loads (verified in ~/ws/notes on 2026-02-08).
- Claude Code:
./.claude/skills/<skill-name>/SKILL.md is a repo-local skills directory (verified in ~/ws/notes on 2026-02-08 via claude -p --setting-sources project).
- Claude Code (global):
~/.claude/skills/ also exists on this machine (symlinked to dotfiles).
- If you want one source of truth for both tools, keep the canonical skill under
./skills/ and keep ./.claude/skills/ in sync (or symlink when your environment allows).
Claude Plugin Architecture (Separate System)
Persistent memory beyond CLAUDE.md lives in plugins at ~/.dotfiles/claude-plugins/. Each plugin contains: skills/, commands/, agents/, scripts/
| Plugin | Purpose |
|---|
productivity | PPV Notion, GTD, coaching, Todoist |
dev | Git, PR workflow, testing, ports, Linear |
media | TTS, image generation, notifications |
memory | Docs, notes, mistakes, configs |
terminal | Tmux, image viewing, themes, sounds |
claude-meta | Session management, prototyping |
misc | Hammerspoon, Sphere, specialized tools |
Placement Decision Tree
Is this info needed MOST OF THE TIME?
├── YES → CLAUDE.md (universal rules, guardrails)
└── NO → Does it auto-load based on context?
├── YES → Skill (plugin/skills/name/SKILL.md)
└── NO → Is it user-invoked action?
├── YES → Command (plugin/commands/name.md)
└── NO → Is it repo-specific?
├── YES → Project commands (<repo>/.claude/commands/)
└── NO → Is it third-party API?
├── YES → Fetch via Context7 (don't store)
└── NO → Log file (historical reference)
Summary by Type
| Type | Location | When to Use |
|---|
| Universal rules | CLAUDE.md | Always needed, guardrails |
| Auto-loaded guidance | Plugin skills | Procedural, triggered by context |
| User actions | Plugin commands | Explicit /command invocation |
| Repo patterns | Project .claude/commands/ | Project-specific workflows |
| API docs | Context7 | External libraries (fetch on demand) |
| Historical | Log files | Learnings, mistakes |
Skill vs Command
Skills (auto-loaded):
- Loaded when Claude matches the description
- Good for: Safety protocols, best practices, domain knowledge
- Locations:
- Entrypoints:
~/.dotfiles/agents/skills/<name>/SKILL.md
- Claude plugin skills:
~/.dotfiles/claude-plugins/<plugin>/skills/<name>/SKILL.md
Commands (user-invoked):
- User types
/plugin:command or /command
- Good for: Actions, workflows, routines
- Location:
~/.dotfiles/claude-plugins/<plugin>/commands/<name>.md
Writing Good Descriptions
Skills: "Use when [specific triggering condition]"
"Use when about to run git stash""Use when killing processes on ports"
Commands: "[Action] when [user intent]"
"Todoist task management. Use when user asks to work with Todoist""Morning routine. Use when user starts their day"
Test: Would Claude naturally think to load this in that situation?
Creating New Plugin Content
mkdir -p ~/.dotfiles/claude-plugins/<plugin>/skills/<name>
Before Editing CLAUDE.md
Checklist:
Escalation Ladder for Mistakes
- First occurrence → Improve or create the relevant skill
- First recurrence → Strengthen skill and add anti-miss cues
- Second recurrence in same repo (14 days) → Add one-line Hot Rule to repo's CLAUDE.md
- Cross-repo recurrence (2+ repos in 14 days) → Add one-line guardrail to root CLAUDE.md
- Cooldown after 14-30 quiet days → Propose removing one-liners; skill remains canonical
Note: For human-readable project documentation (guides, implementation notes), see the doc-placement skill.
Acceptance Checks
