How to Use a System Prompt in Kimi-CLI: Complete Configuration Guide

A system prompt in kimi-cli is a templated text file defined in an agent specification (YAML) that is rendered at runtime with built-in variables and custom arguments, then persisted to the session context for LLM consumption.

The MoonshotAI/kimi-cli repository implements an agentic interface where the LLM's initial behavior is seeded by a configurable system prompt. These prompts are loaded from external files, processed with template variables, and managed through a lifecycle that supports both initial sessions and sub-agent resumption.

What Is a System Prompt in Kimi-CLI?

A system prompt is the first message sent to the LLM that establishes the agent's role, constraints, and available context. In kimi-cli, this is not hardcoded but instead referenced via the system_prompt_path field in an agent specification. The prompt file supports Jinja-style templating, allowing dynamic injection of runtime values such as the current working directory or timestamp before the text is passed to the model.

How System Prompts Are Loaded and Processed

The system prompt lifecycle follows a strict pipeline across several core modules:

Loading the Agent Specification

The process begins in src/kimi_cli/agentspec.py where the load_agent_spec() function parses the agent's YAML configuration. This spec includes two critical fields:

• system_prompt_path: The relative or absolute path to the template file
• system_prompt_args: An optional dictionary of user-defined key/value pairs for template substitution

Reading and Templating the Prompt

Once the spec is loaded, src/kimi_cli/soul/agent.py executes an internal load_system_prompt routine. This function:

1. Reads the file content from system_prompt_path
2. Injects built-in arguments including KIMI_NOW (current timestamp), KIMI_WORK_DIR (working directory), and KIMI_AGENTS_MD (built-in skills documentation)
3. Merges the system_prompt_args from the YAML spec or CLI overrides to replace custom placeholders like {{AGENT_NAME}}

Persisting to Session Context

After rendering, the final prompt text is stored via write_system_prompt() in src/kimi_cli/soul/context.py. This persistence ensures that if a session is resumed or a sub-agent is spawned, the exact same system message is reused without re-reading the original template file.

Passing to the LLM

The rendered prompt is then passed to src/kimi_cli/llm.py where it becomes the first message in the LLM request payload, preceding any user queries or tool schemas.

Sub-Agent Reuse

When spawning sub-agents, src/kimi_cli/subagents/core.py calls prepare_soul() to initialize the child context. This function checks context.system_prompt; if present, it reuses the persisted text, ensuring consistent behavior across agent hierarchies.

Configuring a Custom System Prompt

To implement a custom system prompt, create a template file and reference it in your agent specification.

Create a template file named my_prompt.txt:

You are a specialized coding assistant operating in {{KIMI_WORK_DIR}}.
The current time is {{KIMI_NOW}}.
Your designated name is {{AGENT_NAME}}.
Always reference the available skills documented in {{KIMI_AGENTS_MD}}.

Define the agent specification in agents/my_agent/agent.yaml:

agent:
  name: my_agent
  system_prompt_path: my_prompt.txt
  system_prompt_args:
    AGENT_NAME: "CodeHelper"
  tools:
    - kimi_cli.tools.file.glob

Run the CLI with your custom agent:

kimi --agent my_agent

The default agent configuration located at src/kimi_cli/agents/default/agent.yaml demonstrates the standard structure for referencing system prompts when no custom agent is specified.

Overriding Variables from the Command Line

You can override template variables at runtime using the --system-prompt-arg flag, which dynamically updates the system_prompt_args dictionary without modifying the YAML file:

kimi --agent my_agent --system-prompt-arg AGENT_NAME=Echo

This is particularly useful for ephemeral changes to agent identity or for injecting session-specific metadata that isn't known when writing the specification.

Key Source Files and Architecture

File	Key Function	Purpose
src/kimi_cli/agentspec.py	load_agent_spec()	Parses YAML specs and resolves system_prompt_path and system_prompt_args
src/kimi_cli/soul/agent.py	Internal loading routine	Reads the prompt file and performs template substitution with built-in and custom variables
src/kimi_cli/soul/context.py	write_system_prompt()	Persists the rendered prompt to the session context for resumption
src/kimi_cli/llm.py	Request construction	Receives the final system prompt as the first message in LLM calls
src/kimi_cli/subagents/core.py	prepare_soul()	Reuses the persisted system prompt when initializing sub-agents
src/kimi_cli/agents/default/agent.yaml	Specification	Default agent configuration showing standard system prompt reference

Summary

• System prompts are defined per-agent via system_prompt_path in YAML specifications parsed by load_agent_spec() in agentspec.py.
• Template rendering occurs in soul/agent.py, injecting built-in variables like KIMI_WORK_DIR and merging custom arguments from system_prompt_args.
• Session persistence is handled by write_system_prompt() in soul/context.py, ensuring resumed sessions maintain identical system messages.
• Sub-agent inheritance is managed through prepare_soul() in subagents/core.py, which reuses the persisted prompt from the parent context.
• Runtime overrides are supported via the --system-prompt-arg CLI flag for dynamic template variable substitution.

Frequently Asked Questions

Where is the system prompt stored during an active session?

The rendered system prompt is stored in the session's context file via the write_system_prompt() function in src/kimi_cli/soul/context.py. This persistence allows the CLI to resume sessions or spawn sub-agents without re-reading and re-rendering the original template file.

Can I change the system prompt after starting a session?

No. The system prompt is loaded and persisted at session initialization. To use a different prompt, you must start a new session with either a different system_prompt_path in the agent specification or modified template variables passed via --system-prompt-arg.

What built-in variables are available for system prompt templating?

The rendering engine automatically injects KIMI_NOW (current timestamp), KIMI_WORK_DIR (the active working directory), and KIMI_AGENTS_MD (formatted documentation of available agent skills). You can supplement these with any custom variables defined in the YAML system_prompt_args or passed via CLI arguments.

How do sub-agents inherit the system prompt from the parent agent?

When a sub-agent is created, the prepare_soul() function in src/kimi_cli/subagents/core.py checks the parent context for an existing system prompt. If found, it reuses the persisted text directly; otherwise, it triggers the standard load-and-render pipeline. This ensures behavioral consistency across agent hierarchies.

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