Found something good?

Harness 系列文章之 5，小小的 markdown 文件，却可以改变 Coding Agent 的世界状态。

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

现代 coding agent 里，一个很有意思的现象是：普通 markdown 文件可以改变 agent behavior。

加一个 AGENTS.md，Agent 开始遵守 repo-specific rules。

加一个 SKILL.md，Agent 在某类 task 上突然更稳定。

Markdown file 只是可见部分。

真正有趣的是 Harness 对这种机制的设计：

The Naive Markdown Dump

按照习惯，如果我们从一个从 tiny agent 看 markdown：

这看起来合理，因为 rules，docs，plans，procedures 都经常写在 markdown 里。

但 raw markdown dumping 有代价：

Model 得到了更多 text，但 task 得到的有用的 instruction 更少。

所以，

.md 应该通过 Harness route 进入 context，不能直接倒进 prompt。

Two Files, Two Jobs

这里，我们可以一起看两个常用 markdown files，AGENTS.md 以及 SKILLS.md

它们都是 markdown, 但进入 prompt 的方式不一样。

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

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

Why AGENTS.md Works

AGENTS.md 有效，是因为 Harness 把它当成 workspace instruction context。

它是 project guidance，应该在 model 开始操作 repo 前可见。

例如我自己的 Dongxi Agent 主要任务是要根据每天与 coding agent的交互中，总结学习经验。

那么，在 DongXi 这个 workspace 里，AGENTS.md 要求：做 DongXi Agent 或 coding-agent harness learning 时，要保持 learning artifact current。

这一个文件会改变整个 session 的行为：

Model 仍然负责 writing 和 reasoning。

但 Harness 在 turn 开始前插入了稳定的 project rule。

这就是 AGENTS.md 强的地方：

How AGENTS.md Works

这样 prompt 可以保持一致，又不会把 project rules 变成 noisy chat history。

Where Agents.md Enters The Agent Turn

AGENTS.md 在 model turn 组装前加载。

它进入 stable workspace instruction context，和 project rules、local operating constraints 放在一起。transcript 记录发生了什么；AGENTS.md 约束接下来该怎么做。

Why SKILL.md Works

SKILL.md 有效，原因不同。

它能提升某类 task 的表现，是因为它在正确时机给 model 一个聚焦的 procedure。

没有 skill 时，model 可能懂一般领域，但会漏掉 local workflow。

有 skill 时，Harness 可以提供：

这比一句 vague prompt 强得多：

这个文件会提升 performance，因为它把 fuzzy ability 变成 repeatable procedure。

How SKILL.md Works

好的 Harness 不会把所有 skills 都塞进 default prompt。

它使用 progressive disclosure。

在 startup 或 capability refresh 时，Harness 扫描 skill folders：

Model 可以看到这个 skill 存在。

用户也可以通过 /skills 之类的 local command 看到它。

完整 body 在 task 需要时才进入 context。

Where Skills.md Enters The Agent Turn

SKILL.md 先以 capability metadata 出现，task invoke 之后才加载 body。

它进入 task procedure context：steps、tool expectations、checks、output shape。这个 context 只服务当前 workflow，不扩散成 always-on workspace policy。

小小的 markdown，没有改变 model weights。

却改变了该 task 里的 harness-managed context、tools 和 workflow。

合适使用这些 markdown，是 coding agent 最关心的问题。

而：

在恰当的时机，把不同的 markdown 文件加载进context，就是 harness 应该做的事情。