vrr/goose
2
0
Fork 0
mirror of https://github.com/block/goose.git synced 2026-07-09 16:09:22 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 22

docs: correct custom agents guide (#9947)

Browse source
This commit is contained in:
Angie Jones 2026-06-22 17:43:03 -05:00 • committed by GitHub
parent 20231531ab
commit bc8609485b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 99 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

169
documentation/docs/guides/context-engineering/custom-agents.md
View file

@ -4,48 +4,13 @@ sidebar_position: 3
sidebar_label: Custom Agents
---
Custom agents are reusable goose configurations for specific roles, behaviors, or areas of expertise. Each agent packages a name, system prompt, and optional metadata such as provider, model, and avatar settings so you can quickly switch goose into a specialized mode such as code reviewer, documentation writer, test planner, or release assistant.
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.
## Create an Agent in goose Desktop
## Create an Agent File
In goose Desktop, open **Agents** from the sidebar and select **New Agent**.
An agent includes:
| Field | Description |
|---|---|
| **Display Name** | The name shown in the Agents page and chat selector. |
| **Avatar** | Optional visual identifier for the agent. |
| **System Prompt** | The instructions goose uses when this agent is active. |
| **Provider** | Optional provider preference for this agent. |
| **Model** | Optional model preference for this agent. |
The system prompt is the most important field. It should describe the agent's role, expectations, constraints, and output style.
```text title="Example system prompt"
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.
```
After saving, the agent appears in the Agents page and can be selected from the chat agent picker.
## Manage Existing Agents
From the Agents page, you can:
- **View** an agent's prompt and model settings
- **Edit** writable agents
- **Duplicate** an agent to create a variation
- **Delete** agents you no longer need
- **Export** an agent as a portable JSON file
- **Import** an agent from a JSON file
Read-only agents, such as built-in agents or agents loaded from read-only roots, can be viewed but cannot be edited directly. Duplicate a read-only agent if you want to customize it.
## Agent Files
Agents are stored as Markdown files with YAML frontmatter. You can create or edit these files directly if you prefer managing agents in your editor.
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:
@ -59,13 +24,17 @@ Project agents are available when goose is working in that project:
<project>/.agents/agents/
```
A minimal agent file looks like this:
:::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:
```markdown title="~/.agents/agents/code-reviewer.md"
---
name: Code Reviewer
name: code-reviewer
description: Reviews code for correctness, maintainability, and risk
model: claude-sonnet-4-20250514
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.
@ -75,56 +44,116 @@ The frontmatter supports:
| Field | Required | Description |
|---|---:|---|
| `name` | Yes | Display name for the agent. |
| `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. |
| `provider` | No | Preferred provider for the agent. |
| `avatar` | No | Avatar URL or data URL used by goose Desktop. |
The Markdown body is the agent's system prompt.
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.
:::note Compatibility paths
goose also discovers agents from `.goose/agents/`, `.claude/agents/`, `~/.goose/agents/`, `~/.claude/agents/`, and goose's platform-specific config agents directory. New agents should use `.agents/agents/` or `~/.agents/agents/`.
:::
## Use an Agent
## Import and Export Agents
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.
Exporting an agent creates a `.agent.json` file that can be shared or backed up. Importing an agent adds it to your global agents list in goose Desktop.
### List available agents
Exported `.agent.json` files include the agent name, description, and system prompt. Provider, model, and avatar settings may not be included in portable exports depending on how the agent was created.
In a goose chat session, ask goose to list available sources:
An exported agent uses this shape:
```json title="code-reviewer.agent.json"
{
"version": 1,
"type": "agent",
"name": "Code Reviewer",
"description": "Reviews code for correctness, maintainability, and risk",
"content": "You are a senior code reviewer..."
}
```text
list available sources
```
Imported files can use `.agent.json`, `.persona.json`, or `.json` extensions.
This is a prompt to goose, not a terminal command. When source loading is available, goose lists discoverable agents alongside recipes and subrecipes.
## Use an Agent in Chat
You can invoke an agent by mentioning it by name:
After creating or importing an agent, open a chat and select it from the agent picker. goose applies that agent's system prompt to future messages in the current session. If the agent has a provider preference and that provider is available, goose may switch to that provider when you select the agent.
```text
@code-reviewer review the current diff
```
Selecting an agent does not start a separate isolated session. Existing conversation context remains available, subject to the session's context window and any compaction. The agent's prompt applies going forward; it does not rewrite earlier messages.
Or ask goose to use it:
Choose the default goose agent when you want normal behavior, and switch to a custom agent when you want a specialized role or repeatable workflow.
```text
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`.
### Delegate work to an agent
Use a custom agent when you want an isolated specialist to perform a task and return the result to the current conversation.
```text
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:
```text
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.
### Load an agent's instructions into the current conversation
Use an agent as loaded context when you want the current conversation to adopt the agent's instructions without creating a separate delegated session.
```text
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.
## Example Agents
### Code reviewer
```markdown title="~/.agents/agents/code-reviewer.md"
---
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.
```
### Documentation writer
```markdown title="~/.agents/agents/docs-writer.md"
---
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
```
## When to Use Agents, Skills, or Recipes
| Use | Best fit |
|---|---|
| Change goose's overall role, tone, or system prompt for a session | Custom agent |
| 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](/docs/guides/context-engineering/using-skills) |
| Package a repeatable task with prompts, settings, extensions, and parameters | [Recipe](/docs/guides/recipes) |
| Delegate work to another isolated goose instance | [Subagent](/docs/guides/context-engineering/subagents) |
Agents define who goose should be for a session. Skills and recipes define what goose should know or do.
Agents define who goose should be for a task. Skills and recipes define what goose should know or do.
### Can custom agents be scheduled to run?
@ -132,7 +161,7 @@ Not directly. Custom agents are reusable roles, not scheduled jobs. To run somet
### Do custom agents have workflows?
No. A custom agent defines who goose should be for a session: its role, behavior, prompt, and optional provider/model metadata. It does not define a step-by-step workflow. Use a recipe when you need repeatable steps, parameters, extension configuration, or scheduled execution.
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.
### Can custom agents use skills?
@ -148,7 +177,7 @@ Yes. Custom agents can use the MCP servers and extensions that are enabled in th
### Can custom agents call subagents?
Yes, when delegation tools are available in the session. A selected 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, 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.
### Can one custom agent call another custom agent?