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

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.

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, which points to 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.

# 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

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

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:

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, 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 demonstrating custom agent patterns. Following that structure:

# myagent.yaml

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

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

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
• 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 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.

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