block Agent Builder
Use this skill when managing Berd agents/personas in Agent Markdown format.
Storage
Agents are UTF-8 Markdown files with YAML frontmatter:
- Global:
~/.agents/agents/<slug>.md - Project-local:
<project>/.agents/agents/<slug>.md
Default to global unless the user asks for project-local. Use platform path APIs or shell-safe home expansion.
Format
Each agent is one .md file:
---
name: Agent Name
description: A concise summary of what this agent does
provider: optional-provider
model: optional-model
avatar: optional-avatar
---
Agent instructions here.
Required frontmatter keys are name and description. The description must be a trimmed, non-empty summary of what the agent does; never create or save an agent with a missing, blank, or placeholder description. If the user has not supplied enough context to write an accurate description, ask for one before saving. Preserve all other frontmatter keys when editing existing agents unless the user explicitly changes them. The Markdown body is the agent’s system prompt/persona instructions.
When writing or generating a description or body, do not assign the agent a gender or gendered pronouns unless the user asked for one. Use it/its or they/them for the agent, matching how it is framed (tool vs. character), or avoid pronouns; people the instructions describe get they/them. Preserve pronouns the user chose, in either direction.
Names and Slugs
For create/rename, require a trimmed name that is non-empty, ≤80 characters, and contains no / or \.
Derive <slug> from the name by lowercasing, replacing each non-ASCII alphanumeric run with -, collapsing/trimming -, truncating to 64 characters, and falling back to agent.
Write <slug>.md; on create collisions, use <slug>-2.md, <slug>-3.md, etc.
Workflow
When editing, read the existing file first. Resolve targets by exact path, frontmatter name, then slug filename. Ask only if multiple matches remain.
Prefer direct file edits over helper scripts. Do not require Python, Node, or another runtime unless the current repo already requires it.
After writing, verify that the file exists, frontmatter is valid, name and description are both trimmed and non-empty, and preserved metadata was not removed. Report the final path.