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

> Learn to use a system prompt in Kimi-CLI with our complete configuration guide. Customize agent behavior for enhanced LLM interactions. Get started now!

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

---

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

```text
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/agents/my_agent/agent.yaml):

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

```bash
kimi --agent my_agent

```

The default agent configuration located at [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```bash
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py) | `write_system_prompt()` | Persists the rendered prompt to the session context for resumption |
| [`src/kimi_cli/llm.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/subagents/core.py) | `prepare_soul()` | Reuses the persisted system prompt when initializing sub-agents |
| [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/agentspec.py).
- **Template rendering** occurs in [`soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/soul/context.py), ensuring resumed sessions maintain identical system messages.
- **Sub-agent inheritance** is managed through `prepare_soul()` in [`subagents/core.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.