Skip to content

docs: recipe activity parameter substitution #5462

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
taniandjerry merged 1 commit into from
Oct 30, 2025
Merged

docs: recipe activity parameter substitution #5462

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 97 additions & 26 deletions documentation/docs/guides/recipes/recipe-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
sidebar_position: 2
title: Recipe Reference Guide
description: Complete technical reference for creating and customizing recipes in Goose via the CLI.
description: Complete technical reference for creating and customizing recipes in goose via the CLI.
---

Recipes are reusable Goose configurations that package up a specific setup so it can be easily shared and launched by others.
Recipes are reusable goose configurations that package up a specific setup so it can be easily shared and launched by others.

## Recipe File Format

Expand All @@ -20,10 +20,10 @@ After creating recipe files, you can use the [`goose recipe` subcommands](/docs/

### CLI and Desktop Formats

Goose recipes use two formats:
goose recipes use two formats:

- **CLI Format**: Recipe fields (like `title`, `description`, `instructions`) are at the root level of the YAML/JSON file. This format is used when recipes are created via the CLI `/recipe` command and [Recipe Generator](/recipe-generator) YAML option.
- **Desktop Format**: Recipe fields are nested inside a `recipe` object, with additional metadata fields at the root level. This format is used when recipes are created from Goose Desktop.
- **Desktop Format**: Recipe fields are nested inside a `recipe` object, with additional metadata fields at the root level. This format is used when recipes are created from goose Desktop.

The CLI automatically detects and handles both formats when running `goose run --recipe <file>` and `goose recipe` commands. The Desktop can [import](/docs/guides/recipes/storing-recipes#importing-recipes) and use YAML recipes (or deeplinks) in either CLI or Desktop format.

Expand Down Expand Up @@ -56,7 +56,7 @@ isArchived: false
```

:::note
Goose automatically adds metadata fields to recipes saved from the Desktop app.
goose automatically adds metadata fields to recipes saved from the Desktop app.
:::

</details>
Expand All @@ -77,16 +77,17 @@ Goose automatically adds metadata fields to recipes saved from the Desktop app.
|-------|------|-------------|
| `instructions` | String | Template instructions that can include parameter substitutions |
| `prompt` | String | A template prompt that can include parameter substitutions; required in headless (non-interactive) mode |
| `parameters` | Array | List of parameter definitions |
| `extensions` | Array | List of extension configurations |
| `settings` | Object | Configuration for model provider, model name, and other settings |
| `sub_recipes` | Array | List of subrecipes |
| `response` | Object | Configuration for structured output validation |
| `retry` | Object | Configuration for automated retry logic with success validation |
| [`parameters`](#parameters) | Array | List of parameter definitions |
| [`activities`](#activities) | Array | List of example prompts that appear as clickable bubbles in goose Desktop |
| [`extensions`](#extensions) | Array | List of extension configurations |
| [`settings`](#settings) | Object | Configuration for model provider, model name, and other settings |
| [`sub_recipes`](#subrecipes) | Array | List of subrecipes |
| [`response`](#structured-output-with-response) | Object | Structured output schema for automation workflows |
| [`retry`](#automated-retry-with-success-validation) | Object | Configuration for automated retry logic with success validation |

### Desktop Format Metadata Fields

When recipes are saved from Goose Desktop, additional metadata fields are included at the top level (outside the `recipe` key). These fields are used by the Desktop app for organization and management but are ignored by CLI operations.
When recipes are saved from goose Desktop, additional metadata fields are included at the top level (outside the `recipe` key). These fields are used by the Desktop app for organization and management but are ignored by CLI operations.

| Field | Type | Description |
|-------|------|-------------|
Expand All @@ -97,7 +98,9 @@ When recipes are saved from Goose Desktop, additional metadata fields are includ

## Parameters

Each parameter in the `parameters` array has the following structure:
The `parameters` field allows you to create dynamic, reusable recipes that can be customized for different contexts. Parameters define placeholders that users fill in when running the recipe, making the recipe more flexible and adaptable.

Parameter substitution uses Jinja-style template syntax with `{{ parameter_name }}` placeholders. Each parameter in the `parameters` array has the following structure:

### Required Parameter Fields

Expand All @@ -120,7 +123,7 @@ Each parameter in the `parameters` array has the following structure:
- `optional`: Can be omitted if a default value is specified
- `user_prompt`: Will interactively prompt the user for input if not provided

The `required` and `optional` parameters work best for recipes opened in Goose Desktop. If a value isn't provided for a `user_prompt` parameter, the parameter won't be substituted and may appear as literal `{{ parameter_name }}` text in the recipe output.
The `required` and `optional` parameters work best for recipes opened in goose Desktop. If a value isn't provided for a `user_prompt` parameter, the parameter won't be substituted and may appear as literal `{{ parameter_name }}` text in the recipe output.

### Input Types

Expand All @@ -140,15 +143,81 @@ parameters:
prompt: "Please review this code:\n\n{{ source_code }}"
```

When you run this recipe with `source_code: /path/to/app.py`, Goose will read the contents of `app.py` and substitute the actual code into the `{{ source_code }}` placeholder.
When you run this recipe with `source_code: /path/to/app.py`, goose will read the contents of `app.py` and substitute the actual code into the `{{ source_code }}` placeholder.

:::important
- Optional parameters MUST have a default value specified
- Required parameters cannot have default values
- File parameters cannot have default values regardless of requirement type to prevent unintended importing of sensitive files
- Parameter keys must match any template variables used in instructions or prompt
- Parameter keys must match any template variables used in instructions, prompt, or activities
:::

### Parameter Substitution in Desktop

When a recipe with parameters is opened in goose Desktop, users are presented with a **Recipe Parameters** dialog where they can:
- Provide values for required parameters
- Modify or accept default values for optional parameters
- Enter values for `user_prompt` parameters

Once parameter values are submitted, they are substituted into the recipe's `instructions`, `prompt`, and `activities` fields before the recipe starts.

## Activities

The `activities` field defines an optional message and clickable activity bubbles (buttons) that appears when a recipe is opened in goose Desktop.

:::info Desktop only
Activities are a Desktop-only feature. When recipes with activities are run via the CLI or as a scheduled job, the `activities` field is ignored and has no effect on recipe execution.
:::

### Activity Types

Activities can be defined in two ways:

1. **Message Activity**: Displays the markdown-formatted activity text in an info box above the activity bubbles. For example:

```
activities:
- "message: **Welcome!** Here's what I can help with:\n\n• 📊 Data analysis\n• 🔍 Code review\n• 📝 Documentation\n\nSelect an option below to begin."
```

Only include one `message:` prefixed activity. Additional `message:` prefixed activities become regular clickable bubbles (and display the literal "message:" text).

2. **Button Activities**: Text to display in activity bubbles, which send the activity text as a prompt when clicked

### Parameter Substitution

Activities support [parameter substitution](#parameters), allowing you to create dynamic, personalized activity bubbles. After users provide parameter values in the **Recipe Parameters** dialog, the values are substituted into the activity text before the bubbles are displayed.

### Example Configuration

```yaml
version: "1.0.0"
title: "Code Review Assistant"
description: "Review code with customizable focus areas"
parameters:
- key: language
input_type: string
requirement: required
description: "Programming language to review"
- key: focus
input_type: string
requirement: optional
default: "best practices"
description: "Review focus area"

activities:
- "message: Click an option below to start reviewing {{ language }} code with a focus on {{ focus }}."
- "Review the current file for {{ focus }}"
- "Suggest improvements for {{ language }} code quality"
- "Check for security vulnerabilities"
- "Generate unit tests"
```

In this example:
- The message activity displays instructions with substituted parameter values, for example: "Click an option below to start reviewing rust code with a focus on best practices."
- The first two activity bubbles use parameter substitution, for example: "Review the current file for best practices"
- The last two activity bubbles are static prompts that work regardless of parameters

## Extensions

The `extensions` field allows you to specify which Model Context Protocol (MCP) servers and other extensions the recipe needs to function. Each extension in the array has the following structure:
Expand All @@ -163,7 +232,7 @@ The `extensions` field allows you to specify which Model Context Protocol (MCP)
| `args` | Array | List of arguments for the command |
| `env_keys` | Array | (Optional) Names of environment variables required by the extension |
| `timeout` | Number | Timeout in seconds |
| `bundled` | Boolean | (Optional) Whether the extension is bundled with Goose |
| `bundled` | Boolean | (Optional) Whether the extension is bundled with goose |
| `description` | String | Description of what the extension does |
| `available_tools` | Array | List of tool names within the extension that will be available. When not specified all will be available |

Expand Down Expand Up @@ -203,10 +272,10 @@ extensions:

This feature is only available through the CLI.

If a recipe uses an extension that requires a secret, Goose can prompt users to provide the secret when running the recipe:
If a recipe uses an extension that requires a secret, goose can prompt users to provide the secret when running the recipe:

1. When a recipe is loaded, Goose scans all extensions (including those in subrecipes) for `env_keys` fields
2. If any required environment variables are missing from the secure keyring, Goose prompts the user to enter them
1. When a recipe is loaded, goose scans all extensions (including those in subrecipes) for `env_keys` fields
2. If any required environment variables are missing from the secure keyring, goose prompts the user to enter them
3. Values are stored securely in the system keyring and reused for subsequent runs

To update a stored secret, remove it from the system keyring and run the recipe again to be re-prompted.
Expand Down Expand Up @@ -246,7 +315,7 @@ settings:
```

:::note
Settings specified in a recipe will override your default Goose configuration when that recipe is executed. If no settings are specified, Goose will use your configured defaults.
Settings specified in a recipe will override your default goose configuration when that recipe is executed. If no settings are specified, goose will use your configured defaults.
:::

## Subrecipes
Expand Down Expand Up @@ -359,12 +428,12 @@ These environment variables are overridden by recipe-specific timeout configurat

## Structured Output with `response`

The `response` field enables recipes to enforce a final structured JSON output from Goose. When you specify a `json_schema`, Goose will:
The `response` field enables recipes to enforce a final structured JSON output from goose. When you specify a `json_schema`, goose will:

1. **Validate the output**: Validates the output JSON against your JSON schema with basic JSON schema validations
2. **Final structured output**: Ensure the final output of the agent is a response matching your JSON structure

This **enables automation** by returning consistent, parseable results for scripts and workflows. Recipes can produce structured output when run from either the Goose CLI or Goose Desktop. See [use cases and ideas for automation workflows](/docs/guides/recipes/session-recipes#structured-output-for-automation).
This feature is designed for **non-interactive automation** to ensure consistent, parseable output. Recipes can produce structured output when run from either the goose CLI or goose Desktop. See [use cases and ideas for automation workflows](/docs/guides/recipes/session-recipes#structured-output-for-automation).

### Basic Structure

Expand Down Expand Up @@ -407,11 +476,13 @@ response:

## Template Support

Recipes support Jinja-style template syntax in both `instructions` and `prompt` fields:
Recipes support Jinja-style template syntax in `instructions`, `prompt`, and `activities` fields:

```yaml
instructions: "Follow these steps with {{ parameter_name }}"
prompt: "Your task is to {{ action }}"
activities:
- "Process {{ parameter_name }} with {{ action }}"
```

Advanced template features include:
Expand Down Expand Up @@ -563,7 +634,7 @@ Common errors to watch for:
- Invalid extension configurations
- Invalid retry configuration (missing required fields, invalid shell commands)

When these occur, Goose will provide helpful error messages indicating what needs to be fixed.
When these occur, goose will provide helpful error messages indicating what needs to be fixed.

### Retry-Specific Errors

Expand All @@ -573,4 +644,4 @@ When these occur, Goose will provide helpful error messages indicating what need
- **Missing required retry fields**: When `max_retries` or `checks` are not specified

## Learn More
Check out the [Goose Recipes](/docs/guides/recipes) guide for more docs, tools, and resources to help you master Goose recipes.
Check out the [Recipes](/docs/guides/recipes) guide for more docs, tools, and resources to help you master goose recipes.