Reusable Recipes

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import { PanelLeft, ChefHat, SquarePen, Link, Clock, Terminal, Share2 } from 'lucide-react'; import RecipeFields from '@site/src/components/RecipeFields';

Sometimes you finish a task in goose and realize, "Hey, this setup could be useful again." Maybe you have curated a great combination of tools, defined a clear goal, and want to preserve that flow. Or maybe you're trying to help someone else replicate what you just did without walking them through it step by step.

You can turn your current goose session into a reusable recipe that includes the tools, goals, and setup you're using right now and package it into a new Agent that others (or future you) can launch with a single click.

Create Recipe

Create a recipe from the current session or from a template.

:::warning You cannot create a recipe from an existing recipe session, but you can view or edit the recipe. :::

/recipe

If you want to specify a different name, you can provide it as an argument:

/recipe my-custom-recipe.yaml

# Required fields
version: 1.0.0
title: $title
description: $description
instructions: $instructions    # Define the model's behavior

# Optional fields
prompt: $prompt                # Initial message to start with
extensions:                    # Tools the recipe needs
- $extensions
activities:                    # Example prompts to display in the Desktop app
- $activities
settings:                      # Additional settings
  goose_provider: $provider    # Provider to use for this recipe
  goose_model: $model          # Specific model to use for this recipe
  temperature: $temperature    # Model temperature setting for this recipe (0.0 to 1.0)
retry:                         # Automated retry logic with success validation
  max_retries: $max_retries    # Maximum number of retry attempts
  checks:                      # Success validation checks
  - type: shell
    command: $validation_command
  on_failure: $cleanup_command # Optional cleanup command on failure

For detailed descriptions and example configurations of all recipe fields, see the [Recipe Reference Guide](/docs/guides/recipes/recipe-reference).

:::warning You cannot create a recipe from an existing recipe session - the /recipe command will not work. :::

:::tip Validate Your Recipe You should validate your recipe to verify that it's complete and properly formatted. :::

Optional Parameters

You may add parameters to a recipe, which will require users to fill in data when running the recipe. Parameters can be added to any part of the recipe (instructions, prompt, activities, etc).

To use parameters:

1. Add template variables using {{ variable_name }} syntax in your recipe content
2. Define each parameter in the parameters section of your YAML file

version: 1.0.0
title: "{{ project_name }} Code Review" # Wrap the value in quotes if it starts with template syntax to avoid YAML parsing errors
description: Automated code review for {{ project_name }} with {{ language }} focus
instructions: You are a code reviewer specialized in {{ language }} development.
prompt: |
   Apply the following standards:
   - Complexity threshold: {{ complexity_threshold }}
   - Required test coverage: {{ test_coverage }}%
   - Style guide: {{ style_guide }}
activities:
- "Review {{ language }} code for complexity"
- "Check test coverage against {{ test_coverage }}% requirement"
- "Verify {{ style_guide }} compliance"
settings:                     
  goose_provider: "anthropic"   
  goose_model: "claude-3-7-sonnet-latest"          
  temperature: 0.7 
parameters:
- key: project_name
  input_type: string
  requirement: required # could be required, optional or user_prompt
  description: name of the project
- key: language
  input_type: string
  requirement: required
  description: language of the code
- key: complexity_threshold
  input_type: number
  requirement: optional
  default: 20 # default is required for optional parameters
  description: a threshold that defines the maximum allowed complexity
- key: test_coverage
  input_type: number
  requirement: optional
  default: 80
  description: the minimum test coverage threshold in percentage
- key: style_guide
  input_type: string
  description: style guide name
  requirement: user_prompt
  # If style_guide param value is not specified in the command, user will be prompted to provide a value, even in non-interactive mode

See the Recipe Reference Guide for more information about recipe fields.

- **URL Format**: Generates a shareable link that opens a session in goose Desktop
- **YAML Format**: Generates YAML content that you can save to file and then run in goose CLI

Then fill out the recipe form by providing:
  - A **title** for the recipe
  - A **description**
  - A set of **instructions** for the recipe.
  - An optional initial **prompt**:
    - In the Desktop, the prompt displays in the chat box.
    - In the CLI, the prompt provides the initial message to run. Note that a prompt is required to run the recipe in headless (non-interactive) mode.
  - A set of optional **activities** to display in the Desktop.
  - YAML format only: Optional **author** contact information and **extensions** the recipe uses.

:::tip Customize Recipe Generation You can customize how goose generates recipes by editing the recipe.md prompt template. :::

Edit Recipe

1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click Recipes in the sidebar
3. Find the recipe you want to edit and click the <SquarePen className="inline" size={16} /> button
4. In the dialog that appears, edit any of the following: <RecipeFields />
5. When you're finished, you can:
   • Copy the recipe link to share the recipe with others
   • Click Save Recipe to save your changes
   • Click Save & Run Recipe to save and immediately run the recipe in a new session

:::tip Edit In-Use Recipe You can also access the edit dialog while using a recipe in a session: Just click the <ChefHat className="inline" size={16} /> button at the bottom of the app. The button shows up after you've sent your first message. :::

Use Recipe

1. Open the recipe using a direct link or manual URL entry, or from your Recipe library:

   Direct Link:

   Copy

   1. Click a recipe link shared with you
   

   Manual URL Entry:

   Copy

   1. Paste a recipe link into your browser's address bar 
   2. Press `Enter` and click the `Open Goose.app` prompt
   

   Recipe Library:

   Copy

   1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
   2. Click `Recipes` in the sidebar
   3. Find your recipe in the Recipe Library
   4. Click `Use` next to the recipe you want to open
   

   Slash Command:

   Copy

   1. Enter a [custom slash command](/docs/guides/context-engineering/slash-commands) in any goose chat session
   

2. The first time you run a recipe, a warning dialog displays the recipe's title, description, and instructions for you to review. If you trust the recipe content, click Trust and Execute to continue. You won't be prompted again for the same recipe unless it changes.

3. If the recipe contains parameters, enter your values in the Recipe Parameters dialog and click Start Recipe.

   Parameters are dynamic values used in the recipe:

   • Required parameters are marked with red asterisks (*)
   • Optional parameters show default values that can be changed

4. The recipe automatically submits and goose begins execution. If the recipe includes a prompt, it's sent as the first message. If not, you can click an activity bubble or send a prompt to get started.

:::info Privacy & Isolation

• Each person gets their own private session
• No data is shared between users
• Your session won't affect the original recipe creator's session ::: </TabItem>

Using a recipe with the goose CLI might involve the following tasks:

• Configuring your recipe location
• Running a recipe
• Scheduling a recipe

Configure Recipe Location

Recipes can be stored locally on your device or in a GitHub repository. Configure your recipe repository using either the goose configure command or config file.

:::tip Repository Structure

• Each recipe should be in its own directory
• Directory name matches the recipe name you use in commands
• Recipe file can be either recipe.yaml or recipe.json :::

   Run the configure command:
   ```sh
   goose configure
   ```

   You'll see the following prompts:

   ```sh
   ┌  goose-configure 
   │
   ◆  What would you like to configure?
   │  ○ Configure Providers 
   │  ○ Add Extension 
   │  ○ Toggle Extensions 
   │  ○ Remove Extension 
   // highlight-start
   │  ● goose settings (Set the goose mode, Tool Output, Tool Permissions, Experiment, goose recipe github repo and more)
   // highlight-end
   │
   ◇  What would you like to configure?
   │  goose settings 
   │
   ◆  What setting would you like to configure?
   │  ○ goose mode 
   │  ○ Tool Permission 
   │  ○ Tool Output 
   │  ○ Toggle Experiment 
   // highlight-start
   │  ● goose recipe github repo (goose will pull recipes from this repo if not found locally.)
   // highlight-end
   └  
   ┌  goose-configure 
   │
   ◇  What would you like to configure?
   │  goose settings 
   │
   ◇  What setting would you like to configure?
   │  goose recipe github repo 
   │
   ◆  Enter your goose recipe GitHub repo (owner/repo): eg: my_org/goose-recipes
   // highlight-start
   │  squareup/goose-recipes (default)
   // highlight-end
   └  
   ```

 </TabItem>

 <TabItem value="config" label="Using config file">

   Add to your config file:
   ```yaml title="~/.config/goose/config.yaml"
   GOOSE_RECIPE_GITHUB_REPO: "owner/repo"
   ```

 </TabItem>

Run a Recipe

   **Basic Usage** - Run once and exit (see [run options](/docs/guides/goose-cli-commands#run-options) and [recipe commands](/docs/guides/goose-cli-commands#recipe) for more):
   ```sh
   # Using recipe file in current directory or [`GOOSE_RECIPE_PATH`](/docs/guides/environment-variables#recipe-configuration) directories
   goose run --recipe recipe.yaml

   # Using full path
   goose run --recipe ./recipes/my-recipe.yaml
   ```

   **Preview Recipe** - Use the [`explain`](/docs/guides/goose-cli-commands#run-options) command to view details before running:

   **Interactive Mode** - Start an interactive session:
   ```sh
   goose run --recipe recipe.yaml --interactive
   ```
   The interactive mode will prompt for required values:
   ```sh
   ◆ Enter value for required parameter 'language':
   │ Python
   │
   ◆ Enter value for required parameter 'style_guide':
   │ PEP8
   ```

   **With Parameters** - Supply parameter values when running recipes. See the [`run` command documentation](/docs/guides/goose-cli-commands#run-options) for detailed examples and options.

   Basic example:
   ```sh
   goose run --recipe recipe.yaml --params language=Python
   ```

   **Slash Command** - Enter a [custom slash command](/docs/guides/context-engineering/slash-commands) in any goose chat session

 </TabItem>

 <TabItem value="github" label="GitHub Recipe">

   Once you've configured your GitHub repository, you can run recipes by name:

   **Basic Usage** - Run recipes from your configured repo using the recipe name that matches its directory (see [run options](/docs/guides/goose-cli-commands#run-options) and [recipe commands](/docs/guides/goose-cli-commands#recipe) for more):

   ```sh
   goose run --recipe recipe-name
   ```

   For example, if your repository structure is:
   ```
   my-repo/
   ├── code-review/
   │   └── recipe.yaml
   └── setup-project/
       └── recipe.yaml
   ```
   
   You would run the following command to run the code review recipe:
   ```sh
   goose run --recipe code-review
   ```

  **Preview Recipe** - Use the [`explain`](/docs/guides/goose-cli-commands#run-options) command to view details before running:

   **Interactive Mode** - With parameter prompts:
   ```sh
   goose run --recipe code-review --interactive
   ```
   The interactive mode will prompt for required values:
   ```sh
   ◆ Enter value for required parameter 'project_name':
   │ MyProject
   │
   ◆ Enter value for required parameter 'language':
   │ Python
   ```

   **With Parameters** - Supply parameter values when running recipes. See the [`run` command documentation](/docs/guides/goose-cli-commands#run-options) for detailed examples and options.

 </TabItem>

Validate Recipe

goose recipe validate recipe.yaml

:::info If you want to validate a recipe you just created, you need to exit the session before running the validate subcommand. :::

Recipe validation can be useful for: - Troubleshooting recipes that aren't working as expected - Verifying recipes after manual edits - Automated testing in CI/CD pipelines

Share Recipe

Share your recipe with goose users using a recipe link or recipe file.

:::info Privacy & Isolation Each recipient gets their own private session when using your shared recipe. No data is shared between users, and your original session and recipe remain unaffected. :::

Share via Recipe Link

You can share a recipe with Desktop users via a recipe link.

You can also provide parameter values to pre-fill the `Recipe Parameters` dialog:
```sh
goose recipe deeplink <FILE> --param key1=value1 --param key2=value2
```

When someone clicks the link, it will open goose Desktop with your recipe configuration. They can also use your recipe link to import a recipe for future use.

Share via Recipe File

You can share a recipe with Desktop or CLI users by sending the recipe file directly.

In goose Desktop, you can export a recipe file or copy its content to share with others.

1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click Recipes in the sidebar
3. Find the recipe you want to share and click the <Share2 className="inline" size={16} /> button
4. Choose a sharing method:
   • To download the recipe as a .yaml file: Choose Export to File, select a download location, and click Save
   • To copy the recipe's YAML content to your clipboard: Choose Copy YAML

Other Desktop users can import the recipe to their Recipe Library.

Exporting or copying recipe content is only available through the Desktop, but you can copy local recipe files directly.

CLI users can run a shared recipe file using goose run --recipe <FILE> or open it directly in goose Desktop with goose recipe open <FILE>. See the CLI Commands guide for details.

Schedule Recipe

Schedule from Recipe Library:

1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click Recipes in the sidebar
3. Find the recipe you want to schedule and click the <Clock className="inline" size={16} /> button
4. Click Create Schedule
5. In the dialog that appears, configure the schedule. For Source, your recipe link is already provided.
6. Click Create Schedule

Schedule from Scheduler View:

1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click Scheduler
3. Click Create Schedule
4. In the dialog that appears, configure the schedule. For Source, select a .yaml or .yml file or provide a recipe link.
5. Click Create Schedule

Manage Scheduled Recipes

Your scheduled recipes are listed in the Scheduler page. Click on a schedule to view details, see when it was last run, and perform actions with the scheduled recipe:

• Run Schedule Now to trigger the recipe manually
• Edit Schedule to change the scheduled frequency
• Pause Schedule to stop the recipe from running automatically

At the bottom of the Schedule Details page you can view the list of sessions created by the scheduled recipe and open or restore each session.

# Add a new scheduled recipe which runs every day at 9 AM
goose schedule add --schedule-id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml

You can use either a 5, 6, or 7-digit cron expression for full scheduling precision, following the format "seconds minutes hours day-of-month month day-of-week year".

See the schedule command documentation for detailed examples and options. </TabItem> </Tabs>

Core Components

A recipe needs these core components:

• Instructions: Define the agent's behavior and capabilities

  • Acts as the agent's mission statement
  • Makes the agent ready for any relevant task
  • Required if no prompt is provided

• Prompt (Optional): Starts the conversation automatically

  • Without a prompt, the agent waits for user input
  • Useful for specific, immediate tasks
  • Required if no instructions are provided

• Activities: Example tasks that appear as clickable bubbles

  • Help users understand what the recipe can do
  • Make it easy to get started

Advanced Features

Automated Retry Logic

Recipes can include retry logic to automatically attempt task completion multiple times until success criteria are met. This is particularly useful for:

• Automation workflows that need to ensure successful completion
• Development tasks like running tests that may need multiple attempts
• System operations that require validation and cleanup

Basic retry configuration:

retry:
  max_retries: 3
  checks:
    - type: shell
      command: "test -f output.txt"  # Check if output file exists
  on_failure: "rm -f temp_files*"   # Cleanup on failure

How it works:

1. Recipe executes normally with provided instructions
2. After completion, success checks validate the results
3. If validation fails and retries remain:
   • Optional cleanup command runs
   • Agent state resets to initial conditions
   • Recipe execution starts over
4. Process continues until either success or max retries reached

See the Recipe Reference Guide for complete retry configuration options and examples.

Structured Output for Automation

Recipes can enforce structured JSON output, making them ideal for automation workflows that need to parse and process agent responses reliably. Key benefits include:

• Reliable parsing: Consistent JSON format for scripts, automation, and CI/CD pipelines
• Built-in validation: Ensures output matches your requirements
• Easy extraction: Final output appears as a single line for simple parsing

Structured output is particularly useful for:

• Development workflows: Code analysis reports, test results with pass/fail counts, and build status with deployment readiness
• Data processing: Results with counts and validation status, content analysis with structured findings
• Documentation generation: Consistent metadata and structured project reports for further processing

Example structured output configuration:

response:
  json_schema:
    type: object
    properties:
      build_status:
        type: string
        enum: ["success", "failed", "warning"]
        description: "Overall build result"
      tests_passed:
        type: number
        description: "Number of tests that passed"
      tests_failed:
        type: number
        description: "Number of tests that failed"
      artifacts:
        type: array
        items:
          type: string
        description: "Generated build artifacts"
      deployment_ready:
        type: boolean
        description: "Whether the build is ready for deployment"
    required:
      - build_status
      - tests_passed
      - tests_failed
      - deployment_ready

How it works:

1. Recipe runs normally with provided instructions
2. goose calls a final_output tool with JSON matching your schema
3. Output is validated against the JSON schema
4. If validation fails, goose receives error details and must correct the output
5. Final validated JSON appears as the last line of output for easy extraction

Example automation usage:

# Run recipe and extract JSON output
goose run --recipe analysis.yaml --params project_path=./src > output.log
RESULT=$(tail -n 1 output.log)
echo "Analysis Status: $(echo $RESULT | jq -r '.build_status')"
echo "Issues Found: $(echo $RESULT | jq -r '.tests_failed')"

:::info Structured output is supported in recipes run in both the goose CLI and goose Desktop. However, creating and editing the json_schema configuration must be done manually in the recipe file. :::

What's Included

A recipe captures:

• AI instructions (goal/purpose)
• Suggested activities (examples for the user to click)
• Enabled extensions and their configurations
• Project folder or file context
• Initial setup (but not full conversation history)
• The model and provider to use when running the recipe (optional)
• Retry logic and success validation configuration (if configured)

To protect your privacy and system integrity, goose excludes:

• Global and local memory
• API keys and personal credentials
• System-level goose settings

This means others may need to supply their own credentials or memory context if the recipe depends on those elements.

Learn More

Check out the Recipes guide for more docs, tools, and resources to help you master goose recipes.