Customization
pbi-agent can be customized from files in the current workspace. These files let you change the system prompt, add project-specific rules, install reusable skills and commands, define specialist sub-agents, and expose project-local MCP tools without changing global provider settings.
Customization modules
| Module | Workspace path | Use it for |
|---|---|---|
| Custom system prompt | INSTRUCTIONS.md | Replace the built-in system prompt for this workspace. |
| Project rules | AGENTS.md | Add repository conventions on top of the active system prompt. |
| Project skills | .agents/skills/<skill>/SKILL.md | Advertise task-specific skill instructions that the model can load on demand. |
| Project commands | .agents/commands/*.md | Add reusable slash-command prompt presets. |
| Project sub-agents | .agents/agents/*.md | Define specialist child agents for the sub_agent tool. |
| Workspace reload | /reload | Refresh prompt files and project catalogs in an active session. |
| MCP servers | .agents/mcp.json | Expose project-local MCP tools to the model. |
| File constraints | prompt files | Size, encoding, empty-file, and unreadable-file behavior. |
Prompt file composition
INSTRUCTIONS.md and AGENTS.md compose cleanly:
| Files present | System prompt |
|---|---|
| Neither | Built-in default prompt |
AGENTS.md only | Built-in default prompt + <project_rules> |
INSTRUCTIONS.md only | Your custom prompt |
| Both | Your custom prompt + <project_rules> |
If project skill files are present, their catalog is appended after the active prompt content in all of the cases above, including custom INSTRUCTIONS.md.
Project commands and sub-agents can further scope that composition with frontmatter fields. Commands may declare skills and sub_agents; sub-agents may declare skills, reusable commands, and nested sub_agents. These comma-separated lists let one component expose only the project skills, delegates, and command prompt blocks it needs.
When changes take effect
New one-shot runs and newly created sessions read customization files when their provider starts. A live session keeps its provider open between turns, so edits to workspace files are not applied until you run /reload or restart the session.