Agent Skills for Context Engineering

Agent skills for context engineering are reusable, task-specific modules that tell an agent how to collect, rank, compress, retrieve, retain, and validate context. Instead of placing every rule in one long prompt, a well-designed skill loads only when needed and defines a clear procedure, output contract, failure handling, and acceptance tests.

What a Context Engineering Skill Should Do

Context includes more than the user’s prompt. It can contain system instructions, tool definitions, retrieved documents, conversation history, memory, and tool output. Poor context management can cause several recognizable failures. These failures include lost-in-the-middle, where useful information receives less attention when buried in a large context. The system also faces issues of distraction, caused by irrelevant or duplicated material, alongside poisoning, which occurs when errors or untrusted content influence later steps. Additionally, the agent may experience conflict when two sources give different instructions or facts. Finally, the model can suffer from context growth, where long-running sessions accumulate too much obsolete material.

A useful skill addresses one bounded problem. The context-retrieval skill collects and ranks relevant information. The context-compression skill reduces a long transcript without losing essential state, while the memory-systems skill decides what belongs in short-term, long-term, or relationship-based memory. Additionally, the filesystem-context skill stores plans and large results outside the active context. Finally, the evaluation skill tests whether the final answer used the right context and followed the required process.

The open-source Agent Skills for Context Engineering collection organizes reusable skills around these areas, including context-degradation, context-optimization, tool-design, and advanced-evaluation.

Prefer Skills to One Giant Prompt

A long prompt treats every task as if it needs the same instructions. That makes unrelated rules compete for attention and makes failures difficult to isolate.

Progressive disclosure uses three levels to manage context efficiently. At the metadata level, the agent sees the skill name and a short description. Once a matching task appears, the agent loads the procedure level, which contains the full instructions. Finally, at the detail level, it reads supporting files, examples, schemas, or tool references only when necessary.

This structure lets one agent retain access to many specialized procedures without placing all of them in every request. It also makes each skill independently testable and reusable.

Published descriptions of the referenced collection do not agree on one permanent skill count: snapshots mention 14 skills, 17 skills, or “13+.” Treat the catalog as something that can expand, and organize your system around stable responsibilities rather than a fixed number.

Reusable Context Engineering Skill Template

Copy this structure into a SKILL.md file or another skill format supported by your agent:

---
name: task-context-retriever
description: >
  Use when answering [task type] requires information from [approved sources].
  Do not use for [excluded situation].
---

# Task Context Retriever

## Inputs
- User request:
- Current task state:
- Approved sources:
- Configured context budget:
- Required output format:

## Procedure
1. Identify the facts needed to complete the current task.
2. Retrieve only from approved sources.
3. Remove duplicate and irrelevant passages.
4. Rank each item by task relevance, source quality,
   freshness when applicable, and directness.
5. Keep the highest-value context within the configured budget.
6. Label conflicts, stale information, and unsupported assumptions.
7. If required evidence is missing, state the gap instead of
   inventing an answer.

## Output Contract
Return:
- Selected context:
- Source references:
- Conflicts or uncertainty:
- Missing information:
- Recommended next action:

## Failure Handling
- Retrieval unavailable: report the failure and use only verified context.
- Sources conflict: present both claims and identify their sources.
- Context exceeds budget: compress lower-priority items before
  removing the task objective, constraints, or critical evidence.

## Acceptance Tests
- Correct source is selected from mixed results.
- Duplicate passages appear only once.
- Conflicting sources are identified rather than silently merged.
- Missing evidence produces a clear gap report.
- The output stays within the configured context budget.

The description is the routing layer, so it should state both when to activate the skill and when not to use it. If you are starting from a blank file, the Agent Skills for Context Engineering generator can help turn a repeated workflow into this testable structure.

Example: Context Retrieval Skill

Suppose an agent must answer a customer question from tickets, product documentation, and its previous conversations. Its retrieval procedure should begin by extracting the customer’s exact issue and required facts. Next, it retrieves matching documentation and account history before deduplicating passages that repeat the same information. The agent then ranks current account data and authoritative documentation above general background material. After placing critical constraints near the beginning or end of the assembled context, it keeps older conversation details only when they affect the answer. Finally, the system must flag conflicting documentation and clearly state when the available records do not contain the answer.

This skill is more reliable than telling the agent to “use all relevant information,” because “relevant” has not been defined.

Design Memory and Compression Separately

A memory skill needs rules for deciding what survives a turn or session. Short-term memory should contain the active goal, constraints, unresolved questions, recent decisions, and references to working artifacts. Long-term memory should hold durable facts or preferences, supported by a source, date, and confidence or verification status when possible. For structured relationship memory, a graph representation can preserve links between entities, although it requires more engineering than a basic vector store. Finally, filesystem memory is useful for plans, large tool results, scratchpads, and communication between workers because the agent can retrieve details only when needed.

A compression skill should produce a structured summary rather than a generic recap. The summary must include the current objective and the constraints that remain in force, along with the decisions already made and the supporting evidence for those decisions. It should also document which files or artifacts changed and flag unresolved questions. Finally, the summary must outline the next actions and provide references for any material that was removed from the active context.

For very large tool outputs, observation masking can replace the full result with a reference. Context partitioning can place independent work in separate agents, while prefix caching can reuse stable prompt content across requests. The optimization target should be tokens per completed task, not merely tokens per request.

Evaluate Skills With Task-Level Tests

Evaluate the context process and the final outcome. A practical rubric can assess several dimensions, starting with factual accuracy to determine whether claims are supported by the selected context. It should also measure completeness by checking whether all required task facts are present, and context relevance by verifying how much selected material actually influenced the answer. The rubric needs to track tool efficiency to understand whether the agent used an appropriate number of calls. Furthermore, it should evaluate process quality by confirming that conflicts, gaps, and assumptions were handled properly. Finally, the assessment must confirm end state, ensuring that an action-oriented agent completed the required changes.

Use fixed tasks that include easy cases, ambiguous cases, conflicting sources, missing evidence, noisy histories, and oversized tool outputs. Compare the agent with the skill against one without it. Human reviewers should inspect important edge cases, while rubric-based LLM evaluation can help scale routine comparisons.

Troubleshooting Guide

Several common symptoms require specific adjustments to the context engineering pipeline. The following table identifies typical failures, their underlying causes, and the corresponding fixes.

Symptom	Likely cause	Fix
The agent ignores a key fact	Important material is buried or diluted	Rank it higher, shorten surrounding text, or partition the task
Answers repeat obsolete information	Memory has no freshness or conflict rules	Add source dates and explicit replacement rules
The wrong skill activates	The description is vague	Name the task, trigger conditions, and exclusions
Two sources are merged incorrectly	Provenance is missing	Preserve source labels and surface conflicts
Sessions become slow and expensive	Tool output is never offloaded	Store large results and pass references
Compression removes needed evidence	The summary format is too generic	Require decisions, evidence, artifacts, gaps, and next steps
The final answer is correct for the wrong reason	Evaluation checks only wording	Test tool use, evidence selection, and end state

Applying these targeted adjustments addresses both routine context failures and complex edge cases, ensuring that the agent maintains accurate retrieval.

A Practical Build Process

To build a practical process, first choose one observed failure, such as conflicting retrieval results. Next, name the context operation that should prevent it, which might be context-ranking or context-conflict-detection. Afterward, write a description with a clear trigger and exclusion. You must then define the required inputs, ordered procedure, output schema, and fallback behavior. Following this, add tests for normal, missing, conflicting, and oversized context. During testing, load the skill progressively instead of placing its references in the system prompt at startup. Finally, compare task success and token use against a version without the skill, and revise the weakest step.

Frequently Asked Questions

What is the difference between prompt engineering and context engineering?

Prompt engineering primarily improves instructions for a request. Context engineering manages the complete information available to the model, including instructions, tools, retrieved documents, memory, history, and tool output.

What should the first context engineering skill do?

Start with the failure that occurs most often. Create a retrieval skill if the agent cannot find the right information, a ranking skill if it selects too much noise, or a compression skill if long sessions become unreliable.

How are agent skills different from one long prompt?

Skills separate procedures by task and support progressive loading. One long prompt must carry all instructions together, increasing irrelevant context and making updates and tests harder.

How should a context compression skill be evaluated?

Test whether it reduces context while preserving the objective, constraints, decisions, evidence, changed artifacts, unresolved issues, and next actions. Token reduction alone is not a successful result if task quality declines.

Can context engineering skills work outside a coding assistant?

Yes. The principles are platform-neutral, but the host must support reusable skills or custom instructions. Otherwise, store the same skill structure in your own orchestration layer and load it when its trigger matches.