Context, Skills & Memory

Agents are only as good as what they know when they start, and by default they start knowing nothing about your repo, your conventions, or last week's decisions. Context engineering, deciding what an agent sees, when, and in what form, is now a core skill, and a small set of conventions has standardized around it. The term's christening is usually credited to Andrej Karpathy (amplified by Shopify's Tobi Lütke), who called it the "delicate art and science of filling the context window with just the right information for the next step." LangChain's survey of the field organizes everything under four moves, write context down (scratchpads, memories), select what comes in (retrieval, rules files), compress what stays (summarization, trimming), and isolate what doesn't belong together (sub-agents, sandboxes). Every convention below is an instance of one of them.

When context hurts: the four failure modes

The naive model, that more context is strictly better, is wrong, and knowing how it's wrong separates context engineering from context hoarding. Anthropic's "Effective context engineering for AI agents" grounds the intuition. LLMs have a finite "attention budget," and benchmark work documents context rot, where "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases." Drew Breunig's "How Long Contexts Fail" gives the failure modes names worth memorizing, context poisoning (a hallucination enters the context and gets repeatedly referenced), context distraction (the model over-focuses on a long context, neglecting what it learned in training), context confusion (superfluous tools and information steer it wrong), and context clash (accumulated context contradicts itself). His companion piece, "How to Fix Your Context", maps the mitigations, which amount to prune, quarantine, offload, and trim the tool loadout. Every convention in the rest of this chapter is one of those mitigations wearing a friendlier name.

AGENTS.md and CLAUDE.md: conventions in the repo

The dominant pattern is a plaintext/markdown file at the repo root that agents read on startup. AGENTS.md (agents.md, pitched as "a README for agents," now used by over 60,000 open-source projects and supported by Codex, Cursor, VS Code, GitHub Copilot, Devin, Windsurf, Zed, Aider, and most other tools) and CLAUDE.md (Claude Code's flavor of the same idea) are the two you'll meet. The file holds the things you'd otherwise re-explain every session, such as how to run the build and tests, module boundaries, code-style rules, and, crucially, the "why we don't" decisions that keep an agent from cheerfully reintroducing a pattern you deliberately removed. In the orchestra model, AGENTS.md is explicitly the vessel for compound learning. Every session's hard-won lesson gets written back so the next session (and every parallel agent) starts smarter. This is the ratchet principle applied to knowledge.

Skills / SKILL.md: reusable, disclosed on demand

A Skill (packaged as a SKILL.md plus any supporting files) is reusable project knowledge or procedure the agent can pull in when relevant rather than carrying in every prompt. Skills appear in the loop-engineering component list precisely so you stop re-explaining the same context on every run. The design virtue is progressive disclosure. Instead of stuffing the whole system prompt with everything the agent might need, you let it load the deploy runbook or the API-migration playbook only when the task calls for it, keeping context lean and reducing the "context rot" that degrades long sessions. A mature team accumulates a small library of skills the way it once accumulated shell scripts and internal wikis. Simon Willison's assessment, "Claude Skills are awesome, maybe a bigger deal than MCP", rests precisely on the token economics. Until invoked, "each skill only takes up a few dozen extra tokens," where an MCP server front-loads thousands of tokens of tool definitions into every session. The low-tech format of markdown plus a little YAML is the feature. Skills are portable across tools and models in a way heavier integrations are not.

External state and memory: surviving the reset

The defining constraint of today's agents is that context is finite and vanishes between sessions. The answer, consistent across the long-running-agents and factory literature, is to keep durable state outside the model, in progress files, task lists, decision logs, and session-as-event-log records on disk or a tracker (Linear, a markdown board). Anthropic's "engineers working in shifts with no memory of the previous shift" is the failure this prevents. The fix is that each shift writes down what it did and reads what came before. This is also why checkpoint-and-resume matters. An agent that saves intermediate state can recover from a crash or a context reset instead of losing hours of work.

The most concrete production playbook is the Manus team's "Context Engineering for AI Agents: Lessons from Building Manus". Treat "the file system as the ultimate context: unlimited in size, persistent by nature, and directly operable by the agent itself." Have the agent recite its objectives (Manus keeps rewriting a todo.md) to fight goal drift. And, counterintuitively, "leave the wrong turns in the context," because a model shown its own failed attempt is less likely to repeat it. Their most surprising lesson is economic, that "the KV-cache hit rate is the single most important metric for a production-stage AI agent," which argues for append-only context and stable prompt prefixes. Context design shows up on the invoice, not just in output quality. Anthropic's long-horizon toolkit adds compaction (summarize a session nearing its limit into a fresh window) and structured note-taking as the shift-handoff document each session writes for the next.

Intent debt: the context you can't regenerate

There is one kind of context an agent cannot supply for you, and it deserves its own name. Osmani's "The Intent Debt" defines it as the missing externalized rationale behind a system's design, meaning the goals and constraints that explain why the code is the way it is. It is distinct from technical debt (in the code) and comprehension debt (in people's heads). Intent debt lives in the artifacts that should exist and don't. The pivotal line is worth quoting in full. "An agent can't generate intent, because intent is the one input that has to come from you." Agents can refactor and explain existing code endlessly, but they cannot recover a rationale that was never written down, and a cold-starting agent has none of the hallway-conversation context a long-tenured engineer carried. Multiply that across many sessions and undocumented decisions get re-litigated (or silently violated) again and again. The mitigation is deliberate. Write goal-focused specs that state constraints and non-negotiables, keep decision logs as "pure intent-debt paydown," and leave AGENTS.md "why we don't" notes. Osmani's summary is the practical takeaway for this whole chapter. "Write down the why, because it's becoming the most valuable thing you can leave in the repo."