Recipes

Recipes are YAML files that package complete Goose experiences—instructions, extensions, parameters, and prompts—into reusable, shareable configurations. They enable you to create standardized workflows without writing code.

What is a Recipe?

A recipe defines:

Instructions: The agent’s system prompt and behavior
Extensions: Which tools the agent can use
Parameters: User-configurable inputs
Settings: Model, temperature, and other configuration
Activities: Quick-start suggestions shown in the UI
Sub-recipes: Reusable workflow components
Prompt: Initial message to start the conversation

# example-recipe.yaml
version: 1.0.0
title: Code Review Assistant
description: AI assistant for thorough code reviews

instructions: |
  You are a code review assistant. Review code for:
  - Security vulnerabilities
  - Performance issues
  - Code style and best practices
  - Potential bugs
  
  Always provide specific examples and suggestions.

extensions:
  - type: builtin
    name: developer

settings:
  goose_provider: anthropic
  goose_model: claude-sonnet-4-20250514
  temperature: 0.2
  max_turns: 30

activities:
  - "Review the changes in my last commit"
  - "Check for security issues in auth.rs"
  - "Analyze performance of database queries"

prompt: |
  I need you to review some code. What would you like to review?

Recipe Structure

Required Fields

version: 1.0.0                      # Semantic version (currently 1.0.0)
title: Recipe Name                  # Short, descriptive title
description: What this recipe does  # Longer explanation

Instructions

The system prompt that defines agent behavior:

instructions: |
  You are a specialized assistant for data analysis.
  
  Your capabilities:
  - Load and analyze CSV/JSON data files
  - Generate statistical summaries
  - Create visualizations using the autovisualiser extension
  - Write analysis reports
  
  Always:
  - Explain your analysis methodology
  - Cite data sources
  - Visualize key findings
  - Save reports to ./reports/ directory

Extensions

Define which tools the agent can access:

extensions:
  # Built-in extension
  - type: builtin
    name: developer
    description: File operations and shell commands
  
  # External MCP server
  - type: stdio
    name: brave-search
    cmd: npx
    args: ["-y", "@modelcontextprotocol/server-brave-search"]
    env:
      BRAVE_API_KEY: "${BRAVE_API_KEY}"
    description: Web search capabilities
  
  # Remote service
  - type: sse
    name: company-tools
    url: https://tools.company.internal/mcp
    headers:
      Authorization: "Bearer ${COMPANY_TOKEN}"

Parameters

Make recipes customizable with user inputs:

parameters:
  # Required string parameter
  - key: github_repo
    input_type: string
    requirement: required
    description: "GitHub repository (owner/repo)"
    validation:
      pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
  
  # Optional select parameter
  - key: severity
    input_type: select
    requirement: optional
    default: "medium"
    options: ["low", "medium", "high", "critical"]
    description: "Minimum severity to report"
  
  # Number parameter
  - key: max_results
    input_type: number
    requirement: optional
    default: 10
    description: "Maximum number of results"
  
  # Boolean parameter
  - key: include_tests
    input_type: boolean
    requirement: optional
    default: true
    description: "Include test files in analysis"
  
  # Date parameter
  - key: since_date
    input_type: date
    requirement: optional
    description: "Only analyze changes since this date"
  
  # File parameter (imports file contents)
  - key: config_file
    input_type: file
    requirement: optional
    description: "Configuration file to use"

Using Parameters

Parameters use Jinja2 template syntax:

parameters:
  - key: repo_url
    input_type: string
    requirement: required
  - key: branch
    input_type: string
    requirement: optional
    default: "main"

instructions: |
  You are analyzing the repository: {{ repo_url }}
  Focus on the {{ branch }} branch.
  
prompt: |
  Clone {{ repo_url }} and analyze the {{ branch }} branch.
  
  {% if branch != "main" %}
  Pay special attention to differences from main branch.
  {% endif %}

Settings

Configure model and behavior:

settings:
  goose_provider: anthropic              # AI provider
  goose_model: claude-sonnet-4-20250514  # Model name
  temperature: 0.2                       # Creativity (0.0-1.0)
  max_turns: 50                          # Conversation limit

Activities

Quick-start suggestions shown in the UI:

activities:
  - "Analyze the latest commit"
  - "Find security vulnerabilities"
  - "Generate test coverage report"
  - "Refactor the authentication module"

Prompt

Initial message to start the session:

prompt: |
  Please review the code in {{ directory }} and provide a summary of:
  1. Overall code quality
  2. Security issues found
  3. Performance concerns
  4. Recommendations for improvement

Response Schema

Define structured output format:

response:
  json_schema:
    type: object
    properties:
      summary:
        type: string
        description: High-level summary of findings
      issues:
        type: array
        items:
          type: object
          properties:
            severity:
              type: string
              enum: ["low", "medium", "high", "critical"]
            file:
              type: string
            line:
              type: number
            description:
              type: string
            recommendation:
              type: string
    required: ["summary", "issues"]

The agent uses the final_output tool to return JSON matching this schema.

Sub-Recipes

Sub-recipes are reusable workflow components that can be invoked by the main recipe:

# main-recipe.yaml
title: Full Stack Analysis

sub_recipes:
  # Define available sub-recipes
  - name: "analyze_frontend"
    path: "./sub-recipes/frontend-analyzer.yaml"
    description: "Analyze React components and state"
  
  - name: "analyze_backend"
    path: "./sub-recipes/backend-analyzer.yaml"
    description: "Analyze API endpoints and database"
  
  - name: "security_scan"
    path: "./sub-recipes/security-scanner.yaml"
    sequential_when_repeated: true  # Don't run in parallel
    values:  # Pre-fill parameters
      severity: "high"
      include_deps: "true"

instructions: |
  You have access to specialized sub-recipes for analyzing different
  parts of the application. Use them to break down the analysis.

prompt: |
  Analyze this full-stack application:
  
  1. Use analyze_frontend sub-recipe for the React app
  2. Use analyze_backend sub-recipe for the API
  3. Run security_scan on both
  4. Synthesize findings into a unified report

Sub-recipes are invoked using the subagent tool:

# The AI calls:
subagent(
  subrecipe: "analyze_frontend",
  parameters: {"directory": "./src/components"}
)

Sub-Recipe Options

sub_recipes:
  - name: "task_name"
    path: "./path/to/recipe.yaml"      # Relative to main recipe
    description: "What this sub-recipe does"  # Shown to AI
    
    values:  # Pre-filled parameter values
      param1: "value1"
      param2: "value2"
    
    sequential_when_repeated: true     # Run sequentially, not in parallel

Complete Example: Multi-Stage Workflow

# ci-analysis.yaml
version: 1.0.0
title: CI/CD Pipeline Analyzer
description: Comprehensive analysis of CI/CD configurations and performance

parameters:
  - key: repo_path
    input_type: string
    requirement: required
    description: "Path to repository root"
  
  - key: ci_platform
    input_type: select
    requirement: required
    options: ["github-actions", "gitlab-ci", "jenkins", "circleci"]
    description: "CI/CD platform used"
  
  - key: analyze_performance
    input_type: boolean
    requirement: optional
    default: true
    description: "Include performance analysis"

sub_recipes:
  - name: "analyze_config"
    path: "./sub-recipes/ci-config-analyzer.yaml"
    description: "Analyze CI configuration files"
  
  - name: "analyze_performance"
    path: "./sub-recipes/ci-performance-analyzer.yaml"
    description: "Analyze build times and bottlenecks"
  
  - name: "security_check"
    path: "./sub-recipes/ci-security-checker.yaml"
    sequential_when_repeated: true
    description: "Check for security issues in CI/CD"

extensions:
  - type: builtin
    name: developer
  
  - type: stdio
    name: github
    cmd: uvx
    args: ["mcp-server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"

settings:
  goose_provider: anthropic
  goose_model: claude-sonnet-4-20250514
  temperature: 0.1
  max_turns: 40

instructions: |
  You are a CI/CD pipeline expert. Your job is to analyze the pipeline
  configuration and provide actionable recommendations.
  
  Analysis workflow:
  1. Use analyze_config sub-recipe to review configuration
  2. If analyze_performance is true, run performance analysis
  3. Always run security_check sub-recipe
  4. Synthesize findings into a structured report
  
  Report format:
  - Executive summary
  - Configuration issues (if any)
  - Performance bottlenecks (if analyzed)
  - Security findings
  - Prioritized recommendations

activities:
  - "Analyze GitHub Actions workflows"
  - "Find slow build steps"
  - "Check for security issues"
  - "Optimize build times"

prompt: |
  Please analyze the {{ ci_platform }} configuration in {{ repo_path }}.
  
  {% if analyze_performance %}
  Include detailed performance analysis of build times.
  {% endif %}
  
  Focus on:
  - Configuration best practices
  - Security concerns
  - Optimization opportunities
  
  Provide specific, actionable recommendations.

response:
  json_schema:
    type: object
    properties:
      summary:
        type: string
      config_issues:
        type: array
        items:
          type: object
          properties:
            severity: {type: string}
            issue: {type: string}
            recommendation: {type: string}
      performance_findings:
        type: object
        properties:
          avg_build_time: {type: string}
          bottlenecks: {type: array}
          optimization_potential: {type: string}
      security_findings:
        type: array
        items:
          type: object
          properties:
            risk: {type: string}
            description: {type: string}
            remediation: {type: string}
      recommendations:
        type: array
        items:
          type: object
          properties:
            priority: {type: string}
            action: {type: string}
            impact: {type: string}
    required: ["summary", "recommendations"]

retry:
  max_retries: 3
  initial_delay_ms: 1000
  max_delay_ms: 10000
  backoff_multiplier: 2.0

Recipe Loading

Recipes can be loaded from multiple sources:

Local File

goose run --recipe ./my-recipe.yaml

URL

goose run --recipe https://example.com/recipes/code-review.yaml

Recipe Registry

# Future: Recipe repository integration
goose run --recipe @goose/code-review

Recipe Validation

Goose validates recipes on load:

// From crates/goose/src/recipe/validate_recipe.rs

pub fn validate_recipe(recipe: &Recipe) -> Result<()> {
    // 1. Check required fields
    if recipe.title.is_empty() {
        return Err(anyhow!("Recipe must have a title"));
    }
    
    // 2. Validate at least one of instructions or prompt
    if recipe.instructions.is_none() && recipe.prompt.is_none() {
        return Err(anyhow!("Recipe must have instructions or prompt"));
    }
    
    // 3. Validate parameters
    for param in recipe.parameters.iter().flatten() {
        validate_parameter(param)?;
    }
    
    // 4. Validate extensions
    for ext in recipe.extensions.iter().flatten() {
        ext.validate()?;
    }
    
    // 5. Validate sub-recipes exist
    for sub_recipe in recipe.sub_recipes.iter().flatten() {
        validate_sub_recipe_path(&sub_recipe.path)?;
    }
    
    // 6. Validate response schema (if present)
    if let Some(response) = &recipe.response {
        validate_json_schema(&response.json_schema)?;
    }
    
    Ok(())
}

Validation errors are shown with clear messages:

Error: Recipe validation failed
  - Parameter 'github_repo' has invalid type 'invalid'
  - Sub-recipe 'missing.yaml' not found at path ./sub-recipes/missing.yaml
  - Response schema is not valid JSON Schema

Recipe Templates

Jinja2 templating is supported in:

instructions
prompt
Extension environment variables

parameters:
  - key: project_name
    input_type: string
    requirement: required
  - key: language
    input_type: select
    options: ["python", "rust", "javascript"]
    requirement: required

instructions: |
  You are setting up a {{ language }} project named {{ project_name }}.
  
  {% if language == "python" %}
  Use Poetry for dependency management.
  Set up pytest for testing.
  {% elif language == "rust" %}
  Use Cargo for builds.
  Set up cargo test.
  {% else %}
  Use npm for packages.
  Set up Jest for testing.
  {% endif %}

Using Recipes Programmatically

Via REST API

// Create session with recipe
const response = await fetch('http://localhost:3000/sessions', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    recipe: {
      title: "Code Review",
      instructions: "Review code for security issues",
      extensions: [{type: "builtin", name: "developer"}]
    },
    recipeValues: {
      severity: "high",
      repo_url: "https://github.com/user/repo"
    }
  })
});

Via Agent Client Protocol (ACP)

# Create session with recipe
response = client.send_request("session/new", {
    "cwd": "/path/to/project",
    "recipe": {
        "title": "Analysis Task",
        "instructions": "Analyze the codebase",
        "extensions": [{"type": "builtin", "name": "developer"}]
    }
})

Recipe Best Practices

Write clear, specific instructions

# Good: Specific behavior and expectations
instructions: |
  You are a database migration assistant.
  
  When creating migrations:
  1. Always add both 'up' and 'down' migrations
  2. Include transaction handling
  3. Add comments explaining complex changes
  4. Test migrations before committing
  
  Never:
  - Drop tables without explicit confirmation
  - Modify production data
  - Create migrations that can't be rolled back

# Bad: Vague instructions
instructions: "Help with database tasks"

Use parameters for reusability

# Make recipes reusable across different contexts
parameters:
  - key: environment
    input_type: select
    options: ["development", "staging", "production"]
  - key: target_service
    input_type: string

instructions: |
  You are deploying {{ target_service }} to {{ environment }}.
  
  {% if environment == "production" %}
  CRITICAL: This is production. Require manual approval for all changes.
  {% endif %}

Break complex workflows into sub-recipes

# Main orchestrator recipe
sub_recipes:
  - name: "gather_data"
    path: "./steps/01-gather.yaml"
  - name: "process_data"
    path: "./steps/02-process.yaml"
  - name: "generate_report"
    path: "./steps/03-report.yaml"

# Each sub-recipe is focused and testable

Choose appropriate models

# Use powerful models for complex reasoning
settings:
  goose_model: claude-sonnet-4-20250514
  temperature: 0.1  # Low temperature for consistency

# Use cheaper models for simple tasks in sub-recipes
sub_recipes:
  - name: "count_files"
    path: "./simple-task.yaml"
    values:
      model: "gpt-4o-mini"  # Cheaper for simple tasks

Provide helpful activities

# Activities are shown as quick-start buttons in UI
activities:
  - "Review the latest PR"  # Clear, actionable
  - "Find security vulnerabilities in auth/"  # Specific
  - "Generate test coverage report"  # Common task
  
# Not: "Do stuff", "Help me"  # Too vague

Use response schemas for structured output

# When you need structured data (not conversational output)
response:
  json_schema:
    type: object
    properties:
      findings: {type: array}
      severity: {type: string}
      recommendation: {type: string}
    required: ["findings"]

# Agent will use final_output tool to return valid JSON

Recipe Distribution

Recipes are just YAML files, so you can:

Commit to repositories

git add recipes/
git commit -m "Add code review recipe"

Host on web servers

goose run --recipe https://company.com/recipes/deploy.yaml

Bundle with custom distributions

your-goose/
├── recipes/
│   ├── legal-review.yaml
│   ├── contract-analysis.yaml
│   └── due-diligence.yaml
└── ...

Share in documentation

## Code Review Recipe

```yaml
version: 1.0.0
title: Security-Focused Code Review
# ...
```

Versioning Recipes

# Use semantic versioning
version: 1.2.0  # major.minor.patch

author:
  contact: "team@company.com"
  metadata: |
    Version 1.2.0 changes:
    - Added security_scan sub-recipe
    - Improved performance analysis
    - Fixed parameter validation
    
    Version 1.1.0 changes:
    - Added multi-language support
    
    Version 1.0.0:
    - Initial release

Next Steps

Example Recipes

Browse ready-to-use recipes

Creating Recipes

Learn to build custom recipes

Subagents

Use sub-recipes with subagents

Extensions

Add tools to your recipes

Getting Started

Core Concepts

User Guides

Advanced

Troubleshooting

What is a Recipe?

Recipe Structure

Required Fields

Instructions

Extensions

Parameters

Using Parameters

Settings

Activities

Prompt

Response Schema

Sub-Recipes

Sub-Recipe Options

Complete Example: Multi-Stage Workflow

Recipe Loading

Local File

URL

Recipe Registry

Recipe Validation

Recipe Templates

Using Recipes Programmatically

Via REST API

Via Agent Client Protocol (ACP)

Recipe Best Practices

Recipe Distribution

Versioning Recipes

Next Steps

Example Recipes

Creating Recipes

Subagents

Extensions

​What is a Recipe?

​Recipe Structure

​Required Fields

​Instructions

​Extensions

​Parameters

​Using Parameters

​Settings

​Activities

​Prompt

​Response Schema

​Sub-Recipes

​Sub-Recipe Options

​Complete Example: Multi-Stage Workflow

​Recipe Loading

​Local File

​URL

​Recipe Registry

​Recipe Validation

​Recipe Templates

​Using Recipes Programmatically

​Via REST API

​Via Agent Client Protocol (ACP)

​Recipe Best Practices

​Recipe Distribution

​Sharing Recipes

​Versioning Recipes

​Next Steps

Example Recipes

Creating Recipes

Subagents

Extensions

What is a Recipe?

Recipe Structure

Required Fields

Instructions

Extensions

Parameters

Using Parameters

Settings

Activities

Prompt

Response Schema

Sub-Recipes

Sub-Recipe Options

Complete Example: Multi-Stage Workflow

Recipe Loading

Local File

URL

Recipe Registry

Recipe Validation

Recipe Templates

Using Recipes Programmatically

Via REST API

Via Agent Client Protocol (ACP)

Recipe Best Practices

Recipe Distribution

Sharing Recipes

Versioning Recipes

Next Steps