Skip to content

FAQ · AGENTS AND SKILLS

Agents and skills

Where are my agents and skills stored?

As plain files on your disk. An agent is one Markdown file with YAML front matter at ~/.agents/agents/<slug>.md; a skill is a folder with a SKILL.md inside at ~/.agents/skills/<name>/. Both have a project-local variant under <project>/.agents/. The agents and skills that ship with Berd live in the app's own data directory and are read-only in the app.

Why this comes up: Berd shows agents as cards with faces and skills as a searchable list, so the file system feels like an implementation detail. It is the opposite: the file is the object and the card is a view of it, which matters the first time you back one up, hand-edit one, or wonder why an edit did not stick.

What to do:

  1. In the Skills view, open a skill: the detail shows its source, location and path on disk, with a Show in folder action.
  2. In the Agents view, a card marked File-backed is a Markdown file you can open in any editor. If a profile shows it as review-only, edit the file or ask Agt. Builder to.
  3. Keep ~/.agents/ in whatever backs up your dotfiles. That one tree is your whole cast and method.
  4. Duplicate a built-in agent to change it; the originals cannot be edited.

Why it matters: "Everything under the hood is basically just a file," as Morgan, Berd's design lead, put it on Block's On The Block (September 2026). See Everything is a file and Know where your Berd lives.

My own skill replaced a built-in one — is that a bug?

No. When a personal skill and an app-bundled skill share a name, the personal one wins activation. That precedence is deliberate and written into the skill loader, so your version of berd-help or agent-builder silently takes over from the bundled one.

Why this comes up: People copy a bundled skill to tinker with it, keep the name, and then notice the agent behaving differently everywhere — or do not notice. The app gives no warning when two sources collide by name; the only visible clue is the scope badge on the skill.

What to do:

  1. Decide whether the override is what you want. If you meant to improve the bundled skill for yourself, keep the name; the override is the feature.
  2. If you meant a separate skill, rename yours. Names are lowercase kebab-case, up to sixty-four characters, and must match the folder name.
  3. Check the scope badge — Built in, Personal or Project — whenever an agent stops behaving the way its bundled skill says it should.
  4. A project skill is scoped to that project, so the same trick works per engagement.

Why it matters: This is the mechanism by which your method overrides Block's defaults, without ceremony. It is also how a stale copy of a bundled skill quietly falls behind as Berd updates the original. Name deliberately. See Skills: three sources and one rule.

Agent, skill, project, automation — which is which?

An agent is who you talk to: a saved name, face, model and instructions. A skill is know-how any agent can pick up when the work calls for it. A project is where ongoing work lives: chats grouped around your folders, with context that carries over. An automation is a saved task that runs on a schedule with a run history. Berdy's own rule: an agent remembers how you like to be helped, a skill remembers your context, a project remembers what you are building, an automation remembers your routine.

Why this comes up: All four are ways of making something stick, and all four are files underneath. The first weeks in Berd are mostly the question "agent or skill?" asked in different forms.

What to do:

  1. Something you explain more than twice: a skill.
  2. A way of being helped that you keep steering a chat toward: an agent.
  3. Work with a home folder that outlives one conversation: a project.
  4. Something you do every Monday: an automation — noting that the public release at v0.6.4 is compiled with automations off; see My automation failed.
  5. Unsure: ask Tinker, whose job is exactly this decision.

Why it matters: The wrong container is cheap to fix and expensive to live with; a skill that should have been an agent loads into every conversation whether it fits or not. The mapping to Buzz's words is on Buzz or Berd. See The Berd object model.

Can I make my own Gloopie?

Partly. Berd's avatar library has three bundled collections, and since v0.6.3 a custom gloopie is a first-class citizen of it: reusable across agents and shown first in the Gloopies collection. What the public source does not contain is a way to generate one. At v0.6.4 a custom gloopie enters your library when you import an agent whose card carries one.

Why this comes up: Morgan said on On The Block that Block has an internal make-your-own-Gloopie feature that "might launch externally if we get enough interest." The strings and changelog both mention custom gloopies, so people go looking for the button.

What to do:

  1. Open an agent's profile and use the avatar control; it opens the gallery with the bundled Gloopies, Pollies and Fuzzies.
  2. Import an agent card (PNG or ZIP) from someone who has a custom gloopie; it lands in your library, reusable on any agent.
  3. Do not expect a generator in the public build. If one appears it will be in the changelog first: What changed.
  4. Treat the face as part of the role. Morgan's case for the characters — "something this dumb is never gonna call you dumb" — is that an abstract face takes the edge off technical work.

Why it matters: The face is how you tell agents apart across chats, mentions and delegation activity. The generator is the one part of the story this Coach cannot confirm from source. See Agents are cast, not modes.

Why does the Discover tab ask for a CLI?

Because the Discover tab browses Block's internal skill catalog through a Block-internal tool, sq-agents. It is not a consumer feature: public builds are compiled with skill discovery off and hide the experiment that enables it, and v0.6.3 removed the last exposure from consumer builds. If you see the message, you are on a Block-internal or enterprise distribution.

Why this comes up: The Skills view has an Installed tab and, in some builds, a Discover tab whose empty state says skill discovery needs the sq-agents CLI. Nothing on screen says the catalog is internal.

What to do:

  1. On a public build, expect no Discover tab at all, and no skill-discovery entry in Settings → experiments either.
  2. Get skills the ordinary way: create one manually or with chat from the Skills view, import a .skill.json or .json file, or drop a skill folder into ~/.agents/skills/.
  3. Install Block's published skills from the repository's skills/ folder — at v0.6.4, Buzz Handoff — the same way.
  4. Do not try to install sq-agents; it is not published for outside use.

Why it matters: A message asking for a tool you cannot get reads as a broken install. It is a build boundary: the same source builds a public app and Block's internal one, and this tab belongs to the second. See Skills: three sources and one rule.

Can I give an agent to a colleague?

Yes. Share an agent as a card: PNG for a look, Markdown for the editable text, or ZIP when it must survive Slack with its instructions and settings intact. Your colleague imports it by dragging the file onto the Agents view or through the import dialog, which takes ZIP, PNG, .persona.md or JSON.

Why this comes up: The card looks like a picture. People send the PNG, the recipient gets a picture, and nobody is sure whether the instructions travelled. They do, but chat apps re-encode images, which is why the ZIP exists.

What to do:

  1. Send ZIP through Slack or anything that touches images; PNG or Markdown otherwise.
  2. Warn the recipient that the agent's provider and model may not exist on their machine. The import dialog says so and offers Berd's defaults; nothing runs until both are set.
  3. A card containing memory is imported without it; Berd says so at import.
  4. Expect the recipient to edit. Morgan on On The Block: taking someone else's agent, there will be things you do not love about it.
  5. For a whole cast, share the files in ~/.agents/agents/ directly.

Why it matters: This is how a method spreads inside a practice, and it is the only route to a colleague, because Berd has no notion of other people. The card is a file, and the file is the agent. See Share, import and keep your agents.

Which built-in agent should I start with?

Berdy, if Berd itself is new to you: its job is to help you get to know the app while the app gets to know you. Generalist for the first piece of real work: a plain, flexible starter with one sentence of instructions, and a good first reader when you do not yet know which specialist you need. Go straight to a specialist only when the job is obvious.

Why this comes up: Ten agents on a first run is a lot of faces. Onboarding may also offer four recommended agents by work type — Planner, Reviewer, Automator, Explorer — and whether those are the same files as the bundled starters is not something the sources settle.

What to do:

  1. Tell Berdy what you are trying to get done. Its instructions are to get you one real win before introducing anything.
  2. For work: Generalist, then hand off when the nature of the work changes, not the topic.
  3. When the job is obvious, cast for it: Wildcard to widen, Choosey to decide, Pushback to stress-test, Copycat for your voice, Agt. Builder or Tinker to build.
  4. Read the cast before trusting an output shape: Berd's built-in agents and How the agents hand off.

Why it matters: One agent for small tasks is the rule. Handing off costs context, and the crafted personas refuse things on purpose, so the wrong one produces a polite non-answer rather than a bad one. See Cast the right built-in agent.

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