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

> Master system prompts in Kimi-CLI. Learn configuration and templating to inject environment variables and ensure consistent LLM behavior across sessions with this essential guide.

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

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/llm.py).

- **Sub-agent Reuse**: When spawning sub-agents, [`src/kimi_cli/subagents/core.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```yaml

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/system_prompt.txt) file supports variable substitution using double curly braces:

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

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