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

> Learn to create and utilize custom subagents like coder, explore, and plan in Kimi-Code. This guide details YAML configurations for modular task delegation and efficient coding workflows.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: how-to-guide
- Published: 2026-07-27

---

**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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.

```yaml
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/session/subagent-host.ts) detects this parameter and spawns the corresponding profile.

```json
{
  "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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/profile/default/explore.yaml), it receives special git context injection in [`subagent-host.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/subagent-host.ts) to understand repository history. Launch it programmatically using the SDK:

```typescript
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:

```bash
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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/protocol/src/events.ts) that track subagent execution. Subscribe to these events to build UI panels or logging systems:

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.