docs: Add comprehensive guide on customizing system prompts with AgentContext

sdk/guides/skill.mdx

@@ -161,16 +161,59 @@ Skill(
 
 ### Message Suffixes for `AgentContext`
 
-Add consistent prefixes or suffixes to system and user messages:
+Append custom instructions to the system prompt or user messages via `AgentContext`:
 
-```python highlight={3-4}
+```python
 agent_context = AgentContext(
-    skills=[...],
-    system_message_suffix="Always finish your response with the word 'yay!'",
-    user_message_suffix="The first character of your response should be 'I'",
+    system_message_suffix="""
+<REPOSITORY_INFO>
+Repository: my-project
+Branch: feature/new-api
+</REPOSITORY_INFO>
+    """.strip(),
+    user_message_suffix="Remember to explain your reasoning."
 )
 ```
 
+- **`system_message_suffix`**: Appended to system prompt (always active, combined with repo skills)
+- **`user_message_suffix`**: Appended to each user message
+
+### Replacing the Entire System Prompt
+
+For complete control, provide a custom Jinja2 template via the `Agent` class:
+
+```python
+from openhands.sdk import Agent
+
+agent = Agent(
+    llm=llm,
+    tools=tools,
+    system_prompt_filename="/path/to/custom_system_prompt.j2",  # Absolute path
+    system_prompt_kwargs={"cli_mode": True, "repo_name": "my-project"}
+)
+```
+
+**Custom template example** (`custom_system_prompt.j2`):
+
+```jinja2
+You are a helpful coding assistant for {{ repo_name }}.
+
+{% if cli_mode %}
+You are running in CLI mode. Keep responses concise.
+{% endif %}
+
+Follow these guidelines:
+- Write clean, well-documented code
+- Consider edge cases and error handling
+- Suggest tests when appropriate
+```
+
+**Key points:**
+- Use relative filenames (e.g., `"system_prompt.j2"`) to load from the agent's prompts directory
+- Use absolute paths (e.g., `"/path/to/prompt.j2"`) to load from any location
+- Pass variables to the template via `system_prompt_kwargs`
+- The `system_message_suffix` from `AgentContext` is automatically appended after your custom prompt
+
 ## Next Steps
 
 - **[Custom Tools](/sdk/guides/custom-tools)** - Create specialized tools