mirror of
https://github.com/block/goose.git
synced 2026-07-17 12:56:20 +02:00
docs: customizable prompt templates (#6908)
This commit is contained in:
dianed-square
@@ -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
|
||||
|
||||
@@ -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}>
|
||||
<h2 className={styles.categoryTitle}>📚 Featured Tutorial</h2>
|
||||
<div className={styles.cardGrid}>
|
||||
<Card
|
||||
title="Planning Complex Tasks"
|
||||
description="Learn how to use the Plan feature to break down complex tasks into manageable, executable steps."
|
||||
link="/docs/tutorials/plan-feature-devcontainer-setup"
|
||||
/>
|
||||
</div>
|
||||
</div>
|
||||
## Additional Resources
|
||||
|
||||
import ContentCardCarousel from '@site/src/components/ContentCardCarousel';
|
||||
import blogBanner from '@site/blog/2025-12-19-does-your-ai-agent-need-a-plan/blog-banner.png';
|
||||
|
||||
<ContentCardCarousel
|
||||
items={[
|
||||
{
|
||||
type: 'blog',
|
||||
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',
|
||||
}
|
||||
]}
|
||||
/>
|
||||
@@ -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'
|
||||
}
|
||||
]}
|
||||
/>
|
||||
@@ -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>
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user