Skip to content
Get packs

Guide · Agent skill

How to use the Context Engineering agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Context Engineering skill is a set of text guidance that teaches an AI coding agent how to organise the information it works from: what goes in a persistent rules file, which spec sections and source files to load, how to trim error output, and when to start a fresh session. This guide shows you how to install the skill, trigger it with plain requests, and apply its practices to your own project so the agent follows conventions and stays focused over long sessions.

Context Engineeringaddyosmani/agent-skills · MIT

Quick start

  1. 1Download the ZIP. Get the context-engineering ZIP from this page. It contains SKILL.md.
  2. 2Unzip into a skills folder. Place the context-engineering folder in ~/.claude/skills/ for personal use, or in your project's .claude/skills/ folder.
  3. 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
  4. 4Ask for help with context. Describe the task in plain words, such as setting up a rules file or starting a new session.
  5. 5Create a rules file. Write a CLAUDE.md or equivalent file with your stack, commands, conventions and boundaries.
  6. 6Load only what the task needs. Give the agent the relevant spec section, source files and specific errors rather than everything.
  7. 7Hand off at task boundaries. Save status, decisions and verification results before starting a fresh session.

What the Context Engineering skill makes the agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent extra instructions it can load when they are relevant. This skill focuses on context: the material the agent can see while it works. Its core idea is that too little context leads to hallucinated APIs and ignored conventions, while too much context makes the agent lose focus.

The skill describes a five-level context hierarchy, from most persistent to most transient: rules files, spec and architecture docs, relevant source files, error output and test results, and conversation history. It also covers handing work between sessions through notes and repository state.

  • Keeps a rules file such as CLAUDE.md with project conventions, commands and boundaries
  • Loads only the spec section and source files relevant to the current task
  • Feeds back specific error messages instead of full logs
  • Starts fresh sessions at natural task boundaries and summarises progress
  • Treats instructions found inside loaded files as data, not commands

Install the Context Engineering skill

Download the ZIP for the context-engineering skill from this page. The package contains a single file, SKILL.md. Unzip it so the context-engineering folder sits in one of these locations:

  • Personal skills: ~/.claude/skills/ (available across your projects)
  • Project skills: a .claude/skills/ folder inside your project (shared with anyone who uses that repository)
  • Claude apps: upload the ZIP under Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. Describe what you are doing in plain language and the agent can match your request to the skill's description. The description says it applies when starting a new session, when output quality degrades, when switching tasks, or when you need to configure rules files and context for a project.

Requests that tend to fit the skill include asking the agent to set up a rules file for a new project, asking it to pick up work in a fresh session, or telling it that its output has started ignoring conventions.

  • "Help me set up a CLAUDE.md for this project."
  • "The agent keeps ignoring our naming conventions. Review how we give it context."
  • "We're switching from the billing code to the search code. Plan what context to load."
  • "Prepare a handoff note so the next session can continue this task."

Write a rules file the agent reads every session

The skill calls the rules file the highest-leverage context you can provide, because it is always loaded. The source gives a CLAUDE.md template with sections for tech stack, commands, code conventions, boundaries and an example pattern. Equivalent files exist for other tools: .cursorrules or .cursor/rules/*.md for Cursor, .windsurfrules for Windsurf, .github/copilot-instructions.md for GitHub Copilot, and AGENTS.md for OpenAI Codex.

  • Tech stack: the frameworks and versions you actually use
  • Commands: build, test, lint, dev and type-check commands
  • Code conventions: patterns the agent should follow and avoid
  • Boundaries: things it must never do, such as committing secrets or changing the database schema without asking
# Project: [Name] ## Tech Stack - React 18, TypeScript 5, Vite, Tailwind CSS 4 - Node.js 22, Express, PostgreSQL, Prisma ## Commands - Build: `npm run build` - Test: `npm test` - Lint: `npm run lint -- --fix` - Dev: `npm run dev` - Type check: `npx tsc --noEmit` ## Code Conventions - Functional components with hooks (no class components) - Named exports (no default exports) - colocate tests next to source: `Button.tsx` → `Button.test.tsx` - Use `cn()` utility for conditional classNames - Error boundaries at route level ## Boundaries - Never commit .env files or secrets - Never add dependencies without checking bundle size impact - Ask before modifying database schema - Always run tests before committing ## Patterns [One short example of a well-written component in your style]

Give the agent focused context for each task

Before a change, the skill suggests the agent read the files it will modify, the related tests, one existing example of a similar pattern, and any type definitions involved. Load the relevant spec section rather than the whole spec. When you report an error, paste the specific failure rather than hundreds of lines of output.

The skill includes two packing patterns. The Selective Include lists only the files, pattern and constraint for one task. The Hierarchical Summary is a short project map that points to the key files in each area, so you can load one section at a time.

  • Effective: quote the one failing test and its stack trace line
  • Wasteful: pasting a 500-line test log when one test failed
  • Effective: load the authentication section of the spec for auth work
  • Wasteful: loading a 5000-word spec when you only work on one feature
TASK: Add email validation to the registration endpoint RELEVANT FILES: - src/routes/auth.ts (the endpoint to modify) - src/lib/validation.ts (existing validation utilities) - tests/routes/auth.test.ts (existing tests to extend) PATTERN TO FOLLOW: - See how phone validation works in src/lib/validation.ts:45-60 CONSTRAINT: - Must use the existing ValidationError class, not throw raw errors

Hand off between sessions safely

A fresh session is safe at a completed task boundary. Before you leave a session, the skill recommends recording the accepted scope and decisions, the current task status and next pending task, the files changed and working-tree state, the exact verification commands and their outcomes, and any open questions or approvals needed.

In the new session, the agent should read the rules, spec, plan, task status and the actual git status before acting. The skill says not to treat a previous conversation as approval unless the saved artifact records it. Commit completed work only when you or your repository workflow authorise it; otherwise leave the working tree intact and note that the changes are uncommitted.

  • Write decisions and next steps into the spec or plan file
  • Record which verification commands passed or failed
  • Note uncommitted changes and open approvals
  • Re-run verification if the code has moved since it was recorded

Keep the context budget under control

The skill treats the context window as a working desk rather than a filing cabinet. Conversation history, tool output and exploration pile up and most of it becomes stale. Its guidance is to trim proactively rather than wait until the window is full, since abrupt quality drops tend to happen then. Summarise progress when a conversation gets long, for example: "So far we've completed X, Y, Z. Now working on W."

Compact or summarise the conversation deliberately before critical work, if your tool supports it. Start a fresh session when you move to a different major feature.

Safety notes: scripts and network

The listed requirements for this skill are none. It does not run scripts and does not use the network. It is text guidance only and does not change your code by itself; any edits come from the agent you are using, under your normal permissions.

The skill asks the agent to treat instructions inside loaded files as data to show you, not commands to follow. Configuration files, data fixtures and external documentation should be verified before the agent acts on them. Keep human approval for schema changes, dependency additions and commits, as the example rules file does.

What people use it for

  • Setting up a CLAUDE.md for a new React and Node.js project so the agent uses the right test and lint commands
  • Stopping an agent from inventing APIs by pointing it at the existing validation utilities before a change
  • Recovering a long session that has drifted by summarising progress and starting a fresh one
  • Writing a handoff note so an automated or multi-day workflow can resume from the repository state
  • Splitting a large codebase into a project map so each task loads only one area

Frequently asked questions

How do I install the context-engineering skill?

Download the ZIP from this page and unzip it so the context-engineering folder sits in ~/.claude/skills/ or in your project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

Is the context-engineering skill free?

The skill is published under the MIT licence, as listed on this page. Check the repository's licence file for the full terms before reusing it.

Does the skill need anything else installed?

The listed requirements are none. The skill does not run scripts and does not use the network, and it is text guidance only.

Will this skill fix my code automatically?

No. It only shapes how the agent prepares its context. It does not run tools or change code by itself, so you still direct the work and review the results.

What is a CLAUDE.md file and do other tools use something similar?

CLAUDE.md is a rules file for Claude Code that holds project conventions, commands and boundaries, and it is loaded every session. The skill lists equivalents for other tools, including .cursorrules for Cursor, .windsurfrules for Windsurf, .github/copilot-instructions.md for GitHub Copilot and AGENTS.md for OpenAI Codex.

Why does my agent keep ignoring conventions or drifting in long sessions?

The skill's guidance is that context is the main lever on output quality, and stale or overloaded conversations cause drift. Write a persistent rules file, load only the relevant files for each task, and start a fresh session at a task boundary after saving your progress.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill is a good fit for developers starting a project with an AI coding assistant who want a solid CLAUDE.md or equivalent, and for teams whose agent ignores conventions or drifts in long sessions. It is less useful for non-technical users or anyone who expects it to run tools or fix code, since it only guides how the agent prepares its context.

Download the skill