How to Create and Utilize Custom Subagents in Kimi-Code: A Complete Guide to Coder, Explore, and Plan Agents

Custom subagents in Kimi-Code are specialized worker profiles defined in YAML files that spawn separate agent instances when tool requests specify a subagent_type, enabling modular task delegation for coding, exploration, and planning workflows.

Kimi-Code's architecture treats any worker that runs its own turn as a subagent, allowing you to delegate specific tasks to specialized agents. These subagents are defined by YAML profiles and launched automatically when a tool request specifies a subagent_type parameter. Whether you need to analyze code, explore repositories, or create structured plans, understanding how to create and utilize custom subagents unlocks the full potential of the MoonshotAI/kimi-code engine.

Understanding Subagent Architecture in Kimi-Code

The subagent system relies on three core components working together to spawn isolated agent instances that report progress through the transcript system.

The Transcript Task Model

In packages/transcript/src/model/task.ts, the engine defines a subagent as a task with kind: 'subagent'. This declaration separates subagent execution from regular tool calls, enabling the transcript to record each turn of the child agent independently for debugging, replay, and resume logic.

Profile Definitions

Profiles are YAML files stored in packages/agent-core/src/profile/default/ that describe a subagent's capabilities. Each profile specifies the name, system prompt variables (promptVars), when-to-use descriptions, and the tools the subagent may invoke. For example, the explore profile in packages/agent-core/src/profile/default/explore.yaml grants access to Read, Glob, Grep, WebSearch, and FetchURL tools.

The Subagent Host

The packages/agent-core/src/session/subagent-host.ts file contains the runtime logic that instantiates child agents. It looks up profile names, creates Agent instances, and handles special-case context injection—such as attaching git context to explore subagents via packages/agent-core/src/session/git-context.ts.

Creating a Custom Subagent from Scratch

Building a custom subagent requires defining the profile, ensuring registration, and invoking it via tool requests.

Step 1: Define the Profile YAML

Create a new YAML file in packages/agent-core/src/profile/default/. You can extend existing profiles to inherit common fields using the extends key.

extends: coder
name: mytool
promptVars:
  roleAdditional: |
    You are a specialized sub-agent for analyzing dependency graphs.
whenToUse: |
  Use this sub-agent when you need to map import relationships across the codebase.
tools:
  - Read
  - Glob
  - Grep

Step 2: Register the Profile

The packages/agent-core/src/profile/default.ts loader automatically discovers any *.yaml files in the default directory and registers them under DEFAULT_AGENT_PROFILES. No manual import is required if you place the file in the correct location.

Step 3: Invoke via Tool Request

Trigger your custom subagent by including subagent_type in a tool request. The subagent host in packages/agent-core/src/session/subagent-host.ts detects this parameter and spawns the corresponding profile.

{
  "type": "tool",
  "name": "mytool",
  "subagent_type": "mytool",
  "args": { "query": "find unused imports" }
}

Utilizing Built-in Subagents (Coder, Explore, Plan)

Kimi-Code ships with three primary subagents optimized for specific workflows, each defined in the default profiles directory.

The Coder Subagent

The coder subagent serves as the default coding assistant. You can invoke it directly via session.ask() or indirectly through the Write tool. It handles general code generation and modification tasks without requiring explicit subagent_type specification for basic operations.

The Explore Subagent

The explore subagent operates as a read-only codebase analyzer. Defined in packages/agent-core/src/profile/default/explore.yaml, it receives special git context injection in subagent-host.ts to understand repository history. Launch it programmatically using the SDK:

import { Klient } from '@moonshot-ai/klient';

const client = new Klient({ serverUrl: 'http://localhost:58627' });
const session = await client.createSession({ id: 'demo' });

await session.generateAgentsMd({
  agents: [{ profileName: 'explore' }],
});

Or via CLI:

kimi-code explore "Find all TODO comments in src/**/*.ts" --thorough

The Plan Subagent

The plan subagent specializes in structured planning tasks. Typically launched automatically when users enter plan mode via the EnterPlanMode skill, it breaks complex objectives into actionable steps before execution begins.

Monitoring Subagent Lifecycle Events

The protocol defines wire-level events in packages/protocol/src/events.ts that track subagent execution. Subscribe to these events to build UI panels or logging systems:

session.events.subscribe(event => {
  if (event.type === 'subagent.completed') {
    console.log(`Sub-agent ${event.subagentName} finished:`, event);
  }
});

Available events include subagent.spawned, subagent.started, subagent.completed, and subagent.failed.

Summary

• Subagents are specialized agent instances defined by YAML profiles and launched via subagent_type parameters in tool requests.
• Create custom subagents by adding YAML files to packages/agent-core/src/profile/default/ and invoking them through the SDK or CLI.
• The subagent host in packages/agent-core/src/session/subagent-host.ts handles instantiation, profile wiring, and special context injection.
• Built-in subagents include coder (general coding), explore (read-only analysis with git context), and plan (structured planning).
• Monitor subagent execution through protocol events defined in packages/protocol/src/events.ts for debugging and UI integration.

Frequently Asked Questions

What is the difference between a subagent and a regular tool in Kimi-Code?

A regular tool executes a single function and returns immediately, while a subagent runs its own multi-turn conversation loop as a separate agent instance. Subagents are defined in packages/transcript/src/model/task.ts with kind: 'subagent', allowing them to maintain state across multiple turns and invoke other tools independently before returning results to the parent agent.

Can I extend existing subagent profiles like coder or explore?

Yes. Use the extends field in your YAML profile definition to inherit common fields from base profiles such as coder. This allows you to override specific promptVars or add specialized tools while maintaining the core behavior of the parent agent, as implemented in the profile loader at packages/agent-core/src/profile/default.ts.

How do I pass custom context to my subagent?

For standard profiles, context passes through the args field in the tool request. For special cases like the explore subagent, you can modify packages/agent-core/src/session/subagent-host.ts to inject additional context—such as git history from packages/agent-core/src/session/git-context.ts—by checking if (profileName === 'mytool') before instantiation.

Why doesn't my custom subagent appear in the available agents list?

Ensure your YAML file resides in packages/agent-core/src/profile/default/ and uses the correct structure with name, promptVars, and tools fields. The default.ts loader automatically registers *.yaml files, but syntax errors or incorrect directory placement will prevent registration. Verify the profile loaded correctly by checking DEFAULT_AGENT_PROFILES at runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}