tkmind/tkmind_go
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

Docs: recipe landing page (#3122)

Browse Source
This commit is contained in:
Rizel Scarlett
2025-06-28 00:00:06 -04:00
committed by GitHub
parent d7fa8aed5c
commit 7899cd0c02
12 changed files with 231 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/docs/guides/recipes/_category_.json
+8
View File
@@ -0,0 +1,8 @@
{
"label": "Recipes",
"position": 1,
"link": {
"type": "doc",
"id": "guides/recipes/index"
}
}
documentation/docs/guides/recipes/index.md
+75
View File
@@ -0,0 +1,75 @@
---
title: Recipes
hide_title: true
description: Reusable and shareable AI workflows
---
import Card from '@site/src/components/Card';
import styles from '@site/src/components/Card/styles.module.css';
<h1 className={styles.pageTitle}>Recipes</h1>
<p className={styles.pageDescription}>
Recipes are reusable workflows that package extensions, prompts, and settings together. Share proven workflows with your team and reproduce successful results consistently.
</p>
<!-- will replace with Recipe video once live -->
<!-- <div className="video-container margin-bottom--lg">
<iframe
width="100%"
height="400"
src="https://www.youtube.com/embed/D-DpDunrbpo"
title="Vibe coding with Goose"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
</div> -->
<div className={styles.categorySection}>
<h2 className={styles.categoryTitle}>📚 Documentation & Guides</h2>
<div className={styles.cardGrid}>
<Card
title="Shareable Recipes"
description="Share a Goose session setup (including tools, goals, and instructions) as a reusable recipe that others can launch with a single click."
link="/docs/guides/recipes/session-recipes"
/>
<Card
title="Recipe Reference Guide"
description="Complete technical reference for creating and customizing recipes in Goose via the CLI."
link="/docs/guides/recipes/recipe-reference"
/>
</div>
</div>
<div className={styles.categorySection}>
<h2 className={styles.categoryTitle}>🛠️ Tools & Generators</h2>
<div className={styles.cardGrid}>
<Card
title="Recipe Generator"
description="Interactive tool that creates a shareable Goose recipe URL that others can use to launch a session with your predefined settings."
link="/recipe-generator"
/>
<Card
title="Recipe Cookbook"
description="Browse our collection of ready-to-use recipes. Find and adapt recipes for common development scenarios."
link="/recipes"
/>
</div>
</div>
<div className={styles.categorySection}>
<h2 className={styles.categoryTitle}>📝 Featured Blog Posts</h2>
<div className={styles.cardGrid}>
<Card
title="Championship Driven Development"
description="Recipes to accelerate your developer team's workflow."
link="/blog/2025/05/09/developers-ai-playbook-for-team-efficiency"
/>
<Card
title="A Recipe for Success"
description="The value of scaling agentic workflows with recipes."
link="/blog/2025/05/06/recipe-for-success"
/>
</div>
</div>
documentation/docs/guides/recipes/recipe-reference.md
+221
View File
@@ -0,0 +1,221 @@
---
sidebar_position: 2
title: Recipe Reference Guide
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.
## Recipe File Format
Recipes can be defined in either:
- `.yaml` files (recommended)
- `.json` files
Files should be named either:
- `recipe.yaml`/`recipe.json`
- `<recipe_name>.yaml`/`<recipe_name>.json`
## Recipe Structure
### Required Fields
| Field | Type | Description |
|-------|------|-------------|
| `version` | String | The recipe format version (e.g., "1.0.0") |
| `title` | String | A short title describing the recipe |
| `description` | String | A detailed description of what the recipe does |
### Optional Fields
| Field | Type | Description |
|-------|------|-------------|
| `instructions` | String | Template instructions that can include parameter substitutions |
| `prompt` | String | A template prompt that can include parameter substitutions |
| `parameters` | Array | List of parameter definitions |
| `extensions` | Array | List of extension configurations |
## Parameters
Each parameter in the `parameters` array has the following structure:
### Required Parameter Fields
| Field | Type | Description |
|-------|------|-------------|
| `key` | String | Unique identifier for the parameter |
| `input_type` | String | Type of input (e.g., "string") |
| `requirement` | String | One of: "required", "optional", or "user_prompt" |
| `description` | String | Human-readable description of the parameter |
### Optional Parameter Fields
| Field | Type | Description |
|-------|------|-------------|
| `default` | String | Default value for optional parameters |
### Parameter Requirements
- `required`: Parameter must be provided when using the recipe
- `optional`: Can be omitted if a default value is specified
- `user_prompt`: Will interactively prompt the user for input if not provided
:::important
- Optional parameters MUST have a default value specified
- Required parameters cannot have default values
- Parameter keys must match any template variables used in instructions or prompt
:::
## 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:
### Extension Fields
| Field | Type | Description |
|-------|------|-------------|
| `type` | String | Type of extension (e.g., "stdio") |
| `name` | String | Unique name for the extension |
| `cmd` | String | Command to run the extension |
| `args` | Array | List of arguments for the command |
| `timeout` | Number | Timeout in seconds |
| `bundled` | Boolean | (Optional) Whether the extension is bundled with Goose |
| `description` | String | Description of what the extension does |
### Example Extension Configuration
```yaml
extensions:
- type: stdio
name: codesearch
cmd: uvx
args:
- mcp_codesearch@latest
timeout: 300
bundled: true
description: "Query https://codesearch.sqprod.co/ directly from goose"
- type: stdio
name: presidio
timeout: 300
cmd: uvx
args:
- 'mcp_presidio@latest'
description: "For searching logs using Presidio"
```
## Template Support
Recipes support Jinja-style template syntax in both `instructions` and `prompt` fields:
```yaml
instructions: "Follow these steps with {{ parameter_name }}"
prompt: "Your task is to {{ action }}"
```
Advanced template features include:
- Template inheritance using `{% extends "parent.yaml" %}`
- Blocks that can be defined and overridden:
```yaml
{% block content %}
Default content
{% endblock %}
```
## Built-in Parameters
| Parameter | Description |
|-----------|-------------|
| `recipe_dir` | Automatically set to the directory containing the recipe file |
## Complete Recipe Example
```yaml
version: "1.0.0"
title: "Example Recipe"
description: "A sample recipe demonstrating the format"
instructions: "Follow these steps with {{ required_param }} and {{ optional_param }}"
prompt: "Your task is to use {{ required_param }}"
parameters:
- key: required_param
input_type: string
requirement: required
description: "A required parameter example"
- key: optional_param
input_type: string
requirement: optional
default: "default value"
description: "An optional parameter example"
- key: interactive_param
input_type: string
requirement: user_prompt
description: "Will prompt user if not provided"
extensions:
- type: stdio
name: codesearch
cmd: uvx
args:
- mcp_codesearch@latest
timeout: 300
bundled: true
description: "Query codesearch directly from goose"
```
## Template Inheritance
Parent recipe (`parent.yaml`):
```yaml
version: "1.0.0"
title: "Parent Recipe"
description: "Base recipe template"
prompt: |
{% block prompt %}
Default prompt text
{% endblock %}
```
Child recipe:
```yaml
{% extends "parent.yaml" %}
{% block prompt %}
Modified prompt text
{% endblock %}
```
## Recipe Location
Recipes can be loaded from:
1. Local filesystem:
- Current directory
- Directories specified in `GOOSE_RECIPE_PATH` environment variable
2. GitHub repositories:
- Configure using `GOOSE_RECIPE_GITHUB_REPO` configuration key
- Requires GitHub CLI (`gh`) to be installed and authenticated
## Validation Rules
The following rules are enforced when loading recipes:
1. All template variables must have corresponding parameter definitions
2. Optional parameters must have default values
3. Parameter keys must be unique
4. Recipe files must be valid YAML or JSON
5. Required fields (version, title, description) must be present
## Error Handling
Common errors to watch for:
- Missing required parameters
- Optional parameters without default values
- Template variables without parameter definitions
- Invalid YAML/JSON syntax
- Missing required fields
- Invalid extension configurations
When these occur, Goose will provide helpful error messages indicating what needs to be fixed.
documentation/docs/guides/recipes/session-recipes.md
+416
View File
@@ -0,0 +1,416 @@
---
sidebar_position: 1
title: Shareable Recipes
description: "Share a Goose session setup (including tools, goals, and instructions) as a reusable recipe that others can launch with a single click"
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
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
<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**
3. In the dialog that appears:
- Name the 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)
</TabItem>
<TabItem value="cli" label="Goose CLI">
:::warning
You cannot create a recipe from an existing recipe session - the `/recipe` command will not work.
:::
### 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
```
If you want to specify a different name, you can provide it as an argument:
```sh
/recipe my-custom-recipe.yaml
```
<details>
<summary>recipe file structure</summary>
```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)
```
</details>
### 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
<details>
<summary>Example recipe with parameters</summary>
```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
instructions: |
You are a code reviewer specialized in {{ language }} development.
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-sonnet"
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
```
</details>
### Validate Recipe
[Exit the session](/docs/guides/managing-goose-sessions#exit-session) and run:
```sh
goose recipe validate recipe.yaml
```
Validation ensures that:
- All required fields are present
- Parameters are properly formatted
- Referenced extensions exist and are valid
- The YAML/JSON syntax is correct
### 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
```
</TabItem>
</Tabs>
## Edit Recipe
<Tabs>
<TabItem value="ui" label="Goose Desktop" default>
1. While in the session created from a recipe, click the menu icon **⋮** in the top right corner
2. Select **View recipe**
3. In the dialog that appears, you can edit the:
- Title
- Description
- Instructions
- Initial prompt
- Activities
4. Copy the new recipe URL. The original recipe and your current session are not affected by your edits.
5. Use and share the URL for your new recipe.
</TabItem>
<TabItem value="cli" label="Goose CLI">
Once the recipe file is created, you can open it with your preferred text editor and modify the value of any field.
</TabItem>
</Tabs>
## Use Recipe
<Tabs>
<TabItem value="ui" label="Goose Desktop" default>
There are two ways to use a recipe in Goose Desktop:
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
:::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
:::
</TabItem>
<TabItem value="cli" label="Goose CLI">
### 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](/docs/guides/config-file#global-settings).
:::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
:::
<Tabs>
<TabItem value="configure" label="Using goose configure" default>
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>
</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>
:::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
:::
### Schedule a Recipe
Automate Goose recipes by running them on a schedule.
**Create a schedule** - Create a scheduled cron job that runs the recipe on the specified cadence.
```bash
# Add a new scheduled recipe which runs every day at 9 AM
goose schedule add --id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml
```
The [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) follows the format "seconds minutes hours day-of-month month day-of-week".
See the [`schedule` command documentation](/docs/guides/goose-cli-commands#schedule) 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
## 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)
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.