The agent skill is installed, the MCP server is connected, and the agent has real-time access to the operation's data. Responses arrive fast. But there's a gap between what the agent returns and what the shift coordinator actually needs: when you ask about coverage in the northern zone, the agent reports the number but doesn't tell you whether that number is a problem for that city on a Tuesday at 6 p.m. When you ask how to handle drivers straying outside the main demand area during a peak, it offers reasonable options but not the resolution you landed on two months ago that actually worked in that specific context. That gap between "responds" and "diagnoses" has one cause: the operator context file doesn't contain the information that would turn API data into operation-specific diagnostics.

This article isn't about the base skill or about separating configuration layers to keep updates clean — that's covered in the article on forking the public skill. It's about what goes inside the operator context file: which sections make it useful, what specific data belongs in each one, how much detail is enough for a first working version, and which mistakes produce a file that technically exists but generates no different responses than the agent would give without it. The audience is the operator who already has the agent running and notices that its answers are technically correct but too generic to be directly actionable.

Why the file determines the ceiling of what the agent can diagnose

The agent operates on two types of data: what it gets in real time from the platform API — active drivers, current coverage, ongoing trips, cancellations in the last hour — and what it has in its system context: the operation's conventions that define what each number means. The platform provides the first set; the operator provides the second. When that second set is empty or too generic, the agent has access to the right data but no reference point to interpret it: it knows there are twelve active drivers in the northern zone, but not whether that's sufficient, low, or critical for that zone at that time of day.

The practical difference between an agent with a well-built context file and one without is not speed or data access — it's specificity. With the file, the agent can respond: "northern zone is at twelve active drivers, 30% below the minimum threshold for Tuesday afternoons in peak season; the last time it dropped to that level under similar conditions, the pattern that worked was repositioning two drivers from the central zone before 6:30 p.m." Without the file, the agent gives the same response to any operation with twelve drivers in a zone: it describes the number and leaves interpretation to the coordinator. That's the difference between a tool that amplifies the coordinator's judgment and one that returns raw data without reference.

The five sections that distinguish a useful file from one that fills space

A context file that produces specific diagnostics has five sections. It's not the only valid structure, but it closes the most common information gaps in operations that have had the agent running for more than thirty days:

Zones and thresholds: the shared vocabulary and the numbers that make it specific

Geographic definitions solve the most common problem in operations where the team uses internal names that don't match zone identifiers in the system. An agent that receives a question about "the industrial zone" needs to know whether that name maps to the northern zone in the panel, whether it includes or excludes the federal highway access, and whether "industrial zone" on the night shift refers to all three polygons in the system or just the main one. Without that mapping, the agent works with ambiguity — each response may refer to a different geography depending on how the coordinator phrased the question — and that cost accumulates in inconsistent diagnostics.

Operational thresholds are the section most directly tied to diagnostic quality, because they allow the agent to interpret a number rather than just return it without reference. A well-documented threshold doesn't say "low availability in the northern zone" — it says "fewer than 14 active drivers in the northern zone between 5 p.m. and 8 p.m. Monday through Friday is alert level; fewer than 8 drivers in that same window is critical level and justifies activating repositioning incentives." That specificity lets the agent compare current state against the operation's own reference and generate an actionable diagnostic rather than a neutral data point the coordinator has to interpret without context.

Incidents and resolutions: the memory that eliminates starting diagnosis from scratch

The incidents and resolutions section is where quality varies most sharply between files that produce useful diagnostics and files that exist without making a difference. The distinction between a useful entry and filler is concrete: a useful entry describes the situation with its specific parameters, the decision the coordinator made, the observable result in the following thirty minutes, and the context that explains why that decision worked. A filler entry says "northern zone without coverage, incentive activated, resolved" — there's nothing there the agent couldn't infer on its own. What makes an entry useful is the detail that isn't in the data: that in that specific case the southern zone was also low and pulling drivers from there wasn't viable, that the right resolution was a fixed-point incentive rather than a zone-wide one.

The concrete format for a well-documented incident entry has four fields: Situation (what the operation looked like at the moment of the incident, with specific numbers for coverage, pending cancellations, and unassigned requests); Context (what was unusual or explanatory — a nearby event, end of school shift, rain, payday week); Action (the specific decision taken with its exact parameters — how many drivers, toward which zone, what type of incentive, in what time window); Result (what changed in the following fifteen to thirty minutes). When the agent has twenty to thirty entries in this format, incident diagnostic time drops from ten or fifteen minutes to two or three, because the agent can identify the pattern and retrieve the documented resolution instead of building a new diagnosis from scratch.

The first version in two hours: what to include and what to defer

The most common mistake when building the context file for the first time is trying to document everything before using it. A file that attempts to cover every possible scenario in the first session takes days to build and ends up full of hypotheses about situations that haven't happened yet — which the agent can infer from the data with nearly the same precision. What it can't infer because it requires local knowledge are three specific things: the internal zone names and their correspondence to system identifiers, the thresholds for the three or four main zones during peak demand hours, and the two or three most costly recurring incidents with their documented resolutions.

A working first version can be built in two hours using the agent itself as a working partner. The concrete process: export the zone list from the panel, ask the agent to use that list as a starting point and formulate the threshold questions it needs the operator to answer (this takes twenty to thirty minutes), then document the two or three most recurring incidents using the four-field format (forty to sixty minutes). What stays out of that first session — seasonal patterns, individual drivers, local events — gets added in short sessions after shifts where relevant incidents occurred. The file grows through use, not in a one-time design session, and each incident documented in real time produces a more precise entry than one reconstructed from memory weeks later.

The three patterns that make a file technically present but operationally empty

The first pattern that eliminates the file's usefulness is the absence of specific numbers. Noting that "the northern zone has low availability during peak hours" adds nothing the agent can't already infer from real-time data. What adds value is the threshold: exactly how many drivers is "low" in that zone at that hour, for that operator in that city. Without the number, the agent can't compare current state against the operation's specific reference and produces the same response it would give without the file: technically correct, useful for confirming status, but not for diagnosing whether that status requires action.

The second pattern is documenting only operational state without past incident resolutions. A file full of zone descriptions and operational patterns is useful for answering status questions — how coverage looks, how many drivers are active, which zones have the most cancellations — but not for reducing diagnostic time during the critical moments of a shift, which is exactly where the agent produces the most value when it has the right context. The third pattern is using names in the file that don't match system identifiers: if the file says "industrial zone" and the platform records it as "Zone_North_03," the agent spends part of its context window resolving the ambiguity before arriving at the response — that disambiguation cost repeats with every query and degrades the specificity of each diagnostic.

The operator context file isn't an onboarding document built once at skill installation and left untouched — it's an operational record that grows with every shift where something worth documenting happens. Each incident logged with its resolution, each threshold calibrated to the current season, each seasonal pattern recorded before it arrives, is context the agent can use in the next query to produce a more specific diagnostic than the previous one. That accumulation can't be replicated without the time investment: it's the one input no generic platform configuration can supply at installation time.

Operators who reach six months with a well-maintained file have something no platform setting can directly deliver: the specific intelligence of their city, their zones, and their operation, accumulated shift by shift in a format the agent can use to answer questions that have no generic answer. That specificity is what makes the same coverage question in the northern zone produce different diagnostics for operators running the same platform with the same real-time data. The difference isn't in the skill — it's in the context each operator built.