# How to Create Custom Prompts for kimi-cli: A Complete Guide to Agent Specifications

> Learn how to create custom prompts for kimi-cli by crafting YAML agent specifications and referencing custom system prompt files. Follow our guide for effective agent customization.

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

---

**You can create custom prompts for kimi-cli by authoring a YAML agent specification that references a custom system prompt file via `system_prompt_path`, then launching the CLI with `--agent-file` to override the defaults defined in [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml).**

The MoonshotAI/kimi-cli project implements a modular **agent-based architecture** that decouples system instructions from tool configurations. Instead of hard-coding behaviors, the CLI loads **agent specifications** written in YAML, enabling you to inject custom instructions, security policies, or domain-specific coding standards into every LLM request. This architecture centers on the `Agent` class, which processes `system_prompt_path` and `system_prompt_args` to dynamically construct the final system prompt.

## Understanding the Agent Architecture

According to the kimi-cli source code, all behavior is driven through agent specifications. The default configuration resides in [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml), which points to [`src/kimi_cli/agents/default/system.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/system.md) for the base instructions. When initializing a session, the `Agent` class reads these files, substitutes any template variables, and passes the resulting text to the LLM as the system context.

To create custom prompts, you override this default chain by supplying your own agent specification that references alternative prompt files.

## Step 1: Author Your Custom Prompt File

Create a plain-text or Markdown file containing your system instructions. Use double curly braces `{{VARIABLE}}` to define template placeholders that the CLI will substitute at runtime.

```markdown

# senior-python-engineer.md

You are a senior Python engineer working on the {{PROJECT_NAME}} codebase.
All responses must be concise, use type-annotated Python 3.12 syntax,
and include inline comments explaining any non-trivial logic.
If {{DEBUG_MODE}} is true, you may emit additional diagnostic output.

```

Store this file in your project directory. The path you specify in the next step can be relative to your agent YAML file.

## Step 2: Define the Agent Specification

Create a YAML agent specification that references your prompt file and provides the substitution values. The key fields are:

- **system_prompt_path**: Relative or absolute path to your prompt file
- **system_prompt_args**: Dictionary mapping variable names to values
- **extends**: Optional inheritance directive to retain default tools

```yaml

# custom-python-agent.yaml

name: senior-python-agent
extends: default
system_prompt_path: ./senior-python-engineer.md
system_prompt_args:
  PROJECT_NAME: "Acme-Analytics"
  DEBUG_MODE: "true"

```

This configuration inherits the default tool set from [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml) while replacing the system instructions with your custom prompt.

## Step 3: Load Your Custom Agent

Invoke the CLI with the `--agent-file` flag pointing to your YAML specification:

```bash
kimi --agent-file ./custom-python-agent.yaml "Review this function for type safety"

```

Alternatively, set the `KIMI_AGENT_FILE` environment variable to avoid typing the flag repeatedly:

```bash
export KIMI_AGENT_FILE=./custom-python-agent.yaml
kimi "Refactor this class to use pydantic models"

```

When the CLI starts, it loads [`./senior-python-engineer.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/./senior-python-engineer.md), substitutes `Acme-Analytics` for `{{PROJECT_NAME}}` and `true` for `{{DEBUG_MODE}}`, and uses the resulting text as the system prompt.

## Alternative: Embedding Prompts Directly

If you prefer not to maintain separate prompt files, you can embed the system prompt directly within the agent YAML under the `system_prompt` key (schema permitting). This approach eliminates the external file dependency but reduces readability for lengthy instructions.

## Complete Working Example

The repository includes a reference implementation at [`examples/custom-tools/myagent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/examples/custom-tools/myagent.yaml) demonstrating custom agent patterns. Following that structure:

```yaml

# myagent.yaml

name: security-auditor
extends: default
system_prompt_path: ./security-prompt.md
system_prompt_args:
  COMPLIANCE_LEVEL: "strict"
  FRAMEWORK: "OWASP-Top-10-2021"

```

```markdown

# security-prompt.md

You are a security auditor evaluating code against {{FRAMEWORK}}.
Compliance level: {{COMPLIANCE_LEVEL}}.
Flag any unsafe deserializations, SQL injection vectors, or hardcoded secrets.
Provide CWE identifiers for each vulnerability found.

```

Execute with:

```bash
kimi --agent-file myagent.yaml audit ./src/

```

## Summary

- kimi-cli uses **YAML agent specifications** to configure LLM behavior, located by default in [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml)
- Custom prompts are defined in separate text files referenced by the **`system_prompt_path`** field
- **Variable substitution** uses the `{{VARIABLE}}` syntax with values supplied via `system_prompt_args`
- Launch custom agents using **`--agent-file`** or the **`KIMI_AGENT_FILE`** environment variable
- Use **`extends: default`** to inherit the base tool set while overriding only the prompt instructions

## Frequently Asked Questions

### What file format should I use for custom prompts?

Plain text or Markdown files are recommended. The `Agent` class reads the file specified in `system_prompt_path` as raw text and injects it directly into the LLM's system context. Any text-based format—including `.md`, `.txt`, or even code files—works correctly.

### Can I inherit tools from the default agent while using a custom prompt?

Yes. Include `extends: default` in your agent YAML to inherit the complete tool set and configuration from [`src/kimi_cli/agents/default/agent.yaml`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/default/agent.yaml) while overriding only the `system_prompt_path` and `system_prompt_args` fields with your custom values.

### How does variable substitution work in custom prompts?

The `Agent` class scans your prompt file for double curly brace syntax (e.g., `{{PROJECT_NAME}}`) and replaces these placeholders with the corresponding values defined in the `system_prompt_args` dictionary of your agent specification before sending the request to the LLM.

### Where should I store custom agent specifications?

You can place agent files anywhere in your filesystem. For portability, store them within your project repository and use relative paths for `system_prompt_path` (relative to the YAML file location). Reference them at runtime using `--agent-file path/to/agent.yaml` or set `KIMI_AGENT_FILE` in your shell configuration.