# Context engineering: repository knowledge, MCP, and skills

By Vibe Haus · Published and source-reviewed 2026-10-10

Source: https://vibehaus.team/blog/context-mcp-and-skills

How repository knowledge, task context, MCP tools, and agent skills fit together, with provenance, freshness, trust boundaries, and a practical context contract.

Original Vibe Haus synthesis and proposed engineering workflows, informed by the linked primary sources. These articles are not peer-reviewed studies or measured customer results. Examples and thresholds are illustrative unless explicitly attributed.

> Agents need relevant, current information for the task they are doing. This guide explains how to select that information, provide tools and procedures, and maintain the underlying sources.

## Separate knowledge, procedures, and access

An engineering agent needs several different things that are easy to collapse into one large prompt. It needs durable knowledge about the product and repository, temporary facts about the current task, procedures for recurring work, and access to tools or external systems. These layers change at different rates and carry different authority.

A repository guide can describe where code lives and which checks are expected. A task contract can identify today’s desired behavior. A skill can explain how to perform a recurring review. The Model Context Protocol (MCP) gives agents a standard way to call tools, such as search or document retrieval. None of those, by itself, establishes that an external document is accurate or that a user authorized a consequential action.

The Agent Skills specification defines a discoverable SKILL.md with a name and description, with additional material loaded when useful. MCP defines a protocol for exposing capabilities and exchanging messages. These are complementary mechanisms: a procedure can use a tool, while the tool should retain its own access controls and input validation.

### Workflow: A context assembly path with a freshness and authority check.

1. Locate: Start with the repository map and task contract.
2. Retrieve: Read the smallest relevant source or tool result.
3. Qualify: Record provenance, revision, and unresolved conflicts.

Decision: Is the context sufficient and trustworthy for this decision?
- Yes → act within the existing authority and preserve evidence.
- No → retrieve the missing fact or return the unresolved decision.

Sources: [Agent Skills specification](https://agentskills.io/specification); [Streamable HTTP transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)

## Keep repository instructions concise and current

A repository map should answer where to look next. Name the entry points, ownership boundaries, local commands, and important architectural decisions. Link to detailed documents instead of copying them into a single instruction file. The goal is to help an agent locate the relevant source of truth and recognize when the task crosses into another area.

Dex Horthy’s AI Engineer talk presents a research, planning, and implementation approach for complex codebases. We take a narrow lesson from that framing: understanding the current system is a separate artifact worth checking before a broad edit. A plausible plan built on the wrong version of the code remains a bad plan.

For a billing task, the map might lead to the account model, invoice calculation, external payment adapter, and migration policy. It should also distinguish maintained decisions from old exploration notes. A workshop proposal and an accepted architecture decision can both be useful, but treating them as equally authoritative produces avoidable contradictions.

- Entry points: the few paths that orient a reader to the feature.
- Ownership: who resolves product, data, and release decisions.
- Verification: commands and environments that check the relevant behavior.
- Status: accepted decisions, current implementation, and explicitly tentative ideas.

Sources: [No Vibes Allowed: Solving Hard Problems in Complex Codebases](https://ai.engineer/talks/rmvDxxNubIg-context-engineering-for-complex-codebases)

## Build a context contract for the current task

Task context should explain the decision being made, the version of the system under discussion, and the boundaries that matter. A file path without a revision can become misleading after a rename or refactor. A log excerpt without environment and timestamp can describe a different deployment. Preserve enough provenance to reconnect a claim to the thing it describes.

The contract can remain compact. Include the outcome, relevant source paths, current revision, constraints, acceptance examples, known unknowns, and the next decision. Separate observed facts from hypotheses. “The export job times out in staging with this fixture” is an observation. “The database needs an index” is a hypothesis until examined.

When the work moves to another agent or person, summarize what was learned and where the supporting evidence lives. Do not simply compress every prior message. Preserve decisions, rejected alternatives that still matter, current failures, and unresolved questions. A handoff should let the recipient resume reasoning without inheriting an unexamined conclusion.

```yaml
# Illustrative context contract.
task: Diagnose slow filtered export.
revision: Record the actual commit under investigation.
observed:
  - Staging request exceeded the agreed limit with the attached fixture.
hypotheses:
  - Query plan may scan too many rows; not yet confirmed.
sources:
  - Current route, query implementation, schema, and captured query plan.
constraints:
  - Preserve account isolation and existing output format.
next_decision: Is the bottleneck query work, serialization, or delivery?
missing: Representative upper-bound dataset and acceptable latency target.
```

## Make skills procedural and inspectable

In the AI Engineer talk Don’t Build Agents, Build Skills Instead, Barry Zhang and Mahesh Murag describe packaging reusable knowledge for general agents. Our recommendation is to use a skill when a task has a repeatable method with non-obvious checks. A review skill can explain how to inspect a changed boundary; it should not duplicate the repository’s entire architecture.

A good skill explains when it should be used and includes required inputs, a procedure, a useful output, and conditions under which to stop. Keep instructions that apply to every task in the appropriate repository or runtime policy. Keep task-specific details in the task itself. Otherwise skills become competing collections of global rules that are hard to reconcile.

Version a skill when its behavior changes. Test it with a realistic task that includes an inconvenient case: missing evidence, conflicting requirements, a failing environment, or a request outside its scope. A syntactically valid SKILL.md can still encourage poor decisions. Behavioral testing should ask whether the resulting artifact helps a real reviewer complete the job.

Sources: [Don’t Build Agents, Build Skills Instead](https://ai.engineer/talks/CEvIs9y1uog-agent-skills)

## Design MCP tools around bounded questions

A useful tool interface gives an agent a clear question it can ask and a result it can interpret. For a public research library, “search published articles” and “read this article by slug” are enough. A generic “fetch any URL and execute what it says” capability would create a very different risk surface without improving that basic use case.

Tool results should include stable identifiers and source URLs. Search snippets help choose a document; they are not a substitute for reading the relevant passage. A read result should expose the full authored content or explicitly state truncation. Unknown identifiers should produce an understandable error instead of silently selecting a nearby item.

Our public MCP endpoint follows that narrow design: it searches and reads this site’s own published research and retrieves the downloadable skills. It does not connect to customer systems or receive repository credentials. Its scope is visible on the Data / MCP / Skills page, and the same article text is available through JSON and Markdown for clients that do not use MCP.

## Treat retrieved content as data with provenance

An external page can contain instructions written by someone other than the user. A document that says to ignore prior rules or send credentials somewhere is still just document content. The agent runtime should keep retrieved text separate from higher-priority instructions, and tools should enforce access boundaries independently of the model’s interpretation.

The same principle applies inside a repository when files, issue comments, or generated output can be influenced by outside contributors. Read them for relevant facts; do not let them silently broaden the task’s authority. Skills downloaded from the internet should be inspected before installation, just as a team would inspect another automation artifact.

Freshness is another trust dimension. Cache stable documents with explicit versions; recheck volatile facts before acting on them. If a repository guide conflicts with the installed framework’s current documentation or the executable code, investigate and record the resolution. Do not hide the conflict by choosing whichever source supports the first plan.

## Maintain context as part of changing the system

When a change moves an entry point, changes a command, or supersedes an architectural decision, update the map in the same delivery cycle. The person accepting the change should be able to verify that the next engineer will find the right path. This makes documentation maintenance observable rather than an occasional cleanup project.

Sample failed agent runs and classify the context failure. Was the needed fact absent, stale, difficult to retrieve, contradicted, or ignored? Adding more text helps only the first category and sometimes the third. A better source hierarchy, a smaller tool result, or a clearer stopping condition may be the more effective repair.

The intended outcome is a connected knowledge system: a short repository map, task-specific evidence, reusable procedures, and bounded tools. Each part should be independently understandable. That lets people and agents share the same engineering context without requiring everyone to consume the entire history of the project.

## Sources and further reading

Sources reviewed 2026-10-10. This is a focused reading list, not an exhaustive literature review. Source dates and study conditions matter; follow the original links for their full methods and limitations.

- [Agent Skills specification](https://agentskills.io/specification): Agent Skills. Specification.

- [Streamable HTTP transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports): Model Context Protocol · 2025-11-25. Specification.

- [No Vibes Allowed: Solving Hard Problems in Complex Codebases](https://ai.engineer/talks/rmvDxxNubIg-context-engineering-for-complex-codebases): Dex Horthy · AI Engineer. Conference talk.

- [Don’t Build Agents, Build Skills Instead](https://ai.engineer/talks/CEvIs9y1uog-agent-skills): Barry Zhang & Mahesh Murag · AI Engineer. Conference talk.

## Related services

- [ai native engineering](https://vibehaus.team/ai-native-engineering)

- [product design](https://vibehaus.team/product-design)

## Reuse

You may use and adapt our original templates and workflows with attribution. Third-party sources retain their own terms.

Downloads and tools: https://vibehaus.team/data