From 44fa6a442e877da8e29ccc15913e229ec9851199 Mon Sep 17 00:00:00 2001 From: Rizel Scarlett Date: Sun, 1 Jun 2025 03:37:00 -0400 Subject: [PATCH] Docs recipe revamp (#2753) --- documentation/docs/guides/config-file.md | 4 + .../docs/guides/goose-cli-commands.md | 21 +- documentation/docs/guides/session-recipes.md | 343 +++++++++++------- 3 files changed, 229 insertions(+), 139 deletions(-) diff --git a/documentation/docs/guides/config-file.md b/documentation/docs/guides/config-file.md index 3eb4d78854..f5f28bbd59 100644 --- a/documentation/docs/guides/config-file.md +++ b/documentation/docs/guides/config-file.md @@ -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: diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index 96abdb5d3d..44c653ba8f 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -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 ``` +**Commands:** +- `validate `: Validate a recipe file +- `deeplink `: 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 ``` diff --git a/documentation/docs/guides/session-recipes.md b/documentation/docs/guides/session-recipes.md index ed6479a6c0..97533622dc 100644 --- a/documentation/docs/guides/session-recipes.md +++ b/documentation/docs/guides/session-recipes.md @@ -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. -::: - + :::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) + :::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 ```
- recipe.yaml - + recipe file structure + ```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 ``` -
- 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
Example recipe with parameters - - ```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 ``` -
- 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. - 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 - 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: + + - ```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 + - ```sh - goose run --recipe recipe.yaml --explain - ``` + - #### 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. - + + + + ### 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 + 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 + ``` + + + + + + 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. + + + + + +:::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. \ No newline at end of file