Docs/json recipe support (#5492)
This commit is contained in:
dianed-square
@@ -1,9 +1,12 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Recipe Reference Guide
|
||||
description: Complete technical reference for creating and customizing recipes in goose via the CLI.
|
||||
description: Complete technical reference for creating and customizing recipes in goose
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
Recipes are reusable goose configurations that package up a specific setup so it can be easily shared and launched by others.
|
||||
|
||||
## Recipe File Format
|
||||
@@ -12,11 +15,7 @@ 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`
|
||||
|
||||
After creating recipe files, you can use the [`goose recipe` subcommands](/docs/guides/goose-cli-commands#recipe) to validate, share, and open your recipes.
|
||||
See [Shareable Recipes](/docs/guides/recipes/session-recipes) to learn how to create, use, and manage recipes.
|
||||
|
||||
### CLI and Desktop Formats
|
||||
|
||||
@@ -25,12 +24,18 @@ goose recipes use two formats:
|
||||
- **CLI Format**: Recipe fields (like `title`, `description`, `instructions`) are at the root level of the YAML/JSON file. This format is used when recipes are created via the CLI `/recipe` command and [Recipe Generator](/recipe-generator) YAML option.
|
||||
- **Desktop Format**: Recipe fields are nested inside a `recipe` object, with additional metadata fields at the root level. This format is used when recipes are created from goose Desktop.
|
||||
|
||||
The CLI automatically detects and handles both formats when running `goose run --recipe <file>` and `goose recipe` commands. The Desktop can [import](/docs/guides/recipes/storing-recipes#importing-recipes) and use YAML recipes (or deeplinks) in either CLI or Desktop format.
|
||||
The CLI automatically detects and handles both formats for `.yaml` and `.json` recipe files when running `goose run --recipe <file>` and `goose recipe` commands. The Desktop can [import](/docs/guides/recipes/storing-recipes#importing-recipes) `.yaml`, `.yml`, and `.json` recipe files (or deeplinks) in either CLI or Desktop format.
|
||||
|
||||
<details>
|
||||
<summary>Format Examples</summary>
|
||||
|
||||
**CLI Format:**
|
||||
Recipes can be written in either YAML or JSON format. Both formats follow the same schema structure.
|
||||
|
||||
### CLI Format
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="yaml" label="YAML" default>
|
||||
|
||||
```yaml
|
||||
version: "1.0.0"
|
||||
title: "Code Review Assistant"
|
||||
@@ -40,7 +45,28 @@ prompt: "Review the code in this repository"
|
||||
extensions: []
|
||||
```
|
||||
|
||||
**Desktop Format:**
|
||||
</TabItem>
|
||||
<TabItem value="json" label="JSON">
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"title": "Code Review Assistant",
|
||||
"description": "Automated code review with best practices",
|
||||
"instructions": "You are a code reviewer...",
|
||||
"prompt": "Review the code in this repository",
|
||||
"extensions": []
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Desktop Format
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="yaml" label="YAML" default>
|
||||
|
||||
```yaml
|
||||
name: "Code Review Assistant"
|
||||
recipe:
|
||||
@@ -55,6 +81,29 @@ lastModified: 2025-07-02T03:46:46.778Z
|
||||
isArchived: false
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="json" label="JSON">
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Code Review Assistant",
|
||||
"recipe": {
|
||||
"version": "1.0.0",
|
||||
"title": "Code Review Assistant",
|
||||
"description": "Automated code review with best practices",
|
||||
"instructions": "You are a code reviewer...",
|
||||
"prompt": "Review the code in this repository",
|
||||
"extensions": []
|
||||
},
|
||||
"isGlobal": true,
|
||||
"lastModified": "2025-07-02T03:46:46.778Z",
|
||||
"isArchived": false
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::note
|
||||
goose automatically adds metadata fields to recipes saved from the Desktop app.
|
||||
:::
|
||||
@@ -238,6 +287,9 @@ The `extensions` field allows you to specify which Model Context Protocol (MCP)
|
||||
|
||||
### Example Extension Configuration
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="yaml" label="YAML" default>
|
||||
|
||||
```yaml
|
||||
extensions:
|
||||
- type: stdio
|
||||
@@ -268,6 +320,45 @@ extensions:
|
||||
description: "GitHub MCP extension for repository operations"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="json" label="JSON">
|
||||
|
||||
```json
|
||||
{
|
||||
"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"],
|
||||
"available_tools": ["query_logs"]
|
||||
},
|
||||
{
|
||||
"type": "stdio",
|
||||
"name": "github-mcp",
|
||||
"cmd": "github-mcp-server",
|
||||
"args": [],
|
||||
"env_keys": ["GITHUB_PERSONAL_ACCESS_TOKEN"],
|
||||
"timeout": 60,
|
||||
"description": "GitHub MCP extension for repository operations"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Extension Secrets
|
||||
|
||||
This feature is only available through the CLI.
|
||||
@@ -516,12 +607,15 @@ sub_recipes:
|
||||
|
||||
## Complete Recipe Example
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="yaml" label="YAML" default>
|
||||
|
||||
```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 }}"
|
||||
prompt: "Your task is to use {{ required_param }} with {{ interactive_param }}"
|
||||
parameters:
|
||||
- key: required_param
|
||||
input_type: string
|
||||
@@ -576,9 +670,92 @@ response:
|
||||
description: "Additional details of steps taken"
|
||||
required:
|
||||
- result
|
||||
- status
|
||||
- details
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="json" label="JSON">
|
||||
|
||||
```json
|
||||
{
|
||||
"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 }} with {{ interactive_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"
|
||||
}
|
||||
],
|
||||
"settings": {
|
||||
"goose_provider": "anthropic",
|
||||
"goose_model": "claude-sonnet-4-20250514",
|
||||
"temperature": 0.7
|
||||
},
|
||||
"retry": {
|
||||
"max_retries": 3,
|
||||
"timeout_seconds": 30,
|
||||
"checks": [
|
||||
{
|
||||
"type": "shell",
|
||||
"command": "echo 'Task validation check passed'"
|
||||
}
|
||||
],
|
||||
"on_failure": "echo 'Retry attempt failed, cleaning up...'"
|
||||
},
|
||||
"response": {
|
||||
"json_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"result": {
|
||||
"type": "string",
|
||||
"description": "The main result of the task"
|
||||
},
|
||||
"details": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Additional details of steps taken"
|
||||
}
|
||||
},
|
||||
"required": ["result", "details"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Template Inheritance
|
||||
|
||||
Parent recipe (`parent.yaml`):
|
||||
@@ -614,13 +791,16 @@ Recipes can be loaded from:
|
||||
|
||||
## Validation Rules
|
||||
|
||||
The following rules are enforced when loading recipes:
|
||||
Recipe files must be valid YAML or JSON. In addition, the following [validation rules](https://github.com/block/goose/blob/main/crates/goose/src/recipe/validate_recipe.rs) are enforced when loading recipes and are also checked by the [`goose recipe validate` subcommand](/docs/guides/goose-cli-commands#recipe):
|
||||
|
||||
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
|
||||
- Required `title` and `description` fields must be present
|
||||
- At least one of `instructions` or `prompt` must be present
|
||||
- All template variables must have corresponding parameter definitions
|
||||
- Parameter keys must be unique (not enforced, but required for proper functionality)
|
||||
- All defined parameters must be used in template variables (no unused parameters)
|
||||
- Optional parameters must have default values
|
||||
- File parameters cannot have default values (prevents importing sensitive files)
|
||||
- `response.json_schema` must be a valid JSON schema if specified
|
||||
|
||||
## Error Handling
|
||||
|
||||
|
||||
Reference in New Issue
Block a user