How to Use System Prompts in Kimi-CLI: Configuration and Templating Guide

System prompts in kimi-cli are templated text files defined per-agent in YAML specifications that get loaded at startup, injected with built-in environment variables, and persisted across sessions to ensure consistent LLM behavior.

The MoonshotAI/kimi-cli repository implements an agentic framework where system prompts serve as the primary mechanism for defining agent personality and operational constraints. These prompts follow a multi-stage pipeline that supports runtime customization, template substitution, and deterministic session resumption.

How System Prompts Work in Kimi-CLI

The system prompt flow traverses seven distinct stages across the kimi-cli codebase:

• Specification Loading: src/kimi_cli/agentspec.py invokes load_agent_spec() to parse the YAML configuration, extracting system_prompt_path and optional system_prompt_args.

• File Retrieval: In src/kimi_cli/soul/agent.py, the system reads the template file referenced by system_prompt_path from disk.

• Built-in Injection: The same module substitutes placeholders including KIMI_NOW, KIMI_WORK_DIR, and KIMI_AGENTS_MD with their runtime values.

• Custom Arguments: User-defined key-value pairs from system_prompt_args (defined in the spec or passed via CLI) are merged into the template.

• Persistence: src/kimi_cli/soul/context.py calls write_system_prompt() to cache the rendered text in the session context file.

• LLM Transmission: The finalized prompt becomes the first message in the LLM request via src/kimi_cli/llm.py.

• Sub-agent Reuse: When spawning sub-agents, src/kimi_cli/subagents/core.py invokes prepare_soul() to retrieve the persisted prompt rather than re-rendering from source.

Configuring System Prompts

Define the Agent Specification

Create a YAML configuration that references your system prompt template:

# agents/custom_agent/agent.yaml

agent:
  name: custom_agent
  system_prompt_path: system_prompt.txt
  system_prompt_args:
    AGENT_NAME: "CodeAssistant"
    EXPERTISE: "Python"
  tools:
    - kimi_cli.tools.file.read
    - kimi_cli.tools.code.edit

Author the Template File

The system_prompt.txt file supports variable substitution using double curly braces:

You are {{AGENT_NAME}}, an expert in {{EXPERTISE}}.
Current working directory: {{KIMI_WORK_DIR}}
Current time: {{KIMI_NOW}}
Agent documentation available at: {{KIMI_AGENTS_MD}}

Always provide concise, accurate responses based on the files in the working directory.

Built-in Template Variables

The kimi-cli runtime automatically injects these variables during the loading phase:

• KIMI_NOW: Current date and time string
• KIMI_WORK_DIR: Absolute path to the current working directory
• KIMI_AGENTS_MD: Path to the AGENTS.md documentation file

Runtime Overrides via CLI

You can override template variables at execution time without modifying the YAML configuration:

kimi --agent custom_agent --system-prompt-arg AGENT_NAME="Debugger" --system-prompt-arg EXPERTISE="Rust"

The --system-prompt-arg flag accepts key-value pairs that take precedence over values defined in system_prompt_args. Multiple arguments can be passed by repeating the flag.

Session Persistence and Sub-agents

The persistence mechanism ensures behavioral consistency across resumed sessions. When write_system_prompt() in src/kimi_cli/soul/context.py stores the rendered template, it creates a deterministic snapshot. Subsequent sub-agent invocations via prepare_soul() in src/kimi_cli/subagents/core.py retrieve this cached version rather than re-processing the source file. This guarantees that parent and child agents operate with identical system instructions, preventing drift in long-running workflows.

Summary

• System prompts in kimi-cli are template files defined per-agent via system_prompt_path in YAML specifications
• The rendering pipeline automatically injects built-in variables (KIMI_NOW, KIMI_WORK_DIR, KIMI_AGENTS_MD) and user-defined arguments from system_prompt_args
• Rendered prompts are persisted through src/kimi_cli/soul/context.py to ensure deterministic session resumption
• Sub-agents inherit the same system prompt via prepare_soul() in src/kimi_cli/subagents/core.py to maintain consistent behavior hierarchies
• Use --system-prompt-arg CLI flags to override variables at runtime without editing configuration files

Frequently Asked Questions

Where does kimi-cli store system prompt templates?

System prompt templates reside in the agent directory alongside the agent.yaml specification file. The default agent ships with its template in src/kimi_cli/agents/default/, while custom agents store prompts in their respective user-defined directories. The system_prompt_path key in the YAML spec resolves relative to the agent configuration file location.

Can I change the system prompt without editing the agent YAML?

Yes. Use the --system-prompt-arg CLI flag to override any template variable defined in system_prompt_args. For example, executing kimi --agent custom_agent --system-prompt-arg AGENT_NAME=Debugger temporarily changes the agent's identity without modifying the underlying agent.yaml file.

Which built-in variables are available for templating?

The kimi-cli environment provides KIMI_NOW (current timestamp), KIMI_WORK_DIR (absolute working directory path), and KIMI_AGENTS_MD (path to agent documentation). These are automatically populated when src/kimi_cli/soul/agent.py processes the template during the agent initialization phase.

How does kimi-cli ensure consistency when resuming a session?

The system calls write_system_prompt() in src/kimi_cli/soul/context.py to cache the fully rendered prompt text in the session context. When resuming or spawning sub-agents through prepare_soul() in src/kimi_cli/subagents/core.py, kimi-cli retrieves this persisted version instead of re-reading the source template, ensuring the LLM receives identical system instructions across session boundaries.

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