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

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).
• 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 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, sub-agents use relative paths to extend the base definition:

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, which contains the complete tool registry and sub-agent declarations.
2. When loading a child agent (e.g., 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, the base agent defines several sub-agents:

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 serves as the foundation:

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 demonstrates inheritance and restriction patterns:

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:

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.
• 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 reference ./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 typically set subagents: {} to indicate they are leaf nodes in the delegation tree. The base agent at 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.

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