Markdown Is A Context Interface

Harness Series — Part 5. A tiny markdown file can change the world state of a Coding Agent.

.md file works when the harness knows what kind of context it is.

A fascinating phenomenon in modern coding agents: an ordinary markdown file can alter agent behavior.

Add an AGENTS.md — the Agent starts following repo-specific rules.

Add a SKILL.md — the Agent becomes more stable on a certain class of tasks.

The markdown file is only the visible part.

What’s truly interesting is the Harness’ design behind this mechanism:

The Naive Markdown Dump

By habit, if we look at markdown from a tiny agent’s perspective:

This seems reasonable, because rules, docs, plans, and procedures are often written in markdown.

But a raw markdown dump comes with costs:

• Old notes compete with current instructions
• Long docs squeeze out recent tool results
• Drafts might be mistaken for rules
• General project guidance can overshadow narrow task procedures

The model gets more text, but the task gets fewer useful instructions.

Therefore,

.md should enter context through a Harness route, not be dumped directly into the prompt.

Two Files, Two Jobs

Here, let’s look together at two common markdown files: AGENTS.md and SKILLS.md.

Both are markdown, but they enter the prompt differently.

AGENTS.md : In this workspace, behave like this.

SKILL.md : For this kind of task, use this procedure.

Why AGENTS.md Works

AGENTS.md works because the Harness treats it as a workspace instruction context.

It is project guidance that should be visible to the model before it starts operating on the repo.

For example, my own DongXi Agent’s main task is to summarize learning experiences from daily interactions with the coding agent.

So, in the DongXi workspace, AGENTS.md requires: When working on the DongXi Agent or coding-agent harness learning, keep the learning artifact current.

This single file changes the behavior of the entire session:

The model is still responsible for writing and reasoning.

But the Harness injects a stable project rule before the turn begins.

That’s the power of AGENTS.md:

• It is discovered from the workspace
• It is scoped by project or directory
• It enters the stable instruction layer
• It persists across multiple tasks
• It saves the user from repeating local conventions in every prompt

How AGENTS.md Works

• The Harness should know which directory each rule applies to.
• Nested workspaces may have narrower rules.
• These rules should be treated as instruction context, while still being subordinate to system and developer policy.
• The file content should not be blindly copied into every visible transcript message.
• It belongs in the stable context layer.

This keeps the prompt consistent without turning project rules into noisy chat history.

Where AGENTS.md Enters the Agent Turn

AGENTS.md is loaded before the model turn is assembled.

It enters the stable workspace instruction context, alongside project rules and local operating constraints. The transcript records what happened; AGENTS.md dictates what to do next.

Why SKILL.md Works

SKILL.md works for a different reason.

It improves performance on a specific class of tasks because it gives the model a focused procedure at the right moment.

Without a skill, the model may understand the general domain but miss the local workflow.

With a skill, the Harness can provide:

• When to use this workflow
• Which files or artifacts are important
• Which tools are allowed or expected
• What steps should be followed
• What checks prove the work is done
• What output format the user expects

This is far more powerful than a vague prompt:

“Do this better.”

This file boosts performance because it turns a fuzzy ability into a repeatable procedure.

How SKILL.md Works

A good Harness does not cram all skills into the default prompt.

It uses progressive disclosure.

At startup or capability refresh, the Harness scans skill folders:

The model can see that a skill exists.

The user can also see it via a local command like /skills.

The full body enters the context only when the task requires it.

Where SKILL.md Enters the Agent Turn

SKILL.md first appears as capability metadata; the body is loaded only after the task is invoked.

It enters the task procedure context: steps, tool expectations, checks, output shape. This context serves only the current workflow — it does not bleed into an always-on workspace policy.

A tiny markdown file. It doesn’t change the model weights.

But it changes the harness-managed context, tools, and workflow for that task.

Using these markdown files appropriately is the central concern for coding agents.

And:

Loading different markdown files into context at the right time is what the harness should do.