aljaz/goose
1
0
Fork 0
mirror of https://github.com/aljazceru/goose.git synced 2025-12-18 06:34:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs recipe revamp (#2753)

Browse Source
This commit is contained in:
Rizel Scarlett
2025-06-01 03:37:00 -04:00
committed by GitHub
parent 179da551f8
commit 44fa6a442e
3 changed files with 229 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
documentation/docs/guides/config-file.md
View File

@@ -29,6 +29,7 @@ The following settings can be configured at the root level of your config.yaml f
| `GOOSE_TOOLSHIM_OLLAMA_MODEL` | Model for tool interpretation | Model name (e.g., "llama3.2") | System default | No |
| `GOOSE_CLI_MIN_PRIORITY` | Tool output verbosity | Float between 0.0 and 1.0 | 0.0 | No |
| `GOOSE_ALLOWLIST` | URL for allowed extensions | Valid URL | None | No |
| `GOOSE_RECIPE_GITHUB_REPO` | GitHub repository for recipes | Format: "org/repo" | None | No |
## Example Configuration
@@ -49,6 +50,9 @@ GOOSE_MODE: "smart_approve"
GOOSE_TOOLSHIM: true
GOOSE_CLI_MIN_PRIORITY: 0.2
# Recipe Configuration
GOOSE_RECIPE_GITHUB_REPO: "block/goose-recipes"
# Extensions Configuration
extensions:
developer:

21
documentation/docs/guides/goose-cli-commands.md
View File

@@ -303,26 +303,29 @@ goose bench ...etc.
```
### recipe
Used to validate a recipe file and get a link to share the recipe (aka "shared agent") with another Goose user.
Used to validate recipe files and manage recipe sharing.
**Usage:**
```bash
goose recipe <COMMAND>
```
**Commands:**
- `validate <FILE>`: Validate a recipe file
- `deeplink <FILE>`: Generate a shareable link for a recipe file
**Options:**
- `--help, -h`: Print help information
- **`--help, -h`**: Print this message or the help for the subcommand
**Usage:**
**Examples:**
```bash
# Validate a recipe file
goose recipe validate $FILE.yaml
goose recipe validate my-recipe.yaml
# Generate a deeplink for a recipe file
goose recipe deeplink $FILE.yaml
# Generate a shareable link
goose recipe deeplink my-recipe.yaml
# Print this message or the help for the given command
# Get help about recipe commands
goose recipe help
```

343
documentation/docs/guides/session-recipes.md
View File

@@ -14,16 +14,11 @@ You can turn your current Goose session into a reusable recipe that includes the
## Create Recipe
:::tip Heads Up
You'll need to provide both instructions and activities for your Recipe.
- **Instructions** provide the purpose. These get sent directly to the model and define how it behaves. Think of this as its internal mission statement. Make it clear, action-oriented, and scoped to the task at hand.
- **Activities** are specific, example prompts that appear as clickable bubbles on a fresh session. They help others understand how to use the Recipe.
:::
<Tabs>
<TabItem value="ui" label="Goose Desktop" default>
:::warning
You cannot create a recipe from an existing recipe session - the "Make Agent from this session" option will be disabled.
:::
1. While in the session you want to save as a recipe, click the menu icon **⋮** in the top right corner
2. Select **Make Agent from this session**
@@ -32,74 +27,64 @@ You'll need to provide both instructions and activities for your Recipe.
- Provide a description
- Some **activities** will be automatically generated. Add or remove as needed.
- A set of **instructions** will also be automatically generated. Review and edit as needed.
4. Copy the Recipe URL and use it however you like (e.g., share it with teammates, drop it in documentation, or keep it for yourself)
4. Copy the recipe URL and use it however you like (e.g., share it with teammates, drop it in documentation, or keep it for yourself)
</TabItem>
<TabItem value="cli" label="Goose CLI">
:::warning
You cannot create a recipe from an existing recipe session - the `/recipe` command will not work.
:::
While in a session, run the following command:
### Create a Recipe File
Recipe files can be either JSON (.json) or YAML (.yaml) files. While in a [session](/docs/guides/managing-goose-sessions#start-session), run this command to generate a recipe.yaml file in your current directory:
```sh
/recipe
```
This will generate a `recipe.yaml` file in your current directory.
Alternatively, you can provide a custom filename:
If you want to specify a different name, you can provide it as an argument:
```sh
/recipe my-custom-recipe.yaml
```
<details>
<summary>recipe.yaml</summary>
<summary>recipe file structure</summary>
```yaml
# Required fields
version: 1.0.0
title: $title
description: $description
instructions: $instructions # instructions to be added to the system prompt
instructions: $instructions # Define the model's behavior
# Optional fields
prompt: $prompt # if set, the initial prompt for the run/session
extensions:
prompt: $prompt # Initial message to start with
extensions: # Tools the recipe needs
- $extensions
context:
- $context
activities: # example prompts to display in the Desktop app
activities: # Example prompts to display in the Desktop app
- $activities
author:
contact: $contact
metadata: $metadata
parameters: # required if recipe uses {{ variables }}
- key: $param_key
input_type: $type # string, number, etc
requirement: $req # required, optional, or user_prompt
description: $description
default: $value # required for optional parameters
```
</details>
You can then edit the recipe file to include the following key information:
### Edit Recipe File
- `instructions`: Add or modify the system instructions
- `prompt`: Add the initial message or question to start a Goose session with
- `activities`: List the activities that can be performed, which are displayed as prompts in the Desktop app
Once the recipe file is created, you can open it and modify the value of any field.
### Optional Parameters
#### Recipe 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, edit your recipe file to include template variables using `{{ variable_name }}` syntax and define each of them in your yaml using `parameters`.
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
<details>
<summary>Example recipe with parameters</summary>
```yaml title="code-review.yaml"
```yaml
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
@@ -138,32 +123,25 @@ You'll need to provide both instructions and activities for your Recipe.
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
```
</details>
When someone runs a recipe that contains template parameters, they will need to provide the parameters:
### Validate Recipe
```sh
goose run --recipe code-review.yaml \
--params project_name=MyApp \
--params language=Python \
--params complexity_threshold=15 \
--params test_coverage=80 \
--params style_guide=PEP8
```
#### Validate the recipe
[Exit the session](/docs/guides/managing-goose-sessions/#exit-session) and run:
[Exit the session](/docs/guides/managing-goose-sessions#exit-session) and run:
```sh
goose recipe validate recipe.yaml
```
#### Share the recipe
Validation ensures that:
- All required fields are present
- Parameters are properly formatted
- Referenced extensions exist and are valid
- The YAML/JSON syntax is correct
- To share with **CLI users**, send them the recipe yaml file
- To share with **Desktop users**, run the following command to create a deep link:
### Share Your Recipe
Now that your recipe is created, you can share it with CLI users by directly sending them the recipe file or converting it to a shareable deep link for Desktop users:
```sh
goose recipe deeplink recipe.yaml
@@ -178,76 +156,204 @@ You'll need to provide both instructions and activities for your Recipe.
<Tabs>
<TabItem value="ui" label="Goose Desktop" default>
To use a shared recipe, simply click the recipe link, or paste in a browser address bar. This will open Goose Desktop and start a new session with:
There are two ways to use a recipe in Goose Desktop:
- The recipe's defined instructions
- Suggested activities as clickable bubbles
- The same extensions and project context (if applicable)
Each person using the recipe gets their own private session, so no data is shared between users, and nothing links back to your original session.
1. **Direct Link**
- Click a recipe link shared with you
- The recipe will automatically open in Goose Desktop
2. **Manual URL Entry**
- Copy a recipe URL
- Paste it into your browser's address bar
- You will see a prompt to "Open Goose"
- Goose Desktop will open with the recipe
</TabItem>
<TabItem value="cli" label="Goose CLI">
You can start a session with a recipe file in the following ways:
### Configure Recipe Location
- Run the recipe once and exit:
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](/docs/guides/config-file#global-settings).
```sh
goose run --recipe recipe.yaml
```
:::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 recipe and enter interactive mode:
<Tabs>
<TabItem value="configure" label="Using goose configure" default>
```sh
goose run --recipe recipe.yaml --interactive
```
Run the configure command:
```sh
goose configure
```
- Run the recipe with parameters:
You'll see the following prompts:
```sh
goose run --recipe recipe.yaml --interactive --params language=Spanish --params style=formal --params name=Alice
```
```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
└
```
- Explain the recipe with description and parameters
</TabItem>
```sh
goose run --recipe recipe.yaml --explain
```
<TabItem value="config" label="Using config file">
#### Discover recipes
When using recipe-related CLI commands, there are a few ways to specify which recipe to use:
##### Option 1: Provide the full file path
Use the exact path to the recipe file:
```sh
goose run --recipe ~/my_recipe.yaml
goose recipe validate ~/my_recipe.yaml
goose recipe deeplink ~/my_recipe.yaml
```
##### Option 2: Use the recipe name
If your recipe is named my_recipe, you can simply use the name:
Add to your config file:
```yaml title="~/.config/goose/config.yaml"
GOOSE_RECIPE_GITHUB_REPO: "owner/repo"
```
```sh
goose run --recipe my_recipe
goose recipe validate my_recipe
goose recipe deeplink my_recipe
```
When you use the recipe name, Goose will search for the file in the following order:
1. Local search:
Goose will search for `my_recipe.yaml` or `my_recipe.json` in the current working directory
2. Remote search (GitHub):
- If the `GOOSE_RECIPE_GITHUB_REPO` environment variable is set or configured in the `Goose Settings` via `goose configure`, Goose will search the specified GitHub repo. (eg: my_org/goose-recipes).
- Goose will look for `my_recipe/recipe.yaml` or `my_recipe/recipe.json` within that GitHub repository.
</TabItem>
</TabItem>
</Tabs>
### Run a Recipe
<Tabs>
<TabItem value="local" label="Local Recipe" default>
**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
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
```
</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>
</Tabs>
</TabItem>
</Tabs>
:::note 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
:::
## 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
## What's Included
A Recipe captures:
A recipe captures:
- AI instructions (goal/purpose)
- Suggested activities (examples for the user to click)
@@ -263,27 +369,4 @@ To protect your privacy and system integrity, Goose excludes:
- System-level Goose settings
This means others may need to supply their own credentials or memory context if the Recipe depends on those elements.
## Example Use Cases
- 🔧 Share a debugging workflow with your team
- 📦 Save a repeatable project setup
- 📚 Onboard someone into a task without overwhelming them
## Tips for Great Recipes
If you're sharing recipes with others, here are some tips:
- Be specific and clear in the instructions, so users know what the recipe is meant to do.
- Keep the activity list focused. Remove anything that's too specific or out of scope.
- Test the link yourself before sharing to make sure everything loads as expected.
- Mention any setup steps that users might need to complete (e.g., obtaining an API key).
## Troubleshooting
- You can't create a Recipe from an existing Recipe session. The menu option will be disabled
- Make sure you're using the latest version of Goose if something isn't working
- Remember that credentials, memory, and certain local setups won't carry over
This means others may need to supply their own credentials or memory context if the recipe depends on those elements.