# Kimi-CLI Agent YAML Specifications: Understanding `extend`, `tools`, and `subagents` Structure

> Master Kimi-CLI agent YAML specs with extend tools and subagents. Learn about inheritance capability management and nested agent delegation for powerful AI configurations.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: internals
- Published: 2026-07-22

---

**Kimi-CLI agent YAML specifications define AI agent behavior through hierarchical configuration files using the `extend` field for inheritance, `tools`/`allowed_tools`/`exclude_tools` for capability management, and `subagents` for nested agent delegation.**

MoonshotAI/kimi-cli uses YAML-based agent specifications located in `src/kimi_cli/agents/` to configure LLM behavior, tool access, and hierarchical agent relationships. Understanding the structure of these agent YAML specifications—including the critical `extend`, `tools`, and `subagents` fields—is essential for customizing or extending the CLI's capabilities.

## Core Schema Fields in Agent Specifications

Every agent YAML file follows a strict schema starting with `version: 1` at the top level. The configuration resides under the `agent:` key, which accepts several fields that control the agent's identity, capabilities, and inheritance.

### Metadata and Prompt Configuration

- **`name`**: Optional human-readable identifier for the agent.
- **`system_prompt_path`**: Relative path to a markdown file containing the system prompt template (e.g., [`./system.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/./system.md)).
- **`system_prompt_args`**: Key-value mappings for template variables injected into the system prompt at runtime.

These fields are typically defined in the base agent specification at [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml) and inherited by child agents.

### Tool Configuration Fields

The specification provides three mechanisms for controlling tool access:

- **`tools`**: Defines the **complete list** of available tool import paths as fully qualified Python references (e.g., `"kimi_cli.tools.shell:Shell"`). This field is usually declared only in the base agent to establish the full capability set.
- **`allowed_tools`**: A whitelist used by sub-agents to restrict the inherited tool set to specific capabilities.
- **`exclude_tools`**: A blacklist that removes specific tools from the inherited configuration.

When a sub-agent extends a parent, the runtime merges these lists according to inheritance rules, applying exclusions before whitelisting.

## Agent Inheritance Using the `extend` Field

The **`extend`** field enables configuration inheritance by referencing another YAML file whose contents are merged into the current specification. This mechanism creates a hierarchy where child agents inherit all parent fields and selectively override them.

According to the source code in [`src/kimi_cli/agents/default/coder.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/coder.yaml), sub-agents use relative paths to extend the base definition:

```yaml
agent:
  extend: ./agent.yaml

```

The inheritance resolution follows this flow:

1. The runtime loads the base agent from [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml), which contains the complete tool registry and sub-agent declarations.
2. When loading a child agent (e.g., [`coder.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/coder.yaml)), the system resolves the `extend` chain and merges dictionaries, with child values taking precedence.
3. Tool restrictions (`allowed_tools`/`exclude_tools`) are applied to the merged tool list from the parent.

This design allows specialized agents to maintain minimal configuration files while leveraging the base agent's infrastructure.

## Declaring Hierarchical Agents with `subagents`

The **`subagents`** field is a dictionary that declares named child agents available for delegation. Each entry requires two properties:

- **`path`**: Relative file path to the sub-agent's YAML specification.
- **`description`**: Free-form text explaining the sub-agent's purpose for documentation and UI hints.

In [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml), the base agent defines several sub-agents:

```yaml
subagents:
  coder:
    path: ./coder.yaml
    description: "Good at general software engineering tasks."
  explore:
    path: ./explore.yaml
    description: "Fast codebase exploration with read-only behavior."
  plan:
    path: ./plan.yaml
    description: "Read-only implementation planning and architecture design."

```

Child agents can declare `subagents: {}` to terminate the hierarchy, or omit the field entirely to inherit sub-agents from the parent (though typically specialized agents define an empty map to prevent further delegation).

## Practical Configuration Examples

### Base Agent Definition

The root specification at [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml) serves as the foundation:

```yaml
version: 1
agent:
  name: ""
  system_prompt_path: ./system.md
  system_prompt_args:
    ROLE_ADDITIONAL: ""
  tools:
    - "kimi_cli.tools.agent:Agent"
    - "kimi_cli.tools.shell:Shell"
    - "kimi_cli.tools.file:ReadFile"
    - "kimi_cli.tools.web:SearchWeb"
    - "kimi_cli.tools.ask_user:AskUserQuestion"
  subagents:
    coder:
      path: ./coder.yaml
      description: "Good at general software engineering tasks."

```

### Specialized Sub-Agent with Tool Restrictions

The `coder` sub-agent at [`src/kimi_cli/agents/default/coder.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/coder.yaml) demonstrates inheritance and restriction patterns:

```yaml
version: 1
agent:
  extend: ./agent.yaml
  system_prompt_args:
    ROLE_ADDITIONAL: |
      You are now running as a subagent specialized for coding tasks.
  when_to_use: |
    Use this agent for non-trivial software engineering work.
  allowed_tools:
    - "kimi_cli.tools.shell:Shell"
    - "kimi_cli.tools.file:ReadFile"
    - "kimi_cli.tools.web:SearchWeb"
  exclude_tools:
    - "kimi_cli.tools.agent:Agent"
    - "kimi_cli.tools.ask_user:AskUserQuestion"
  subagents: {}

```

### Custom Minimal Agent

To create a `tester` agent with read-only capabilities:

```yaml
version: 1
agent:
  extend: ./agent.yaml
  allowed_tools:
    - "kimi_cli.tools.file:ReadFile"
    - "kimi_cli.tools.web:SearchWeb"
  subagents: {}

```

## Summary

- **Agent YAML specifications** in Kimi-CLI use a versioned schema (currently `version: 1`) with configuration nested under the `agent:` key.
- The **`extend`** field enables file-based inheritance, allowing sub-agents to merge and override base configurations from paths like [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml).
- **Tool access** is controlled through three complementary fields: `tools` (full registry), `allowed_tools` (sub-agent whitelist), and `exclude_tools` (sub-agent blacklist).
- The **`subagents`** dictionary defines hierarchical relationships, requiring `path` and `description` properties for each declared child agent.
- Configuration files are stored in `src/kimi_cli/agents/`, with the `default/` directory containing the built-in agent hierarchy.

## Frequently Asked Questions

### What is the purpose of the `extend` field in Kimi-CLI agent YAML specifications?

The `extend` field specifies a parent YAML file path that the current agent configuration inherits from. When the Kimi-CLI runtime loads an agent, it merges the parent specification with the child specification, allowing child values to override parent defaults. This mechanism reduces duplication by letting sub-agents like [`coder.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/coder.yaml) reference [`./agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/./agent.yaml) rather than redefining the entire tool registry.

### How do `allowed_tools` and `exclude_tools` interact with the base `tools` list?

When an agent extends another, it inherits the parent's `tools` list. The runtime first applies `exclude_tools` to remove unwanted capabilities, then applies `allowed_tools` to restrict the remaining set to the specified items. If `allowed_tools` is present, the agent can only access tools in that whitelist; if absent, the agent retains all inherited tools minus any exclusions.

### Can sub-agents define their own sub-agents, or is the hierarchy flat?

Sub-agents can theoretically define their own `subagents` dictionaries to create nested hierarchies. However, practical implementations like [`src/kimi_cli/agents/default/coder.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/coder.yaml) typically set `subagents: {}` to indicate they are leaf nodes in the delegation tree. The base agent at [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml) defines the primary sub-agents (`coder`, `explore`, `plan`), while specialized agents usually terminate the chain to prevent infinite delegation loops.