documentation/docs/guides/context-engineering/custom-agents.md
Custom agents are reusable goose configurations for specific roles, behaviors, or areas of expertise. Each agent packages a name, description, optional model preference, and instructions so you can quickly ask goose to work with a specialized role such as code reviewer, documentation writer, test planner, or release assistant.
Use custom agents when you want the same role or behavior across multiple sessions without retyping the same instructions.
Agents are stored as Markdown files with YAML frontmatter. You can create or edit these files directly in your editor.
Global agents are available across goose sessions:
~/.agents/agents/
Project agents are available when goose is working in that project:
<project>/.agents/agents/
:::note Compatibility paths
goose also discovers agents from .goose/agents/, .claude/agents/, ~/.goose/agents/, ~/.claude/agents/, goose's platform-specific config agents directory, and project-local .agents/agents/. New shared agents should use .agents/agents/ for project agents or ~/.agents/agents/ for global agents.
:::
Create the directory if it does not already exist, then add a Markdown file for your agent:
---
name: code-reviewer
description: Reviews code for correctness, maintainability, and risk
model: gpt-5.5
---
You are a senior code reviewer. Review changes for correctness, maintainability, security, and test coverage. Be direct, prioritize issues by severity, and suggest concrete fixes.
The frontmatter supports:
| Field | Required | Description |
|---|---|---|
name | Yes | Name used to list, load, mention, or delegate to the agent. |
description | No | Short summary shown when listing agents. |
model | No | Preferred model for the agent. |
Only name is required in the frontmatter. description and model are optional. The Markdown body is the agent's instructions and should not be empty if you want the agent to appear as a usable source in chat.
After you create an agent file, start goose from a working directory where the agent can be discovered. Project agents are discovered from the current working directory, while global agents are discovered from your home/config directories.
In a goose chat session, ask goose to list available sources:
list available sources
This is a prompt to goose, not a terminal command. When source loading is available, goose lists discoverable agents alongside recipes and subrecipes.
You can invoke an agent by mentioning it by name:
@code-reviewer review the current diff
Or ask goose to use it:
Use the code-reviewer agent to review this pull request.
In chat interfaces with a mention picker, type @ and choose the agent by name, such as code-reviewer.
Use a custom agent when you want an isolated specialist to perform a task and return the result to the current conversation.
Delegate to code-reviewer: review the current diff and identify the highest-risk issues.
Or, if you are writing prompts that call the delegation tool directly, use the agent's name as the source:
Use the code-reviewer agent to review this pull request.
The delegated agent runs in a separate session with the instructions from the agent file. It can use the model specified in the agent frontmatter. Some interfaces also let you override settings such as model, provider, temperature, or max turns when you delegate.
Use an agent as loaded context when you want the current conversation to adopt the agent's instructions without creating a separate delegated session.
Load the code-reviewer agent, then review this change.
Loading an agent adds its instructions to the current conversation context. Delegating to an agent runs it separately and returns a result.
---
name: code-reviewer
description: Reviews code for correctness, maintainability, and risk
model: gpt-5.5
---
You are a senior code reviewer. Review changes for correctness, maintainability, security, and test coverage.
Prioritize:
- bugs and correctness issues
- security or privacy risks
- missing tests
- unnecessary complexity
- unclear naming or structure
Be direct. Group findings by severity and suggest concrete fixes.
---
name: docs-writer
description: Writes clear developer documentation
---
You are a developer documentation writer. Explain features clearly, use practical examples, and avoid marketing language.
When writing docs:
- start with what the user can accomplish
- show the shortest working example
- explain important options after the example
- call out limitations and prerequisites
| Use | Best fit |
|---|---|
| Change goose's role, tone, or instructions for a task | Custom agent |
| Teach goose a reusable workflow or domain-specific procedure it can load on demand | Skill |
| Package a repeatable task with prompts, settings, extensions, and parameters | Recipe |
| Delegate work to another isolated goose instance | Subagent |
Agents define who goose should be for a task. Skills and recipes define what goose should know or do.
Not directly. Custom agents are reusable roles, not scheduled jobs. To run something on a schedule, create a recipe and schedule the recipe. If you want the scheduled job to behave like a custom agent, put the agent's instructions into the recipe or have the recipe delegate to that agent.
No. A custom agent defines who goose should be for a task: its role, behavior, instructions, and optional model preference. It does not define a step-by-step workflow. Use a recipe when you need repeatable steps, parameters, extension configuration, or scheduled execution.
Yes. A custom agent can use skills that are available in the session. Skills are still discovered and loaded through goose's normal skill behavior, so the agent can use them when your request matches a skill or when you explicitly ask for one.
A custom agent does not contain or automatically run a recipe. You can start goose with a recipe, ask goose to load or delegate a recipe when the relevant tools are available, or create a recipe that uses custom-agent instructions as part of its workflow.
Yes. Custom agents can use the MCP servers and extensions that are enabled in the current session. The agent file itself does not define a separate MCP server list. If you need a reusable setup with a specific extension set, use a recipe.
Yes, when delegation tools are available in the session. A custom agent can ask goose to delegate work to a subagent just like the default goose agent can. Delegated subagents run in isolated sessions and do not automatically inherit the full parent conversation.
Yes, through delegation. For example, one custom agent can delegate a task to another custom agent by name if that agent is discoverable. This is useful for one-off collaboration between specialized agents.
For repeatable chains, use a recipe that explicitly defines the sequence, such as delegating first to a reviewer agent, then to a docs agent, then combining the results.