docs: customizable prompt templates (#6908)

documentation/docs/guides/config-files.md

@@ -19,6 +19,7 @@ The configuration files allow you to set default behaviors, configure language m
 - **permission.yaml** - Tool permission levels configured via `goose configure`
 - **secrets.yaml** - API keys and secrets (only when keyring is disabled)
 - **permissions/tool_permissions.json** - Runtime permission decisions (auto-managed)
+- **prompts/** - Customized [prompt templates](/docs/guides/prompt-templates)
 
 In addition to editing configuration files directly, many settings can be managed from goose Desktop and goose CLI:
 - **goose Desktop**: From the `Settings` page and the bottom toolbar

documentation/docs/guides/creating-plans.md

@@ -38,6 +38,10 @@ The goose CLI plan mode uses two configuration values:
 goose also supports automatic model switching with [Lead/Worker mode](/docs/guides/environment-variables#leadworker-model-configuration), which provides turn-based switching between two models to help balance model capabilities with cost and speed.
 :::
 
+:::tip Customize Plan Format
+You can also customize how goose creates plans by editing the `plan.md` [prompt template](/docs/guides/prompt-templates).
+:::
+
 ### Set goose planner environment variables
 You might add these lines to your bash shell config file (.bashrc) to add the planner environment variables:
 ```bash
@@ -318,13 +322,27 @@ To enter planning mode, type `/plan`.  Optionally, you can append your plan desc
 ( O)> /endplan
 ```
 
-<div className={styles.categorySection}>
+## Additional Resources
-  <h2 className={styles.categoryTitle}>📚 Featured Tutorial</h2>
+
-  <div className={styles.cardGrid}>
+import ContentCardCarousel from '@site/src/components/ContentCardCarousel';
-    <Card 
+import blogBanner from '@site/blog/2025-12-19-does-your-ai-agent-need-a-plan/blog-banner.png';
-      title="Planning Complex Tasks"
+
-      description="Learn how to use the Plan feature to break down complex tasks into manageable, executable steps."
+<ContentCardCarousel
-      link="/docs/tutorials/plan-feature-devcontainer-setup"
+  items={[
-    />
+      {
-  </div>
+      type: 'blog',
-</div>
+      title: 'Does Your AI Agent Need a Plan?',
+      description: 'Knowing when and how to plan with an AI agent can produce better results.',
+      thumbnailUrl: blogBanner,
+      linkUrl: '/goose/blog/2025/12/19/does-your-ai-agent-need-a-plan',
+      date: '2025-12-19',
+      duration: '7 min read'
+    },
+    {
+      type: 'topic',
+      title: 'Planning Complex Tasks',
+      description: 'Learn how to use the Plan feature to break down complex tasks into manageable, executable steps.',
+      linkUrl: '/goose/docs/tutorials/plan-feature-devcontainer-setup',
+    }
+  ]}
+/>

documentation/docs/guides/prompt-templates.md

@@ -0,0 +1,137 @@
+---
+sidebar_position: 86
+title: Customizing Prompt Templates
+sidebar_label: Prompt Templates
+description: Learn how to customize the prompt templates that define goose's behavior in different situations
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import { PanelLeft } from 'lucide-react';
+
+goose comes with built-in prompt templates that guide its behavior in different situations. You can edit these templates to customize how goose responds, creates plans, decides what to save during compaction, and more.
+
+## How It Works
+
+goose's default prompt templates are defined in the codebase and embedded in the application. You can override any default by creating a custom version in your local config directory (either directly or via goose Desktop).
+
+When you customize a template:
+
+- Your customizations persist across goose updates
+- Changes to defaults in the codebase don't affect your customized templates
+- You can reset to default templates at any time
+- Changes take effect in new sessions
+
+Your changes can range from major updates to minor adjustments such as:
+- Edit `system.md` to have goose respond in Dutch by adding an instruction to "Reply in Dutch"
+- Edit `plan.md` to add time estimates by adding instructions to "Include an estimated time for each step (e.g., "~5 min", "~30 min", "~2 hours")."
+
+See [Template Variable Syntax](#template-variable-syntax) for important information about modifying template variables.
+
+:::info Related Configuration
+Other goose settings and features can also affect behavior or provide context, such as [config files](/docs/guides/config-files), [.goosehints](/docs/guides/context-engineering/using-goosehints), and [skills](/docs/guides/context-engineering/using-skills).
+:::
+
+## Managing Prompt Templates
+
+<Tabs groupId="interface">
+  <TabItem value="ui" label="goose Desktop" default>
+  
+  goose Desktop users can manage templates from the `Settings` page.
+
+  **To customize a template:**
+
+  1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
+  2. Click `Settings` in the sidebar
+  3. Click the `Prompts` tab
+  4. Click `Edit` next to the template you want to change
+  5. Make your changes in the editor. You can click `Restore Default` to start over from the default template at any time.
+  6. Click `Save` to apply your customization
+
+  Customized prompt templates display a `Customized` badge.
+
+  **To reset a template to its default:**
+
+  1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
+  2. Click `Settings` in the sidebar
+  3. Click the `Prompts` tab
+  4. Click `Edit` next to the template you want to reset
+  5. Click `Reset to Default` to delete your local template file
+
+  Or click `Reset All` at the top of the tab to delete all of your local template files. 
+
+  </TabItem>
+  <TabItem value="cli" label="goose CLI">
+
+  goose CLI users can edit template files directly in the file system.
+
+  Custom templates are stored in:
+
+  - **macOS/Linux:** `~/.config/goose/prompts/`
+  - **Windows:** `%APPDATA%\Block\goose\config\prompts\`
+
+  **To customize a template:**
+
+  1. Create the `prompts` directory if it doesn't exist
+  2. Copy the template file name from the table above (e.g., `system.md`)
+  3. Create a file with that name in your prompts directory
+  4. Add your custom content and save your changes. We recommend that you start by reviewing or copying the default template (linked in the [table](#available-prompt-templates) above).
+
+  **To reset a template to its default:**
+
+  1. Delete the template file from your `prompts` directory
+
+  </TabItem>
+</Tabs>
+
+### Available Prompt Templates
+
+The following default templates can be customized.
+
+| Template | Description | Applies To |
+|----------|-------------|------------|
+| [system.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/system.md) | General system prompt defining goose's role, capabilities, and response format | Desktop and CLI |
+| [apps_create.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/apps_create.md) | Prompt for generating new standalone apps (in development) | Desktop only |
+| [apps_iterate.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/apps_iterate.md) | Prompt for updating existing standalone apps (in development) | Desktop only |
+| [compaction.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/compaction.md) | Prompt for summarizing conversation history when context limits are reached | Desktop and CLI |
+| [desktop_prompt.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/desktop_prompt.md) | Context about the user interface and available features | Desktop only |
+| [desktop_recipe_instruction.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/desktop_recipe_instruction.md) | Instructions for executing recipes | Desktop only |
+| [permission_judge.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/permission_judge.md) | Prompt for analyzing tool operations for read-only detection | Desktop and CLI |
+| [plan.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/plan.md) | Instructions for creating detailed, actionable plans with clarifying questions | CLI only |
+| [recipe.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/recipe.md) | Prompt for generating recipe files from conversations | Desktop and CLI |
+| [subagent_system.md](https://github.com/block/goose/blob/main/crates/goose/src/prompts/subagent_system.md) | System prompt for subagents spawned to handle specific tasks | Desktop and CLI |
+
+Customizable templates are enumerated in the `TEMPLATE_REGISTRY` array in [`prompt_template.rs`](https://github.com/block/goose/blob/main/crates/goose/src/prompt_template.rs).
+
+### Template Variable Syntax
+
+Templates use [Jinja2](https://jinja.palletsprojects.com/) syntax for dynamic content:
+
+- `{{ variable }}` - Inserts a value (e.g., `{{ extensions }}` lists enabled extensions)
+- `{% if condition %}...{% endif %}` - Conditional sections
+- `{% for item in list %}...{% endfor %}` - Loops over items
+
+Check out the default templates (linked to from the [table](#available-prompt-templates) above) to find common variables, such as `{{ extensions }}` and `{{ hints }}`.
+
+:::warning
+Be careful when modifying template variables, as incorrect changes can break functionality. Test your changes in a new session to ensure they work as expected.
+:::
+
+## Additional Resources
+
+import ContentCardCarousel from '@site/src/components/ContentCardCarousel';
+import promptBanner from '@site/blog/2025-03-19-better-ai-prompting/prompt.png';
+
+<ContentCardCarousel
+  items={[
+    {
+      type: 'blog',
+      title: 'AI Prompting 101: How to Get the Best Responses from Your AI Agent',
+      description: 'Learn different prompting styles—from instruction-based to chain-of-thought—and discover which approach works best for your needs.',
+      thumbnailUrl: promptBanner,
+      linkUrl: '/goose/blog/2025/03/19/better-ai-prompting',
+      date: '2025-03-19',
+      duration: '8 min read'
+    }
+  ]}
+/>

documentation/docs/guides/recipes/session-recipes.md

@@ -180,6 +180,10 @@ You can turn your current goose session into a reusable recipe that includes the
   </TabItem>
 </Tabs>
 
+:::tip Customize Recipe Generation
+You can customize how goose generates recipes by editing the `recipe.md` [prompt template](/docs/guides/prompt-templates).
+:::
+
 ## Edit Recipe
 <Tabs groupId="interface">
   <TabItem value="ui" label="goose Desktop" default>

documentation/docs/guides/sessions/smart-context-management.md

@@ -41,6 +41,10 @@ When you reach the auto-compaction threshold:
   2. Once complete, you'll see a confirmation message that the conversation was compacted and summarized.
   3. Continue the session. Your previous conversation remains visible, but only the compacted conversion is included in the active context for goose.
 
+:::tip Customize Compaction
+You can customize how goose summarizes conversations during compaction by editing the `compaction.md` [prompt template](/docs/guides/prompt-templates).
+:::
+
 ### Manual Compaction
 You can also trigger compaction manually before reaching context or token limits:
 

documentation/docs/guides/subagents.mdx

@@ -248,6 +248,10 @@ Subagents use the following pre-configured settings, but you can override any de
 | **Extensions** | Inherited from parent | Specify which extensions to use in your prompt |
 | **Return Mode** | All subagent information provided in main session | Specify how much detail you want in your prompt |
 
+:::tip Advanced Customization
+You can also customize subagent behavior by editing the `subagent_system.md` [prompt template](/docs/guides/prompt-templates).
+:::
+
 ### Customizing Settings in Prompts
 
 You can override any default by including the setting in your natural language request: