mirror of
https://github.com/aljazceru/goose.git
synced 2025-12-18 14:44:21 +01:00
Add a reference for recipes (#3099)
Co-authored-by: Douwe Osinga <douwe@squareup.com> Co-authored-by: Rizel Scarlett <rizel@squareup.com>
This commit is contained in:
Douwe Osinga
221
documentation/docs/guides/recipe-reference.md
Normal file
221
documentation/docs/guides/recipe-reference.md
Normal file
@@ -0,0 +1,221 @@
|
||||
---
|
||||
sidebar_position: 18
|
||||
title: Recipe Reference Guide
|
||||
sidebar_label: Recipe Reference Guide
|
||||
---
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user