IDE
CLI

Sub-Agents ​

Sub-agents allow you to package commonly used roles, workflows, or tool combinations into reusable "agent tools" that can be invoked like commands in the CLI or used as tools within other agents.

Placement Locations ​

Sub-agents support two levels of sources, merged intelligently according to priority:

  • Project-level: .codebuddy/agents/

  • Global personal: ~/.codebuddy/agents/

Subdirectories are supported, and the subdirectory name will be displayed as part of the source label in the description, making it easy to distinguish agents with the same name.

File Naming and Recognition ​

  • Each .md file represents a sub-agent. For example, .codebuddy/agents/test.md will register as the agent named test.

  • The name defaults to the file name (without the .md extension), but it can also be specified in the Frontmatter with the name field.

Frontmatter Metadata ​

You can configure metadata using YAML Frontmatter at the top of the Markdown file:

markdown
---
name: "my-agent"
description: "Responsible for code review and suggestions"
model: "gpt-4o"
tools: "bash,fs,github"
color: "#4A90E2"
---
Here are the system instructions and task details for this sub-agent...

Field explanations:

  • name: Optional. Overrides the default name (file name).

  • description: Optional. A brief description. The system will automatically append the source label (project|user and subdirectory path).

  • model: Optional. The current implementation parses this but does not require it. It may be determined by upper-level product configurations.

  • tools: Optional. A comma-separated list. When not specified, it inherits the default tools of the current agent. The task tool will be automatically removed internally.

  • color: Optional. Specifies the color code for displaying the agent in the interface (e.g., "#FF5733"). If not specified, the system will automatically generate a consistent color based on the agent name.

Instructions Content ​

The content after the Frontmatter is the "system/work instructions" for the sub-agent. During execution, it will be passed as the instructions for the agent.

Using as a Tool ​

  • Sub-agents are marked as asTool: true and can be called as tools within other workflows or agents.

  • The system will automatically tag them as: cli, custom, making it easier to filter in the list.

Source Label Examples ​

  • (project): From the .codebuddy/agents directory in the project root

  • (project:review): From the .codebuddy/agents/review/ subdirectory

  • (user): From the ~/.codebuddy/agents directory

  • (user:experiments:lint): From the ~/.codebuddy/agents/experiments/lint/ subdirectory

This label will automatically be appended to the description, for example: "Code review (project:review)".

Writing Suggestions ​

  • Make sure to clearly specify the inputs, steps, and output format in the content.

  • If tools are required, explicitly declare them in the tools field; if default tools are used, this can be omitted.

  • Consolidate common roles/workflows into separate .md files for easier reuse across projects (store them in the user directory).

Management Interface ​

Use the /agents slash command to open the visual agent management interface, which supports:

  • Create Agents: Automatically generate agent configurations based on natural language descriptions.

  • Smart Configuration: AI auto-generates system prompts and usage scenario descriptions.

  • Location Selection: Choose whether to save to the project-level or user-level directory.

  • Delete Management: Safely delete unnecessary agents.

  • Real-time Preview: Preview the full agent configuration before creation.

Frequently Asked Questions ​

  • What happens if no tools are specified? The agent will inherit the default toolset of the default agent.

  • How are files with the same name distinguished? They are distinguished by the source label in the description.

  • Can subdirectories be nested? Yes, directory paths will be reflected in the source label.

  • How do I quickly create an agent? Use the /agents command to enter the management interface and enter a natural language description.