AX: Context Documents (SKILL.md) as Interface Page Copy

When building agentic systems, connecting an MCP server full of tools only solves half of the interface problem. Tools act as the interactive forms, modals, and setup wizards of your application. However, dropping a user into an interface made entirely of forms and action modals without any explanatory page copy makes navigation guesswork.

To bridge the gap between having an interactive capability and knowing the business rules around how to apply it, we supply Modular Runtime Protocols (SKILL.md documents) within the orchestration harness. In Agent Experience (AX), these Markdown documents act as our in-page copy, contextual help banners, and domain playbooks.

Decoupling Method from Mandate

In Part 2: AX: System Instructions as Operating Charters, we established why global governance (Mandate) must remain separated from transient task logic (Method). Handing an agent a set of MCP tools without domain context forces the model to guess operational sequences, business thresholds, and cross-system dependencies.

A SKILL.md file provides that missing domain context on demand. Instead of permanently bloating the persistent system_instruction with every edge case across your organization, the orchestration harness dynamically mounts a specific SKILL.md file only when the active workflow requires it.

Under the Hood: How Harnesses Mount Skills via Tool Calls

To write effective SKILL.md files, it helps to see how an orchestration harness actually wires them into the model's context window. Under the hood, dynamic skills are commonly exposed to the LLM as a standard tool call.

At runtime initialization, the harness scans your /skills/ directory, parses only the YAML frontmatter (name and description) from each SKILL.md file, and maps those strings directly into the parameter schema of a lookup tool (such as load_skill). The full Markdown body stays on disk until the model requests it:

┌─────────────────────────────────────────────────────────────────────────┐
│ 1. BUILD / INIT TIME: Harness parses SKILL.md Frontmatter               │
│    name: "inventory-procurement"                                        │
│    description: "Manages parts ordering... Mount when stock is low..."  │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ maps 1:1 into tool schema
┌────────────────────────────────────▼────────────────────────────────────┐
│ 2. RUNTIME TURN 1: Model sees lightweight `load_skill` Tool Definition  │
│    { "name": "load_skill",                                              │
│      "parameters": { "skill_name": { "enum": ["inventory-procurement"], │
│                      "description": "Manages parts ordering..." } } }   │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ model calls load_skill()
┌────────────────────────────────────▼────────────────────────────────────┐
│ 3. RUNTIME TURN 2: Harness injects full SKILL.md body into Context      │
└─────────────────────────────────────────────────────────────────────────┘

Because the frontmatter name and description map 1:1 into the tool definition that the model evaluates on Turn 1, vague frontmatter directly breaks skill routing.

Anatomy of a High-Signal SKILL.md Document

Effective SKILL.md files focus on information architecture and business context rather than conversational fluff. Structure your skill documents around five core elements:

1. Proactive Frontmatter (The Routing Trigger)

Because the harness injects your YAML frontmatter directly into the skill-loader tool description, passive summaries cause the model to under-trigger your skill. Write proactive, condition-first descriptions that explicitly state the user intents and domain keywords required to mount the document:

2. Progressive Disclosure & Reference Pointers

Keep your primary SKILL.md file tight - ideally under 500 lines. When a workflow depends on massive lookup tables, vendor specifications, or lengthy compliance matrices, split those payloads into isolated sub-files (for example, references/reorder-thresholds.md or references/hazmat-codes.md).

Keep the core operational flow in SKILL.md and use clear Markdown pointers so the agent fetches secondary reference files only when a specific conditional branch requires them. (For a deeper look at dynamic mounting and context boundaries, see Progressive AX and SubAgent Delegation).

3. Condition-First Business Rules

While the Operating Charter defines global authority boundaries, a SKILL.md supplies local business logic and institutional context that is not obvious from raw tool schemas. Frame these heuristics using positive, condition-first rules ("When X occurs, apply Y") so the model understands why a rule exists and when to trigger it:

• Vague Heuristic: "Try to check stock levels and use expedited shipping if it looks urgent."
• Condition-First Business Rule: "Default shipping_method to 'standard' to protect freight margins. Upgrade shipping_method to 'expedited' exclusively when check_inventory_stock confirms zero remaining units on the assembly line."

4. Native Markdown Hierarchy (.md)

Verbose markup wrappers like HTML or deeply nested XML inside large context documents burn through your token budget without adding meaning. Write context documents in raw Markdown.

Markdown headings (#, ##, ###), paragraphs, lists, and tables inject native semantic hierarchy straight into the model's attention field. These lightweight typography rules act as high-contrast visual anchors that help the inference engine parse relationships with minimal token overhead.

5. Optional: Input / Output & Sequence Scaffolding

When your MCP tools are self-contained and owned by your team, a clean tool schema often eliminates the need for step-by-step tool sequencing in a SKILL.md. However, in enterprise environments, agents frequently have to bridge separate tools owned by different teams (for example, querying an internal Warehouse service to get a part SKU, then passing that SKU to a third-party ERP service to draft a purchase order).

When you cannot re-architect the underlying APIs to combine those steps, use your SKILL.md to explain the operational sequence, the reason behind each step, and any required output formatting.

Example: Bridging Cross-Team Tools with a SKILL.md

Here is a practical SKILL.md file that bridges an internal warehouse lookup tool and an external procurement system while supplying the unwritten business rules a human operator would normally know:

---
name: inventory-procurement
description: Manages physical parts ordering and supplier outreach. Mount this skill whenever a request mentions replenishing stock shortages, ordering new components, auditing bills-of-materials, or checking supplier lead times.
---

# Skill: Inventory Procurement Workflow

## Business Context & Operational Sequence
Because warehouse inventory and vendor purchasing live in separate backend systems, execute replenishment requests in this order:
1. **Verify Live Stock (`check_inventory_stock`):** Query the warehouse service first to retrieve the canonical `part_id` and confirm actual on-hand quantity before contacting external vendors.
2. **Resolve Approved Vendor (`get_supplier_details`):** Pass the verified `part_id` to the vendor registry to identify the contracted primary supplier and current lead times.
3. **Stage Purchase Request (`stage_purchase_order`):** Submit the order payload using the verified `part_id` and `supplier_id`.

## Domain Rules & Guardrails
* **Contract Compliance:** Require a system-validated `supplier_id` from `get_supplier_details` prior to staging any purchase order so orders only route to approved vendors.
* **Freight Margin Protection:** Apply `standard` shipping by default to control logistics costs. Upgrade to `expedited` shipping exclusively when `check_inventory_stock` returns a quantity of exactly zero.
* **Hazmat Handling:** When ordering parts flagged as `chemical` or `lithium-battery`, read `references/hazmat-compliance.md` and include the required regulatory handling code in the order notes.

## Confirmation Format (Optional Scaffolding)
When presenting a staged order back to the user in chat, use this summary layout:
### Order Confirmation
* **Part Number:** [Insert ID]
* **Approved Supplier:** [Insert Name]
* **Shipping Tier:** [Standard / Expedited + Justification]
* **Status:** [Submitted / Pending Controller Approval]

SKILL.md Authoring Checklist

When authoring or reviewing a SKILL.md file, verify these five criteria:

1. 1:1 Loader Frontmatter: Does the YAML description clearly state the environmental triggers so the harness's skill-loader tool activates reliably?
2. Mandate Separation: Does the file focus strictly on domain context and task execution (Method), leaving global identity and escalation floors to the Operating Charter (Mandate)?
3. Progressive Disclosure: Is the main file under 500 lines, with heavy reference tables or compliance specs linked out to secondary files?
4. Business Context over Brittle Scripts: When bridging multiple tools, does the skill explain why each tool is called in sequence so the model can adapt if a parameter is already present in context?
5. Lightweight Markdown: Is the document structured with clean Markdown headings, lists, and tables rather than token-heavy HTML wrappers?

Next in the AX Series

Once the agent runtime has a persistent Operating Charter and on-demand Interface Page Copy (SKILL.md), the final layer of the 3-Tier AX Triad focuses on designing the interactive capabilities themselves:

• Next Up - Part 4: AX: Structuring MCP Servers as Action Buttons - Applying the Single Capability Principle, designing composable MCP servers, and structuring tool schemas as deterministic form affordances.
• Previous Installment - Part 2: AX: System Instructions as Operating Charters.
• Series Hub - Part 1: AX Fundamentals: Intro to Agent Experience (AX) Design.