> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipes

> Pre-configured workflows and agent behaviors packaged as YAML files

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

```yaml theme={null}
# 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

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
activities:
  - "Analyze the latest commit"
  - "Find security vulnerabilities"
  - "Generate test coverage report"
  - "Refactor the authentication module"
```

### Prompt

Initial message to start the session:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
# 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:

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

### Sub-Recipe Options

```yaml theme={null}
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

```yaml theme={null}
# 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

```bash theme={null}
goose run --recipe ./my-recipe.yaml
```

### URL

```bash theme={null}
goose run --recipe https://example.com/recipes/code-review.yaml
```

### Recipe Registry

```bash theme={null}
# Future: Recipe repository integration
goose run --recipe @goose/code-review
```

## Recipe Validation

Goose validates recipes on load:

```rust theme={null}
// 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

```yaml theme={null}
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

```typescript theme={null}
// 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)

```python theme={null}
# 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

<AccordionGroup>
  <Accordion title="Write clear, specific instructions">
    ```yaml theme={null}
    # 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"
    ```
  </Accordion>

  <Accordion title="Use parameters for reusability">
    ```yaml theme={null}
    # 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 %}
    ```
  </Accordion>

  <Accordion title="Break complex workflows into sub-recipes">
    ```yaml theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Choose appropriate models">
    ```yaml theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Provide helpful activities">
    ```yaml theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Use response schemas for structured output">
    ```yaml theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

## Recipe Distribution

### Sharing Recipes

Recipes are just YAML files, so you can:

1. **Commit to repositories**
   ```bash theme={null}
   git add recipes/
   git commit -m "Add code review recipe"
   ```

2. **Host on web servers**
   ```bash theme={null}
   goose run --recipe https://company.com/recipes/deploy.yaml
   ```

3. **Bundle with custom distributions**
   ```
   your-goose/
   ├── recipes/
   │   ├── legal-review.yaml
   │   ├── contract-analysis.yaml
   │   └── due-diligence.yaml
   └── ...
   ```

4. **Share in documentation**
   ````markdown theme={null}
   ## Code Review Recipe

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

### Versioning Recipes

```yaml theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Example Recipes" icon="book" href="/guides/recipes">
    Browse ready-to-use recipes
  </Card>

  <Card title="Creating Recipes" icon="pencil" href="/api/cli/recipe">
    Learn to build custom recipes
  </Card>

  <Card title="Subagents" icon="robot" href="/concepts/agents#subagents">
    Use sub-recipes with subagents
  </Card>

  <Card title="Extensions" icon="puzzle-piece" href="/concepts/extensions">
    Add tools to your recipes
  </Card>
</CardGroup>