Schemas Up Front
VFS.md spells out each file's shape, so agents can plan the task and how they will reach its data before their first command.
VFS.md
A simple, open format for guiding agents through a virtual filesystem.
Think of VFS.md as a README for the filesystem your agent works in: it describes the data and how it's shaped.
---
name: <name>
description: <description>
---
# Virtual Filesystem
<What this filesystem holds and how to read it.>
| Path | Description |
|---|---|
| `/<path>` | <Service>, read-only; change it with the `<cli>` CLI. |
## `.<kind>.json` format
```json
{"id": "...", "title": "...", "<items>": [...]}
```| name | <name> |
|---|---|
| description | <description> |
Virtual Filesystem
<What this filesystem holds and how to read it.>
| Path | Description |
|---|---|
/<path> | <Service>, read-only; change it with the <cli> CLI. |
.<kind>.json format
{"id": "...", "title": "...", "<items>": [...]}An Agent's Guide to the Virtual Filesystem.
VFS.md tells agents how the filesystem is laid out and how its special files are shaped, so they can go straight to the Unix-like tools they already know, like ls, grep and jq.
Progressive Discovery
Agents read each VFS.md's metadata first, its name and description, and load the rest or a deeper one only as needed.
Works with Any Agent
It is plain Markdown, which LLMs are well trained to read, and it lives in the virtual filesystem, so agents need no special SDK or server.
Add VFS.md. Point Your Agent to It.
- 01
Add VFS.md to the Virtual Filesystem
In the agent's instructions, say where it lives.
- 02
Pair It with SKILL.md
VFS.md describes the data and how it's shaped. SKILL.md describes the commands that act on it. The agent gets both.
- 03
Nest VFS.md Where Detail Changes
A folder can carry its own VFS.md, so the agent loads format details only when it goes there.
- 04
Let the Agent Work in a Terminal-Like Environment
It reads VFS.md first, then works with shell tools, CLIs and scripts, in a real terminal or a virtual one. Results stay as files in the virtual filesystem it can check and reuse.
/├── VFS.md # data and formats├── SKILL.md # commands└── <path>/ ├── VFS.md # this folder's formats └── <title>.<kind>.json
A Small Format, Deliberately.
What happens when two VFS.md files overlap?
Say in the agent's instructions which one wins, for example the VFS.md closest to the path in use.
Can it replace MCP?
Yes, for agents in a terminal-like environment. Instead of loading every tool schema up front, the agent reads files and chains shell tools and CLIs, using fewer tokens with better accuracy. MCP servers can still serve the data behind the virtual filesystem.