Skip to content

SUPPORTING KNOWLEDGE · 0004

Everything is a file

Morgan, Berd's design lead, on Block's On The Block (September 2026), put the whole design idea in one line: everything under the hood is basically just a file. Agents and skills are markdown. Berd's job was to take those primitives, attach a mental model, and show them in an interface instead of a secret folder in Finder.

The interface is the front. The files are the truth. An agent card in the gallery carries a File-backed label because that is what it is: a markdown file with YAML frontmatter at ~/.agents/agents/<slug>.md, or <project>/.agents/agents/<slug>.md for a project-local one. A skill is a folder at ~/.agents/skills/<skill-name>/ (or <project>/.agents/skills/<skill-name>/) with a required SKILL.md and optional scripts/, references/ and assets/. What Berdy remembers about you lives in plain text under ~/.config/goose/: a global hints file, AGENTS.md, for standing rules, and a memory folder for facts.

Berd's bundled builder skills spell out the formats. An agent file needs name and description in its frontmatter, may carry provider, model and avatar, and the markdown body is the agent's instructions. A skill's SKILL.md needs name and description, the folder name must match the name, and the name is lowercase kebab-case, at most 64 characters.

Why it matters to you

Because the file is the truth, three things are yours that would otherwise be the app's.

You can read and edit anything by hand. Open the agent file in any editor. Fix a typo in a skill without a chat. Read exactly what has been remembered about you. The builder skills say to read the existing file before editing and to preserve frontmatter keys you did not mean to change; hold yourself to the same rule.

Backup is copying folders. ~/.agents and ~/.config/goose hold your cast, your method and your memory. They travel with your dotfiles. What does not have a documented path is the session store: no source names where conversations are kept on disk or whether that store is portable, so sessions are exported one at a time from the app. See What stays on your laptop.

Sharing is sending a file. An agent leaves as a card (PNG), as its markdown, or as a ZIP that survives Slack intact. An imported agent is a file you will edit; Morgan's expectation is that someone else's agent always has things you do not love about it.

How to apply it

Learn the two trees. ~/.agents/ is yours across every project; a project's own .agents/ folder is scoped to that engagement. When you build something, the first decision is which tree it belongs in.

Let the app write files for you, then check the result on disk. The skills list shows a path on disk for each skill; the agent builder reports the final path when it saves. Knowing the path is what lets you back it up, version it, or hand it over.

Keep one skill or one agent to one purpose, so the file stays readable. A 1,600-word persona file (Agt. Builder's is that long) is fine; a file that does three jobs is a file nobody will maintain.

If you ignore this

You treat the gallery as the only view, lose the laptop, and find that the cast you spent weeks refining existed nowhere else. Or you hand-edit a skill's folder name without changing the name in its frontmatter, and the skill stops loading with no error.

Examples

A recipe box. The app is the pretty index on the lid; the cards inside are what the cook reads. Copy the box and you have copied the cooking.

A consultant keeps ~/.agents/ in a private git repository. Each new engagement gets a .agents/skills/ folder in its project directory holding only the house rules that apply there; the repository never sees client material.

Assuming a whole Berd install can be moved by exporting from the app. Agents, skills, hints and memory are files you can copy; the conversation store has no documented location and no whole-install export.

Do it: Know where your Berd lives, and back it up

Last checked: Berd v0.6.4, 2026-09-11.

Reference

Verified
Berd v0.6.4 · 2026-09-11
NEVER BESTUCK AGAINCLICK ME

Guide built with Berd, Claude and Codex · verified against Berd v0.6.4, 2026-09-11 · read from source, not yet tested in the app · Buzz Guide · About · not affiliated with Block