Skip to content

BERD TASK · 0011 · BUILD YOUR CAST

Write a skill and decide where it lives

A skill is a folder with a SKILL.md in it: instructions an agent loads when a request matches the skill's description. Any agent can use it. Two decisions on this page outlast the writing — where the folder lives, and what the description promises — and one rule can silently change an agent's behaviour.

Steps at a glance

  1. Write down the thing you explain more than twice
  2. Choose the shape
  3. Choose the home: personal or project
  4. Write the description as the trigger surface
  5. Create with chat or by hand; the builder warns before discarding
  6. Test the trigger with four requests
  7. Know the precedence rule

1. Write down the thing you explain more than twice

That is the whole test. Berdy's instructions say it the same way: when someone explains the same thing twice, suggest capturing it as a skill instead of re-typing it forever. The house rules for a summary, the terms your practice has retired, the way you cite a source — each is a paragraph you have typed into a chat many times. A skill is that paragraph, saved once, loaded whenever the work calls for it.

If the thing you keep explaining is who the agent should be rather than how a task is done, that is an agent — see Build an agent of your own.

2. Choose the shape

The minimum is one file, SKILL.md, with name and description in its frontmatter and the instructions below. Three optional folders sit beside it and, in the skill-builder's words, must earn their keep: scripts/ for code that would otherwise be rewritten every time, references/ for detail loaded only when needed, assets/ for templates or files used in outputs. No README, no changelog inside the folder. Keep the critical instruction near the top and move length into references/.

3. Choose the home: personal or project

Two places, and the folder name must match the skill name in both:

  • Personal — ~/.agents/skills/<skill-name>/SKILL.md. Available to every session, every project. Your method.
  • Project — <project>/.agents/skills/<skill-name>/SKILL.md. Scoped to that project. One engagement's conventions.

The new-skill dialog puts the choice on a Save to control with the two hints spelled out — Available to all sessions against Stored in the project folder — and shows the resulting path on disk. The skill-builder defaults to personal unless you are clearly working in a project, and asks when it cannot tell. A third kind, built in, ships with Berd and is read-only.

[SCREENSHOT: T11-01 — new skill dialog with Save to]

4. Write the description as the trigger surface

The description is not a label. It is what the agent matches your request against, so it has to say both what the skill does and when to use it, with the phrases a person would actually type — the dialog's placeholder is exactly that. Under-triggering: make the description more concrete. Over-triggering: narrow it and add what it is not for.

5. Create with chat or by hand; the builder warns before discarding

Two routes from the Skills view. Create with chat hands the job to the skill-builder skill, which asks for two or three example requests if the goal is vague, decides the shape, writes the folder, validates it and reports the path. Create manually is a form: name, description, instructions, save-to. Names are 1–64 lowercase letters, numbers or hyphens, not starting or ending with a hyphen; a clash with an existing name is refused rather than overwritten. Since v0.6.3 leaving the form with unsaved edits asks Discard unsaved changes? first.

A Discover tab also exists in the strings, asking for the sq-agents CLI. It is Block-internal: v0.6.3 removed Skill Discovery from public builds, and at v0.6.4 the public release compiles it off (VITE_SKILL_DISCOVERY=0), which hides the tab and its experiments entry entirely — the Skills view shows installed skills only. In distributions that enable it, the tab is an opt-in experiment. Skills from outside arrive as files, or as .skill.json through the import action.

[SCREENSHOT: T11-03 — discard warning]

6. Test the trigger with four requests

Before you trust it: two requests that should fire the skill — the obvious one and a paraphrase — and two that should not — an unrelated task, and an adjacent one just outside its scope. Ask the agent what it loaded, or give it a task only the skill can shape and read the output. A skill that does not fire produces no error; it produces a competent answer done someone else's way.

7. Know the precedence rule

Skills come from three sources — built in, personal, project — and when a personal skill has the same name as a built-in one, the personal one wins. Berd's help is explicit that this is deliberate, not a bug. It is how you replace berd-help with your own version; it is also how you do that by accident, with no message. Check the scope badges in the skills list, and do not reuse a bundled name unless replacement is what you want.

[SCREENSHOT: T11-02 — skills list with scope badges]

Practitioner decision

Two documented homes. Personal for everything: one folder to back up, every skill in every chat, nothing left behind when a project is archived — and every client's conventions visible to every other client's chats. Project-local for engagement-specific skills, personal for method: the practice's way of working travels everywhere, a client's vocabulary and templates stay inside that project's folder and leave with it — at the cost of two trees to back up. Recommendation: the split. Method is personal; anything naming a client is project-local. The standard should also fix a naming prefix that keeps personal skills clear of bundled names. Practitioner writes the standard here.

Last checked: Berd v0.6.4, 2026-09-11 — read from source and release notes, not yet tested in the app.

Learn more

Reference

Moment
apply
Takes
20 min
Steps
7
Verified
Berd v0.6.4 · 2026-09-11 · source-read
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