SUPPORTING KNOWLEDGE · 0006
Skills: three sources and one precedence rule¶
A skill is the same thing in Berd as in Buzz: written instructions, saved as a file, that an agent picks up when the work calls for it. The Buzz Guide's What a skill is explains the idea; this page covers only what Berd adds, which is where skills come from and which one wins.
In Berd a skill is a folder with a SKILL.md (frontmatter plus instructions) that is matched against your request and loaded into the session when relevant. The description in the frontmatter is the trigger surface: it has to say both what the skill does and when to use it, with concrete phrases, and it is what decides whether the skill fires.
Skills come from three sources, and the source decides who owns the skill and what happens on a name clash:
| Source | Where it lives | Who owns it |
|---|---|---|
| App-bundled | the app-data skills directory; read-only in the interface | Berd. Five ship in v0.6.4: berd-help, agent-builder, skill-builder, berd-monitor, berd-orchestrator |
| Personal | ~/.agents/skills/<skill-name>/ |
You; available to every session |
| Project | <project>/.agents/skills/<skill-name>/ |
The project; stored in its folder |
Why it matters to you¶
The one precedence rule: when a personal skill and a bundled skill share a name, the personal one wins. Berd's help calls this deliberate, and tells the help agent that a user reporting their own version of a bundled skill taking over is not reporting a bug. The rule is powerful and silent. Name a skill berd-help and every Berd question in every session is answered by your file instead of Block's.
The split also decides reach. A personal skill is available in all sessions. A project skill is scoped to its project folder, which is what you want for one engagement's house rules and not what you want for your own method.
A fourth kind is not a source in the app: Berd publishes portable skills under skills/ in its repository (the first is buzz-handoff). They are installed independently, separate from the five bundled ones, and an agent that has not been given one does not know it exists.
How to apply it¶
Write down the thing you explain more than twice. That is the test, in both products.
Pick the home before you write. The skill builder's own rule is: global unless you are clearly working in a project directory, and ask when a project is active and the intent is unclear. "This repo", "only here" means project; "all projects", "always available" means personal.
Name it carefully. Lowercase, a-z, 0-9 and -, at most 64 characters, no leading or trailing hyphen; the folder name and the name in the frontmatter must match. And do not reuse a bundled name unless you mean to replace it.
Test the trigger: two requests that should fire it, two adjacent ones that should not. Under-triggering means the description is too vague; over-triggering means it needs a line saying what it is not for.
The Discover tab that browses Block's internal skill catalog is not a consumer feature; v0.6.3 removed it from public builds, and at v0.6.4 the public release compiles it off (VITE_SKILL_DISCOVERY=0), so the tab does not render at all and the Skills view shows installed skills only. A message asking for the sq-agents CLI means you are on a distribution that enables it and have the experiment switched on without the CLI.
If you ignore this¶
A personal skill with a bundled name quietly replaces it, and Berd's help starts giving your answers, or Agt. Builder starts following your half-finished format, with no error anywhere. Or a house-rules skill saved as personal follows you into the next client's project.
Examples¶
Three shelves in the same room: the manufacturer's manuals, your own binders, and the binder that stays with this job. When two binders have the same title, yours is the one that gets opened.
A retired-words skill, personal, whose description says: "Check a draft against the practice's retired-word list. Use when asked to review, polish or house-style a text." It fires for every review in every session, and never for a build.
Copying agent-builder into ~/.agents/skills/agent-builder/ to "tweak it a little". From that moment the bundled one never loads, and the next release's improvements to it never reach you.
Do it: Write a skill and decide where it lives
Last checked: Berd v0.6.4, 2026-09-11.
Reference¶
- block/berd — distro/skills/berd-help/references/skills.md — the three sources and the precedence rule
- block/berd — distro/skills/skill-builder/SKILL.md — storage decision, naming, trigger testing
- block/berd — skills/README.md — published skills, separate from bundled ones
- block/berd — src/shared/i18n/locales/en/skills.json — scope labels and the
sq-agentsmessage - block/berd — CHANGELOG.md — v0.6.3, public builds
- block/berd — .github/workflows/release.yml —
VITE_SKILL_DISCOVERY=0in the public release - What a skill is — the Buzz Guide article
- Verified
- Berd v0.6.4 · 2026-09-11