Markdown Is the Context API for an Agent OS
Markdown in autonomous systems is more than a format for keeping records; it serves as a high-level context routing protocol and behavioral bus.
In the Agent era, I treat Markdown as a Context API connecting large models to their external environments. Seeing it strictly as a formatting syntax for human readers falls short. *Markdown Is A Context Interface* puts Markdown at the level of a system interface. I agree with that judgment; simply praising the format's universality misses this layer.
Large language models have neither long-term engineering memory nor a direct grasp of the boundary rules governing a codebase or knowledge system. An Agent can act like a well-trained collaborator because an external runtime (Harness) routes Markdown specifications, workflows, and reference materials from the file system into the model's active context at the right moment based on the task goal.
Two plain text files can both end in .md, yet differences in their system paths, naming conventions, and loading mechanisms give them very different behavioral semantics and execution permissions.
Why Dumping Everything into the Context Often Causes Problems
Looking at how people build Agents in practice, I keep seeing the same approach: stuffing every available document, old note, and code file into the prompt all at once. This "throw it all in as long as the context window is big enough" strategy easily causes five system-level problems:
- Rule conflicts: Descriptions in outdated documents or drafts easily clash semantically with the user's latest intent, leaving the model unsure which to follow.
- Context pollution and privilege escalation: Sample commands, scraped web snippets, or malicious text inside external materials can be misidentified by the model as system instructions, triggering indirect prompt injection.
- Attention dilution: Long background text consumes a finite attention budget, crowding out critical tool execution outputs, terminal error messages, and the latest constraints.
- Misaligned scopes: When project-level baseline rules, task-level operational steps, and pure reference materials are flattened and mixed together, the system cannot establish a clear priority arbitration mechanism.
- Failure to build reusable assets: A massive, ad-hoc prompt only solves a one-off problem and fails to build up structured capabilities for ongoing engineering collaboration.
These issues convinced me that a reliable Agent system needs a clear Context Routing Protocol. Stuffing text into a window does not solve the problem of how information should be scheduled.
A Layered Context Contract: From Constitution to Evidence
For a system to schedule information accurately, my view is that we need to draw clear responsibility boundaries and scopes for Markdown at the file system level:
1. Workspace Constitution: AGENTS.md
AGENTS.md sits at the foundational rule layer, defining the behavioral guidelines an Agent must follow by default within a workspace.
- What I believe must be consolidated here: Core project goals and architectural constraints, directory structure semantics, code and file naming conventions, permission red lines for high-risk operations (such as prohibiting unconfirmed modifications to production environments), and unified automated verification standards.
- What should be excluded: Temporary progress on specific one-off tasks, excerpts from individual papers, unverified ideas, and daily status updates that quickly go stale.
- How I position it:
AGENTS.mdshould be as stable and restrained as a workspace constitution, not written like a casual activity log.
2. Task-Level Workflow Specification: SKILL.md
SKILL.md sits at the execution workflow layer, specifying the standard steps and acceptance criteria when facing a specific class of tasks.
- What I believe must be consolidated here: Task trigger conditions, prerequisite dependency checks, recommended toolchain invocation sequences, known pitfalls and workarounds, clear quantitative verification methods, and formatting conventions for deliverables.
- What should be excluded: Long macro-level background manifestos, unrelated slogans of principle, and temporary parameters valid only in a single scenario.
- My understanding: A solid Skill should substantially reduce communication overhead the next time a similar task comes up, helping the Agent "guess less, ask less, and drift less."
3. Execution Scaffolding: Task Plans and Workbench Documents (Plan)
These documents support step-by-step progress on medium- to long-horizon tasks, recording current milestone decisions, to-do checklists, and intermediate states. Their lifecycle is bound to a single task; once the task is archived, they remain as an audit trail.
4. Navigation Map: Directories and Indexes (Index)
This serves as a wayfinding pointer when an Agent explores unfamiliar territory. I think index files should stay brief and maintain high information density, taking on only the guiding function of "pointing out what material lives where" without repeating lengthy body text.
5. Fact and Evidence Repository: Reference Materials and Archives (Evidence)
This layer holds external research, web snapshots, technical whitepapers, and raw data. Within the semantic system, I require this layer to be treated strictly as Data (data awaiting analysis). Even if the content looks authoritative and neatly formatted, it must not be granted Instruction (execution instruction) privileges without confirmation from a human or a higher-level system.
Strict Isolation Across Four Semantic Forms
Throughout the runtime lifecycle, I believe the Harness must constantly enforce isolation across four semantic boundaries:
[Instruction] 用户当前明确指令、AGENTS.md 规则、受控加载的 Skill
↓ 控制并调度
[Procedure] 项目公认的 Checklist、测试脚本、构建工具
↓ 作用并分析
[Evidence] 外部文章、抓取日志、错误输出、数据库记录（仅作纯数据）
↓ 沉淀为
[Draft] 中间草稿、探索分支、待验证结果To me, this isolation mechanism is the core defense line of an Agent system: external evidence cannot autonomously escalate its privileges to become system instructions, and temporary drafts cannot be merged directly into the main branch before passing verification.
Letting the File System Carry Engineering Semantics
Developers, the file system, and the Agent Harness can give Markdown clear engineering semantics through path conventions, naming standards, and loading timing. These conventions explain Markdown's role in the system far better than how many heading levels it has or whether it supports list syntax.
Once every Markdown document has a defined place in the context system, formerly static and scattered notes can work together across the file system. I think of this way of organizing files, with clear responsibilities and security boundaries, as a personal Agent operating system.