This is the sixth article in the series about AI-friendly architecture. We have already discussed how code, documentation, and observability help agents understand systems. We also saw how skills can provide specialized knowledge for specific problems.
Now I want to take a step back and look at the architecture behind these skills.
Just as we learned to split large systems into smaller contexts, we may also need to learn how to split the context we give to agents.
The Context Monolith
One of the first attempts to prepare a repository for agents is often to create one central file with all the instructions.
Something like this:
AGENTS.md
# How our company works
Architecture
Domains
Coding standards
Deployment processes
Observability
Business rules
Runbooks
Testing conventions
Information about all teamsAt first, this file helps. It creates one place to record decisions and guidance that used to exist only in people's heads.
But it can grow quickly. After some time, it becomes hard to know which parts apply to each task, who is responsible for updating them, and which instructions have priority.
This is a context monolith.
The problem is not having a central file. The problem is putting knowledge from every domain and every tool in the same place without clear boundaries.
What We Learned from Microservices
The evolution of microservices taught us an important lesson: large systems are easier to understand when they are split by responsibility and business context.
A bounded context is not only a folder or a separate service. It defines a boundary that contains:
its own vocabulary;
specific rules;
clear responsibilities;
contracts with other contexts;
related data and behavior;
defined ownership.
For example, inside the payments context, the word transaction may have a specific meaning. Inside the orders context, the same word may appear but represent another part of the business.
Boundaries help prevent every component from needing to know everything.
We can apply a similar idea to the context given to agents.
Context Can Also Be Decomposed
Instead of giving every instruction for every problem, we can create specializations:
Each skill knows one context deeply. It can have its own vocabulary, rules, tools, and limits.
A payments skill can explain transaction states, refund policies, and the provider integration. A delivery skill can explain the deployment flow, environments, and approvals. An observability skill can guide investigations using logs, metrics, and traces.
The agent still has a general view, but it does not need to carry every detail at the same time.
Context Skills Are Not Microservices
It is important to make a distinction.
Context Skills are not the new microservices. A skill is not a production service, does not have a business API by definition, and does not replace a runtime boundary.
The connection between the concepts is the idea of decomposition.
Microservices help separate software capabilities. Context Skills help separate knowledge and workflows for agents.
The same domain may have a service, documentation, dashboards, and one or more related skills. The skill knows the context and knows how to query the right sources, but the data stays in the systems responsible for it.
The value comes from connecting these parts.
A Skill Is More Than Documentation
A documentation page explains a subject. A Context Skill also needs to explain how to work with that subject.
It can guide the agent about:
when that context is relevant;
which sources should be checked first;
which questions need answers;
which evidence should appear in the result;
which actions are allowed;
which actions need approval;
when the investigation should stop.
This creates a work contract for the context. The skill does not need to contain every detail, but it should help the agent find the right information and respect the team's limits.
For example, a payments skill may say that a refund investigation should check the operation contract, emitted events, and failure runbook. It may also require the agent to tell the difference between an authorized transaction and a captured transaction before forming a hypothesis.
What Does a Context Skill Need to Know?
A context-based skill does not need to copy all the information in the domain. It needs to know how to navigate it.
Some important elements are:
Vocabulary
Which terms have a special meaning in this domain? What is a transaction, an authorization, a capture, or a refund?
Responsibilities
Which service is responsible for each action? Who owns the context? Which decisions can the team make?
Contracts
Which APIs, events, and schemas connect this context to others? Which changes need versioning?
Sources of Truth
Where is the current data? Which documentation should be checked? Which platform contains the production signals?
Limits
Which actions are read-only? What needs approval? When should the agent stop and ask for help?
This set of information gives the agent depth without requiring it to carry the knowledge of the whole company.
These limits should be defined together with the architecture's security policies. As we saw in the article Security, Guardrails, and Fitness Functions for Agents, a skill can guide the agent, but it should not be the only protection against an unsafe action. Permissions, scopes, and approvals must also be enforced by the tools and protected resources.
One Agent Connects the Skills
Breaking down the context does not mean creating isolated agents that cannot communicate.
The main agent coordinates the specializations.
Imagine an investigation where the payment failure rate has increased. The agent can do the following:
1. Activate the Payments Context Skill.
2. Use the Observability Skill to investigate the signals.
3. Use the Delivery Skill to check recent deployments.
4. Use the Data Platform Skill if the flow depends on processed data.
5. Combine the evidence into a hypothesis.
6. Show what was confirmed and what is still uncertain.Each skill adds a specific view. The agent connects the information between them.
This separation allows a skill to be maintained by the people who really know that context. They do not need to maintain every instruction for the engineering agent.
Too Much Context Can Also Be a Problem
Decomposing does not mean creating hundreds of small skills.
There is a point where too much fragmentation starts to cause problems. If the agent needs to activate ten skills to answer a simple question, the boundaries may be wrong or the task may be split into units that are too small.
A good boundary usually groups knowledge that changes together, is used together, and has related ownership.
Another useful question is: if this context changes, who needs to review the knowledge? If the answer includes very different teams, conflicting responsibilities, or unrelated sources, the boundary may be too large.
Boundaries should also be observable. We need to know which context was consulted, which sources were used, and which rules guided the answer. Without this visibility, it is hard to understand whether a problem came from missing information, the choice of skill, or the agent's interpretation.
We can start with a few larger contexts:
Observability
Delivery
Data
Payments
Orders
SecurityOver time, each context can evolve. An observability skill may later gain specializations for incidents, performance, and capacity. This split should happen when there is a real need, not just because it is possible to create more files.
Where Do Context Skills Live?
A Context Skill can live with the team's code, in a platform repository, or in a shared catalog. The choice depends on who maintains the context and how the agents will be used.
The most important points are to make clear:
who owns the skill;
which agents can use it;
which external sources it consults;
how its instructions are versioned;
how changes are reviewed;
which permissions it needs.
For example, a skill for observability may be maintained by the platform team. It can explain how to query standard dashboards and metrics, but it should not store copies of production data.
A payments skill may be maintained by the team responsible for the domain. It can point to ADRs, contracts, and runbooks, but it should continue to respect the original sources.
Context Skills and Ownership
Ownership is an essential part of this architecture.
If everyone is responsible for a skill, probably no one is truly responsible. If no one reviews the instructions when an API changes, the agent starts working with outdated knowledge.
A skill can have a simple metadata file:
name: payments-context
owner: payments-team
review_frequency: quarterly
sources:
- payment-service
- payment-documentation
- payment-dashboardsThis file does not solve the maintenance problem on its own, but it makes responsibility more visible and can help create a review process.
Conclusion
For a long time, our concern was decomposing systems so they could be developed and operated by different teams.
Now we also need to decompose the knowledge we give to agents.
Context Skills are a way to create boundaries for this knowledge. They allow each context to have clear vocabulary, rules, tools, ownership, and limits.
The agent does not need to know everything deeply. It needs to know which contexts exist, when to use them, and how to connect the evidence it finds.
In the next article, we will separate the parts that make this architecture work: agents, skills, tools, and MCP. The goal is to understand the role of each layer before using them in a real case.
Comments