Unified Tooling for Recipes, Subrecipes, Claude Skills, and Claude Subagents

[tlongwell-block]

This proposal introduces unified tools that replace subagent and loadSkill with a cleaner mental model:

Tool	Purpose	Mental Model
load	Inject into current context	"Teach me this"
delegate	Run in isolated subagent	"Do this for me"

Key insight: The tool determines the execution mode, not the file format.

Any source (goose recipe, Claude Skill, Claude Subagent) can be used with either tool. A skill can be loaded for reference OR delegated as a specialized subagent. A recipe can be delegated to run OR loaded to learn its approach.

The Problem

Current tools have confusing names and limited interoperability:

• subagent only accepts subrecipes or ad-hoc instructions
• loadSkill only accepts skills by name
• Can't load a recipe into context without running it
• Can't delegate a skill as a subagent task
• No support for Claude Subagent files
• No way to discover available sources

The Solution

Any source (recipe, skill, Claude Subagent) can be used with either tool:

• A skill can be loaded (add patterns to my knowledge) OR delegated (use these patterns to review my code)
• A recipe can be delegated (run this workflow) OR loaded (teach me this workflow's approach)
• A Claude Subagent can be delegated (let this persona handle it) OR loaded (adopt this persona's expertise)

Proposed API

delegate Tool

delegate(instructions)                               # Ad-hoc task
delegate(instructions, extensions)                   # Ad-hoc with tool filtering
delegate(instructions, extensions, settings)         # Ad-hoc with model override
delegate(source)                                     # Run recipe, skill, or agent by name
delegate(source, parameters)                         # Recipe with parameters
delegate(source, instructions)                       # Source with additional context
delegate(source, instructions, extensions, settings) # Full control

load Tool

load()                                               # List all available sources
load(source)                                         # Load by name into current context

Examples

// List what's available
{"name": "load", "arguments": {}}

// Load a skill's knowledge into context
{"name": "load", "arguments": {"source": "rust-patterns"}}

// Delegate a recipe to run in isolation
{"name": "delegate", "arguments": {"source": "security-review"}}

// Use a skill as a specialized subagent
{"name": "delegate", "arguments": {
  "source": "rust-patterns",
  "instructions": "Review src/auth.rs using these patterns"
}}

// Ad-hoc task
{"name": "delegate", "arguments": {
  "instructions": "Find all TODO comments in the codebase"
}}

Discovery

Calling load() with no arguments scans the filesystem and returns all available sources:

Available sources for load/delegate:

Recipes:
• security-review - Review code for security vulnerabilities
• code-quality - Analyze code quality metrics

Skills:
• rust-patterns - Common Rust patterns and idioms
• api-guidelines - API design best practices

Agents:
• code-reviewer - Expert code reviewer for PR reviews

Subrecipes:
• jira-ticket - Create Jira tickets from requirements

Use load(source: "name") to load into context.
Use delegate(source: "name") to run as subagent.

The load tool description also shows the top 10 available sources for quick reference.

Source Resolution

Users reference sources by name only (not filename):

{"source": "security-review"}  // Not "security-review.yaml"

Resolution priority:

1. Subrecipes (parent recipe's sub_recipes array)
2. Local recipes (.goose/recipes/)
3. Local skills (.goose/skills/*/SKILL.md)
4. Local agents (.goose/agents/, .claude/agents/)
5. Global recipes/skills/agents (~/.config/goose/)

Claude Subagent Compatibility

This proposal adds support for Claude Subagent files (.md with frontmatter):

---
name: code-reviewer
description: Expert code reviewer
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer...

Claude's tools are mapped to goose extensions, and model shorthand (sonnet, opus, haiku) is translated to full model names.

Implementation

Rename subagent -> delegate
Rename loadSkill -> load

Add support for parsing Claude Subagent files and Claude Skill files into internal recipe representations.

[taniandjerry]

Wanted to tag @block/goose-maintainers in case you didn't see this and had anything to add!