# context-engineering

> A Claude Code skill from Addy Osmani's agent-skills repo that treats agent context as a layered hierarchy — rules files at the base, transient error output at the top — and refuses both context starvation (agent hallucinates) and context flooding (agent loses focus past ~5,000 lines).

**Use case**: Curate what the agent sees so output stops drifting from project conventions

**Canonical URL**: https://agentcookbooks.com/skills/context-engineering/

**Topics**: claude-code, skills, documentation, planning

**Trigger phrases**: "set up the context for this project", "agent isn't following our conventions", "configure CLAUDE.md"

**Source**: [Addy Osmani](https://github.com/addyosmani/agent-skills/tree/main/skills/context-engineering)

**License**: MIT

---

## What it does

`context-engineering` is the meta-skill in Addy Osmani's collection — about how to feed a coding agent the right information at the right time. It defines a five-level hierarchy ordered by persistence: rules files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`) at the base because they apply to every session, then spec/architecture docs loaded per feature, then relevant source files loaded per task, then error/test output loaded per iteration, and finally the conversation itself which accumulates and needs deliberate compaction.

The skill ships a concrete `CLAUDE.md` template covering tech stack, commands, conventions, boundaries, and one short example of well-written code in the project's style — the rule being "one real snippet beats three paragraphs of description." It also names two specific failure modes by their failure mode: **context starvation** (agent hallucinates APIs and ignores conventions) and **context flooding** (agent loses focus past ~5,000 lines of non-task-specific context). The remedy is selective inclusion, not bigger windows.

The third pillar is confusion management. When spec contradicts existing code, or when requirements are incomplete, the skill mandates that the agent surface the conflict with options labeled A/B/C — rather than silently picking an interpretation and building on it. The "inline planning pattern" — emit a 3-step plan before executing, "→ Executing unless you redirect" — is the cheap version of the same idea: a 30-second checkpoint that prevents 30-minute rework.

## When to use it

- Setting up a brand-new project and you want to author the right `CLAUDE.md` on day one rather than retrofit later
- Agent output is drifting (hallucinated APIs, wrong patterns, ignored conventions) and you need a structured way to fix the inputs before blaming the agent
- Starting work in an unfamiliar area of an existing codebase where you want a project-map context block rather than the full repo
- After a context-window compaction event where the agent lost track of conventions

When *not* to reach for it:

- One-shot questions ("explain this regex") where no project context applies
- Single-file scripts where there is no surrounding architecture to model
- Mature projects with a `CLAUDE.md` that already works — adding more context-engineering ceremony to a working setup is the skill's exact "context flooding" anti-pattern

## Install

From [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) at `skills/context-engineering/`. Standalone — its outputs are `CLAUDE.md` files and context-packing patterns rather than runtime tooling. Pairs naturally with `spec-driven-development` (the spec is the level-2 context), `browser-testing-with-devtools` (the DevTools MCP is one of the level-2 integrations the skill names), and any planning skill that produces the project map the skill expects to load.

## What a session looks like

1. **Audit existing context.** Does a `CLAUDE.md` (or equivalent rules file for whatever IDE/agent is in use) exist? If not, that's level 1 of the hierarchy missing — start there.
2. **Author the rules file.** Tech stack with versions, exact build/test/lint/dev commands, code conventions illustrated by one short example, three-tier boundaries (always do / ask first / never do).
3. **Pick a packing strategy per task.** Brain dump for project kickoff. Selective include for a known task ("modify this endpoint, follow this validation pattern, here are the relevant files"). Hierarchical summary for large projects with a project-map index.
4. **Wire MCP integrations as needed.** Context7 for library docs, Chrome DevTools for browser state, PostgreSQL for schema, GitHub for issue/PR context — only the ones the project actually needs.
5. **Manage confusion explicitly.** When spec and code disagree, or requirements are incomplete, the skill's pattern is to emit options A/B/C and stop, not guess. Same shape applies to planning: "PLAN: 1. ... 2. ... 3. ... → Executing unless you redirect."
6. **Refresh between major tasks.** Start fresh sessions when switching features. Summarize progress when context gets long. Compact deliberately before critical work.

The discipline that makes it work: the line between "context window is huge, I'll use it all" (the skill's "rationalization" column) and "performance degrades with too many instructions" (its "reality" column). Big window ≠ big attention budget.

## Receipts

_TODO — to be filled in from a real session. Once the skill has been used to author or refactor a `CLAUDE.md` on a project that previously had drift problems, this section will capture: which level of the hierarchy was actually missing (almost always level 1 in practice), whether the inline-planning pattern caught a wrong direction before code got built on it, and the wall-clock cost of the upfront context investment vs. the rework it prevented._

## Source and attribution

From [Addy Osmani's agent-skills repository](https://github.com/addyosmani/agent-skills/tree/main/skills/context-engineering), an MIT-licensed collection of production-grade engineering skills for AI coding agents.

License: MIT.

Quote from the skill body, verbatim: *"Context is the single biggest lever for agent output quality — too little and the agent hallucinates, too much and it loses focus."* The five-level hierarchy and the explicit "starvation vs. flooding" anti-pattern table are how the skill makes that lever operational instead of decorative.