Skip to content

Agent Zero AI framework

docs: add system prompt extensions, include original, and specifics file

linuztxadd0546508c3
diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md
index ab192ad6f..ae206a63c 100644
--- a/docs/developer/architecture.md
+++ b/docs/developer/architecture.md
@@ -227,14 +227,27 @@ The `prompts` directory contains various Markdown files that control agent behav
#### Prompt Inheritance with `{{include original}}`
When overriding a prompt, you can extend the original instead of replacing it entirely. Use `{{include original}}` to pull in the default version and add your changes on top:
+**Example:** `agents/developer/prompts/agent.system.main.communication.md`:
```markdown
{{include original}}
-## Additional instructions
-- my custom additions here
+- always explain your reasoning
+- include code snippets in responses
```
-This keeps overrides small and ensures they stay in sync when the default prompt is updated.
+This finds `agent.system.main.communication.md` in the next directory up the hierarchy → includes the default from `prompts/` → appends the additions. Result:
+
+```markdown
+## Communication
+- be concise
+- use markdown formatting
+- ask clarifying questions when unsure
+
+- always explain your reasoning
+- include code snippets in responses
+```
+
+Overrides stay small and automatically inherit any future changes to the default.
#### Dynamic Behavior System
- **Behavior Adjustment**:
diff --git a/docs/developer/extensions.md b/docs/developer/extensions.md
index b87e07f51..a140c107a 100644
--- a/docs/developer/extensions.md
+++ b/docs/developer/extensions.md
@@ -225,9 +225,19 @@ When overriding a prompt file, you can **extend** the original instead of replac
- include code snippets in responses
```
-This includes the default `prompts/agent.system.main.communication.md` first, then appends the developer-specific additions. If the default file changes later, the override automatically inherits the changes.
+This resolves to: find `agent.system.main.communication.md` in the next directory up the hierarchy → finds the default in `prompts/` → includes it. Result:
-Works at any level of the hierarchy — if multiple overrides each use `{{include original}}`, they chain together from highest to lowest priority.
+```markdown
+## Communication
+- be concise
+- use markdown formatting
+- ask clarifying questions when unsure
+
+- always explain your reasoning
+- include code snippets in responses
+```
+
+The override stays small and automatically inherits any future changes to the default file. Works at any level of the hierarchy — if multiple overrides each use `{{include original}}`, they chain together from highest to lowest priority.
##### Agent Specifics File
The default `agent.system.main.md` includes `agent.system.main.specifics.md` — an empty file by default. Subagent profiles can override just this file to add profile-specific instructions without touching role, communication, or other sections.