Agent Skill for Context Engineering

An agent skill for context engineering tells an AI agent what context to load, what sources to trust, what to ignore, and how to use context without flooding the model window. The goal is not more context. The goal is the right context at the right stage of the workflow.

That makes context engineering a natural skill-shaped problem. A one-off prompt can ask the model to "use the right context," but a reusable skill can define the source hierarchy, load order, exclusion rules, tool boundaries, and completion evidence every time the job runs. If you are still defining the category, start with What Is an Agent Skill?. This article focuses on the narrower question: how do you package context strategy into an agent skill?

OpenAI's Codex Agent Skills documentation describes skills as packages of instructions, resources, and optional scripts, with progressive disclosure so Codex begins from lightweight skill metadata and loads the full instructions only when relevant. Anthropic's Agent Skills overview uses the same three-level pattern: metadata first, SKILL.md instructions when triggered, and bundled resources as needed.

That is the key context-engineering move. The skill is not a giant prompt. It is a controlled context loader.

Many agent failures are not reasoning failures. They are context failures.

Common examples:

• The agent reads stale docs instead of current source files.
• It searches broadly before checking the obvious primary source.
• It loads too much reference material and misses the task.
• It treats examples as rules.
• It ignores the user's narrow scope.
• It invents missing context instead of stopping.

A context-engineering skill prevents those failures by making the context plan explicit. It tells the agent where truth lives, what counts as supporting material, which sources are only examples, and when the absence of context should block the task.

This is different from simply increasing the context window. A larger window lets the agent hold more material, but it does not decide which material is authoritative. In a community discussion about whether RAG is obsolete as context windows grow, practitioners repeatedly return to cost, latency, relevance, and source selection. A skill gives the agent a repeatable policy for those choices.

For skill authors, the immediate payoff is consistency. A documentation-maintenance skill should not randomly prioritize a year-old tutorial over the current API reference. A code review skill should not wander through unrelated packages before reading the diff. A customer-research skill should not treat a single anecdote as a market conclusion. The skill encodes those decisions before the run begins.

Use this structure inside a skill:

This reduces the agent's need to guess. The important detail is that the table is not generic. A strong skill names the actual files, MCP servers, datasets, docs pages, or source systems the agent should use.

For a launch-readiness skill, the primary sources might be merged pull requests, release notes, current docs, and a sample app build. For a sales-call analysis skill, the primary sources might be the transcript, CRM account fields, and the team's current qualification rubric. For a code-review skill, the primary source is the diff, not the whole repository.

## Context Rules

1. Read the user brief first.
2. Read existing examples before writing new content.
3. Prefer official documentation over blog summaries.
4. Use prior project memory only for positioning, not for current file contents.
5. Stop if the target files already exist.
6. Do not modify unrelated content files.

## Completion Evidence

Return the sources inspected, the context you accepted, the context you rejected, and the files or artifacts created or changed.

This is context engineering because it controls source selection, order, and proof. It also makes the agent's behavior easier to debug. If the output is wrong, the team can ask whether the skill loaded the wrong source, loaded the right source too late, accepted a low-trust example as policy, or failed to stop when a required input was missing.

That is why context engineering belongs inside the skill, not only inside the model prompt. The model prompt may describe general behavior. The skill describes the context policy for one repeatable job.

Skills and retrieval-augmented generation are complementary. RAG retrieves candidate facts. A context-engineering skill tells the agent how to use those facts.

If a team has a vector database but no skill, the agent may retrieve information without knowing how to apply it. If a team has a skill but no retrieval, the agent may know the procedure but lack the current facts. Strong systems combine both. The deeper comparison is covered in Agent Skill vs RAG: What Each One Actually Solves, but the short version is simple: retrieval supplies evidence; the skill supplies judgment rules.

Long-context models do not remove that need. A million-token window can make more material available, but it can also make the agent wade through irrelevant, duplicated, or contradictory context. The hard question is not "Can it fit?" The hard question is "Should this be in context for this task?"

A context-engineering skill should answer:

• What should be loaded eagerly?
• What should be retrieved only if needed?
• What should stay outside the model window and be accessed through a tool or script?
• What should never be used as truth?
• What evidence must appear in the final answer?

This is where progressive disclosure matters. OpenAI's Codex docs note that the initial skill list is kept small and the full skill instructions are read only after selection. Anthropic's overview makes the same point with metadata, instructions, and on-demand resources. That design keeps a skill from becoming its own context problem.

The Model Context Protocol introduction explains MCP as a standard way for AI applications to connect to external systems such as local files, databases, tools, and workflows. The protocol matters for context engineering because it separates raw access from controlled use.

MCP resources and MCP tools should not be treated as the same thing. The MCP resources specification describes resources as server-exposed context such as files, database schemas, or application-specific information. The MCP tools specification describes tools as model-invoked actions such as querying a database, calling an API, or performing computation.

That distinction is useful inside a skill:

In a context-engineering skill, MCP rules might say: use the docs server for official docs, use the GitHub server for current files, query the CRM only when customer context is required, never query production data unless the user asks, and include the source ID or URL for every claim that drives a decision.

The skill turns raw access into a controlled context strategy. It should also define human-in-the-loop boundaries for sensitive actions. MCP's tool guidance recommends clear visibility and confirmation for tool invocations; a skill can make that concrete by naming which operations are read-only, which require approval, and which are out of scope.

Memory is easy to confuse with context engineering. They overlap, but they are not the same.

LangChain's short-term memory docs describe thread-level state through checkpointers and middleware that can read, trim, or summarize messages before a model call. That is useful infrastructure: it lets an agent remember previous turns, keep custom state, or reduce message history so the next call fits within the context window.

A skill still has to decide how that memory should be trusted.

For example, a support skill might say:

• Use thread memory for the customer's stated preference and prior issue summary.
• Use the current account record for plan, region, and billing status.
• If memory conflicts with the CRM, cite the conflict and prefer the CRM.
• Do not use old conversation memory to override current policy.

Without those rules, memory can become a silent source of stale context. The agent may carry forward an outdated assumption because it was present in the thread, not because it is still true. Context engineering is the discipline of assigning trust and scope to every context source, including memory.

• Define the highest-trust source.
• Define source load order.
• Separate current facts from examples.
• Put large references in separate files.
• Use specific file paths or tool names where useful.
• Require citations or file paths for important claims.
• State when to stop because context is missing.
• Tell the agent what not to inspect.
• Distinguish read-only resources from action-taking tools.
• Define when memory is allowed to influence the output.
• Keep the final answer tied to evidence.

Imagine an agent is asked to update a migration guide after an SDK change. Without context rules, it may read old docs, a stale README, release notes, and random examples in whichever order search happens to return. That produces confident but fragile work.

A context-engineering skill should set the source hierarchy before the agent starts: merged code and current tests first, official API reference second, release notes third, old tutorials last. It should also tell the agent what not to use as truth: archived docs, examples from deprecated branches, or old support answers. If the code and docs disagree, the skill should require the agent to report the conflict instead of smoothing it over.

The skill is not adding more context. It is making context governable.

The same pattern applies beyond engineering. A founder-interview skill can require the transcript before the summary. A hiring-scorecard skill can require the rubric before the recommendation. A product-launch skill can use release notes for shipped behavior, positioning for message hierarchy, support tickets only as evidence of questions, and docs for current user-facing instructions.

When you write a context-engineering skill, start with the job rather than the sources. The job determines which context matters.

1. Name the repeatable job.
2. List the minimum inputs required to start.
3. Rank sources by authority.
4. Define load order and retrieval triggers.
5. Identify excluded or low-trust sources.
6. Add conflict rules.
7. Add stop rules.
8. Require completion evidence.

For example:

## Context Policy

Primary source:
- Current repository diff and tests.

Secondary sources:
- Current docs in /docs.
- Release notes for the target version.
- Prior migration examples, only as examples.

Conflict rule:
- If code and docs disagree, treat code/tests as current behavior and report the docs conflict.

Retrieval rule:
- Search old issues only after reading current docs and only to identify repeated confusion.

Stop rule:
- Stop if the target version or repository path is missing.

This kind of policy is short enough to fit in the main SKILL.md. Longer examples, rubrics, schemas, and templates can live in references/ so the agent loads them only when they matter.

The first mistake is treating all context as equal. A transcript, a metric dashboard, a sales note, and a published policy are different kinds of evidence. The skill should say which one wins.

The second mistake is putting the entire world into the skill body. Progressive disclosure works because the first file is small enough to guide the agent, while deeper resources are loaded on demand. If the skill starts with fifteen pages of background, it becomes a tax on every run.

The third mistake is omitting rejection rules. Good context engineering is not only about what to read. It is also about what to ignore: stale docs, deprecated examples, broad internet summaries, old memories, or files outside the user's requested scope.

The fourth mistake is skipping completion evidence. A final answer that says "I used the docs" is weak. A final answer that names the files, URLs, queries, or resources inspected is easier to trust and improve.

Context engineering is not the art of maximizing tokens. It is the discipline of deciding what should enter the model's working set, when it should enter, and how much authority it should have.

An agent skill is a practical way to package that discipline. It gives the agent a repeatable context policy: load this first, trust this most, retrieve this only when needed, ignore that, stop here, and show your evidence. For skill authors, that policy is often the difference between a clever demo and a workflow other people can run repeatedly.

Once the skill is drafted, test it the same way you would test any reusable workflow. Run it on a clean example, a messy example, and a missing-context example. Check whether it starts in the right place, rejects the wrong sources, and stops when it should. How to Test an Agent Skill Before You Publish It covers that pre-release loop; for this category, the most important test is whether two agents given the same job choose the same source hierarchy.