From 70ed1542e3d4dec7c5dbb79b105b405fb3ade4d3 Mon Sep 17 00:00:00 2001
From: 7Sageer <7sageer@djwcb.cn>
Date: Thu, 30 Jul 2026 18:21:47 +0800
Subject: [PATCH] Clarify system prompt variable evaluation timing

---
 docs/en/customization/agents.md | 2 ++
 docs/zh/customization/agents.md | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/docs/en/customization/agents.md b/docs/en/customization/agents.md
index 209711bdc..62eeb34a9 100644
--- a/docs/en/customization/agents.md
+++ b/docs/en/customization/agents.md
@@ -158,6 +158,8 @@ Like the body of a regular agent file, SYSTEM.md is rendered as a template each
 
 Unknown variables stay verbatim, a bare `$` is never special, and a variable with no context value renders as an empty string. Three pre-composed blocks — `${windows_notes}`, `${additional_dirs_section}`, and `${skills_section}` — render the matching built-in prompt section, or an empty string when it does not apply. The variables are enough to rebuild the skeleton of the built-in prompt, for example:
 
+These variables are evaluated when the system prompt is rendered. An existing session does not watch `AGENTS.md` or inject a change reminder automatically; edits take effect the next time the system prompt is rendered, such as after a working-directory change, context compaction, or a new session.
+
 ```markdown
 You are Kimi, running at ${cwd} on ${os}.
 
diff --git a/docs/zh/customization/agents.md b/docs/zh/customization/agents.md
index 0dd0a9c8a..5fa6a1e7e 100644
--- a/docs/zh/customization/agents.md
+++ b/docs/zh/customization/agents.md
@@ -158,6 +158,8 @@ SYSTEM.md 是纯 Markdown 正文，不需要也不读取 Frontmatter。文件缺
 
 未知变量原样保留，单独的 `$` 没有特殊含义；上下文中缺失的变量渲染为空字符串。另有三个预组合块——`${windows_notes}`、`${additional_dirs_section}`、`${skills_section}`——渲染对应的内置提示词段落，不适用时为空字符串。利用这些变量可以重建内置提示词的骨架，例如：
 
+这些变量会在系统提示词重新构建时求值。现有会话不会监控 `AGENTS.md`，也不会自动注入变更提醒；编辑文件后，需要等系统提示词再次构建（例如切换工作目录、上下文压缩或启动新会话）才会生效。
+
 ```markdown
 You are Kimi, running at ${cwd} on ${os}.