> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# VFS.md and SKILL.md

> Two Markdown files that tell an agent what is mounted and which commands it can run.

A workspace describes itself to an agent in two Markdown files, in the
[VFS.md](https://agentvfs.org/vfs) format:

* **VFS.md**: every mounted path, its layout and which Unix commands work
  there.
* **SKILL.md**: the registered CLIs, with each one's help.

Both are built from the live workspace and follow the session's
[profile](https://docs.mirage.strukto.ai/home/policy/overview.md): a command the profile denies, or a path it
hides, is never mentioned. Each VFS page shows its VFS.md, such as
[Gmail](https://docs.mirage.strukto.ai/python/vfs/gmail.md).

## Get them

**Python**

```python theme={null}
vfs_md = await ws.vfs_md()
skill_md = await ws.skill_md(session_id="agent")
preview = await ws.vfs_md(profile="reader")
await ws.vfs_md("/VFS.md")
```

**TypeScript**

```typescript theme={null}
const vfsMd = await ws.vfsMd()
const skillMd = await ws.skillMd(undefined, { sessionId: 'agent' })
const preview = await ws.vfsMd(undefined, { profile: 'reader' })
await ws.vfsMd('/VFS.md')
```

**HTTP**

```bash theme={null}
curl http://127.0.0.1:8765/v1/workspaces/demo/vfs-md \
  -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN"

curl http://127.0.0.1:8765/v1/workspaces/demo/sessions/agent/skill-md \
  -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN"

curl -X PUT http://127.0.0.1:8765/v1/workspaces/demo/vfs-md \
  -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"path":"/VFS.md"}'
```

**CLI**

```bash theme={null}
mirage workspace vfs-md demo
mirage workspace skill-md demo --session agent
mirage workspace vfs-md demo --path /VFS.md
```

* **No session or profile**: what the workspace's default profile allows.
* **A session**: what that session's agent sees.
* **A profile**: a preview of what a session with that profile would see.
* **A path**: the file appears in the workspace, read-only and always
  current, so the agent runs `cat /VFS.md`. Each session reads its own
  version.

## What VFS.md says about each path

* **Mode**: `read`, `write` or `exec`. A path whose VFS cannot change files
  shows `read`, whatever mode it is mounted with.
* **Layout**: how its files are organized and what they hold, for a VFS that
  has one. A VFS sets it with [`vfs_md`](https://docs.mirage.strukto.ai/home/setup/custom-vfs#attributes).
* **Supported commands**: the Unix commands that work there, which of them
  use the service's own search, and the path's own commands, such as
  `chroma-query` on Chroma.
* **Limitations**: where it differs from a local filesystem, such as being
  read only, or the [`walk_limit`](https://docs.mirage.strukto.ai/home/integration/search#walk_limit) on
  large folders.

Which commands can change files depends on the methods the VFS implements;
[Custom VFS](https://docs.mirage.strukto.ai/home/setup/custom-vfs.md) lists them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.