MoonshotAI · liruifengv · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
diff --git a/.changeset/follow-kimi-home-resources.md b/.changeset/follow-kimi-home-resources.md
@@ -0,0 +1,6 @@
+---
+"@moonshot-ai/agent-core": patch
+"@moonshot-ai/kimi-code": patch
+---
+
+Load Kimi-specific user Skills and global agent instructions from `KIMI_CODE_HOME` when it is set.
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -97,9 +97,9 @@ Term mapping (Chinese <-> English, and proper noun handling):
   - Chinese: use `提示` for tip, `注意` for warning, `说明` for info, `警告` for danger.
   - English: use no title or short words like `Note` for warning.
   - ✓ `::: tip 提示` + content starting with the key point
-  - ✓ `::: warning 注意` + content `\`KIMI_CODE_HOME\` 不影响 Skills 的搜索路径。...`
-  - ✗ `::: warning 不影响 Skills` (title too long, should be in content)
-  - ✗ `::: tip Skills 路径独立于 KIMI_CODE_HOME` (title too long)
+  - ✓ `::: warning 注意` + content `部分 \`.agents\` 资源不受 \`KIMI_CODE_HOME\` 影响。...`
+  - ✗ `::: warning 不影响 .agents` (title too long, should be in content)
+  - ✗ `::: tip .agents 路径独立于 KIMI_CODE_HOME` (title too long)
 - **Version info blocks**: For version change callouts, use `::: info` with a category title (Added/Changed/Removed in English; 新增/变更/移除 in Chinese). The content should be a complete sentence.
   - ✓ `::: info 新增` + content `新增于 0.2.0。`
   - ✗ `::: info 新增于 0.2.0` (title too long)

diff --git a/docs/en/configuration/data-locations.md b/docs/en/configuration/data-locations.md
@@ -16,13 +16,13 @@ If you need to move the data directory elsewhere (for example, to isolate config
 export KIMI_CODE_HOME="$HOME/.config/kimi-code"
 ```
 
-Once set, **all** data — config, sessions, logs, OAuth credentials, and more — lands under the new path. For the full reference on `KIMI_CODE_HOME`, see [Environment variables](./env-vars.md).
+Once set, **all** Kimi Code data — config, sessions, logs, OAuth credentials, Kimi-specific user Skills, global `AGENTS.md`, and more — lands under the new path. For the full reference on `KIMI_CODE_HOME`, see [Environment variables](./env-vars.md).
 
-::: tip Two types of data are not affected by `KIMI_CODE_HOME`
+::: tip Note
 
 **Built-in tool cache** (ripgrep binary) uses `KIMI_CODE_CACHE_DIR` instead. When that is unset, the platform cache directory is used: `~/Library/Caches/kimi-code` on macOS, `~/.cache/kimi-code` on Linux, and `%LOCALAPPDATA%\kimi-code` on Windows.
 
-**Agent Skills** search paths are `~/.kimi-code/skills` and `~/.agents/skills` (user level), and `.kimi-code/skills` and `.agents/skills` under the working directory (project level). See [Agent Skills](../customization/skills.md).
+**Generic `.agents` resources** stay under the real OS home so they can be shared across tools. For example, user-level generic Skills remain at `~/.agents/skills/`, while Kimi-specific user Skills move with `KIMI_CODE_HOME` as `$KIMI_CODE_HOME/skills/`.
 :::
 
 ## Directory layout
@@ -31,7 +31,9 @@ Once set, **all** data — config, sessions, logs, OAuth credentials, and more
 $KIMI_CODE_HOME  (default: ~/.kimi-code)
 ├── config.toml             # User configuration
 ├── tui.toml                # Terminal UI preferences (including auto-update toggle)
+├── AGENTS.md               # Global Kimi-specific agent instructions (optional)
 ├── mcp.json                # User-level MCP server declarations (optional)
+├── skills/                 # Kimi-specific user-level Skills (optional)
 ├── plugins/
 │   ├── installed.json      # Installed plugin records and enabled state
 │   └── managed/            # Plugin copies installed from zip/local paths
@@ -60,7 +62,9 @@ Each top-level file under the data root serves a specific purpose; most are mana
 
 - **`config.toml`**: the main runtime configuration file, storing user-level settings such as providers, models, and loop control. See [Configuration files](./config-files.md).
 - **`tui.toml`**: terminal UI client preferences, including `[upgrade].auto_install` (auto-update, on by default). You can disable it in `/settings` or by manually setting `auto_install = false`.
+- **`AGENTS.md`**: global Kimi-specific agent instructions. This file moves with `KIMI_CODE_HOME`; generic cross-tool instructions can still live under `~/.agents/AGENTS.md`.
 - **`mcp.json`**: user-level MCP server declarations, merged with the project-local `.kimi-code/mcp.json` on startup. See [MCP](../customization/mcp.md).
+- **`skills/`**: Kimi-specific user-level Skills. This directory moves with `KIMI_CODE_HOME`; generic cross-tool Skills can still live under `~/.agents/skills/`. See [Agent Skills](../customization/skills.md).
 - **`plugins/installed.json`**: records installed plugins, each plugin's enabled state, and MCP server capability state changes made via `/plugins` or `/plugins mcp disable|enable`. Files installed from local paths or zip URLs are copied to `plugins/managed/<id>/`. See [Plugins](../customization/plugins.md).
 - **`credentials/`**: OAuth credential directory, with permissions `0o700` (directory) / `0o600` (files), readable and writable only by the current user. Managed provider credentials are stored as `credentials/<name>.json`; MCP server credentials are stored under `credentials/mcp/`. Credentials are written using an atomic flow (tmp → fsync → rename) to prevent corruption.
 
@@ -111,9 +115,10 @@ Deleting the data root directory (`~/.kimi-code/` or the path set by `KIMI_CODE_
 | Force re-download of ripgrep | Delete `~/.kimi-code/bin/` |
 | Clear provider OAuth login state | Run `/logout`, or delete the corresponding `credentials/<name>.json` |
 | Clear MCP server OAuth login state | Delete `credentials/mcp/` (`/logout` does not clear MCP credentials) |
-| Remove user-level MCP declarations | Delete `~/.kimi-code/mcp.json` |
-| Clear plugin install records | Delete `~/.kimi-code/plugins/` (local plugin source directories are not affected) |
-| Clear user-level Skills | Delete `~/.kimi-code/skills/` |
+| Remove user-level MCP declarations | Delete `$KIMI_CODE_HOME/mcp.json` (default `~/.kimi-code/mcp.json`) |
+| Clear global Kimi-specific agent instructions | Delete `$KIMI_CODE_HOME/AGENTS.md` (default `~/.kimi-code/AGENTS.md`) |
+| Clear plugin install records | Delete `$KIMI_CODE_HOME/plugins/` (local plugin source directories are not affected) |
+| Clear Kimi-specific user-level Skills | Delete `$KIMI_CODE_HOME/skills/` (default `~/.kimi-code/skills/`) |
 
 ## Next steps
 

diff --git a/docs/en/customization/agents.md b/docs/en/customization/agents.md
@@ -37,6 +37,10 @@ Sub-agent permission rules are inherited from the main Agent: "always allow" rul
 
 If you need a particular type of tool to be permanently unavailable inside sub-agents, tighten the corresponding permission rule on the main Agent.
 
+## Instruction Files
+
+Global Kimi-specific instructions can live at `$KIMI_CODE_HOME/AGENTS.md` (default: `~/.kimi-code/AGENTS.md`). When you relocate the data root with `KIMI_CODE_HOME`, this global instruction file moves with it. Generic cross-tool instructions can still live under `~/.agents/AGENTS.md` in the real OS home, and project-level instructions remain under the project tree, for example `.kimi-code/AGENTS.md` or `AGENTS.md`.
+
 ## Storage Location in the Session Directory
 
 Sub-agent runtime state is persisted to the `agents/` subdirectory of the current session directory. Each sub-agent instance has its own directory, which contains a `wire.jsonl` file that records prompts, message history, and final state in chronological order. Background sub-agents also expose their lifecycle status through a `tasks/` subdirectory.

diff --git a/docs/en/customization/skills.md b/docs/en/customization/skills.md
@@ -66,9 +66,11 @@ Positional arguments support single and double quoting, so in `/skill:commit "fi
 Kimi Code CLI scans four tiers by scope; more specific scopes take higher priority: **Project > User > Extra > Built-in**
 
 **User level** (applies to all projects):
-- `~/.kimi-code/skills/`
+- `$KIMI_CODE_HOME/skills/` (default: `~/.kimi-code/skills/`)
 - `~/.agents/skills/`
 
+The Kimi-specific user Skill directory moves with `KIMI_CODE_HOME`, so isolated data roots also get isolated Kimi-specific Skills. The generic `~/.agents/skills/` directory stays under the real OS home so it can be shared across tools.
+
 **Project level** (project root = the nearest directory containing `.git`, searching upward from the working directory):
 - `.kimi-code/skills/`
 - `.agents/skills/`
@@ -120,7 +122,7 @@ Please review the PR the user specified: $pr_ref
    - Noteworthy positives
 ```
 
-Save this as `~/.kimi-code/skills/review-pr/SKILL.md`, place the checklist at `references/checklist.md` in the same directory, and after starting a new session you can invoke it with `/skill:review-pr #1234`, where `#1234` is expanded into `$pr_ref`.
+Save this as `$KIMI_CODE_HOME/skills/review-pr/SKILL.md` (or `~/.kimi-code/skills/review-pr/SKILL.md` when `KIMI_CODE_HOME` is unset), place the checklist at `references/checklist.md` in the same directory, and after starting a new session you can invoke it with `/skill:review-pr #1234`, where `#1234` is expanded into `$pr_ref`.
 
 ## Next steps
 

diff --git a/docs/zh/configuration/data-locations.md b/docs/zh/configuration/data-locations.md
@@ -16,13 +16,15 @@ Kimi Code CLI 把所有运行时数据——配置文件、会话历史、登录
 export KIMI_CODE_HOME="$HOME/.config/kimi-code"
 ```
 
-设置后，配置、会话、日志、OAuth 凭据等**全部**数据都会落到新路径下。`KIMI_CODE_HOME` 的完整说明见[环境变量](./env-vars.md)。
+设置后，配置、会话、日志、OAuth 凭据、Kimi 专属用户级 Skills、全局 `AGENTS.md` 等 **Kimi Code 数据**都会落到新路径下。`KIMI_CODE_HOME` 的完整说明见[环境变量](./env-vars.md)。
 
-::: tip 两类数据不受 `KIMI_CODE_HOME` 影响
+::: tip 提示
+
+部分路径不受 `KIMI_CODE_HOME` 影响。
 
 **内置工具缓存**（ripgrep 二进制）走的是 `KIMI_CODE_CACHE_DIR`，未设时使用平台缓存目录：macOS 的 `~/Library/Caches/kimi-code`、Linux 的 `~/.cache/kimi-code`、Windows 的 `%LOCALAPPDATA%\kimi-code`。
 
-**Agent Skills** 的搜索路径是 `~/.kimi-code/skills` 和 `~/.agents/skills`（用户级），以及工作目录下的 `.kimi-code/skills` 和 `.agents/skills`（项目级）。详见 [Agent Skills](../customization/skills.md)。
+**通用 `.agents` 资源**仍放在真实 OS home 下，以便跨工具共享。例如，用户级通用 Skills 仍位于 `~/.agents/skills/`，而 Kimi 专属用户级 Skills 会随 `KIMI_CODE_HOME` 移动到 `$KIMI_CODE_HOME/skills/`。
 :::
 
 ## 目录结构
@@ -31,7 +33,9 @@ export KIMI_CODE_HOME="$HOME/.config/kimi-code"
 $KIMI_CODE_HOME  （默认 ~/.kimi-code）
 ├── config.toml             # 用户配置
 ├── tui.toml                # 终端界面偏好（含自动更新开关）
+├── AGENTS.md               # 全局 Kimi 专属 Agent 指令（可选）
 ├── mcp.json                # 用户级 MCP server 声明（可选）
+├── skills/                 # Kimi 专属用户级 Skills（可选）
 ├── plugins/
 │   ├── installed.json      # 已安装 plugin 记录与启用状态
 │   └── managed/            # zip/本地路径安装的 plugin 副本
@@ -60,7 +64,9 @@ $KIMI_CODE_HOME  （默认 ~/.kimi-code）
 
 - **`config.toml`**：主运行时配置，存放供应商、模型、循环控制等用户级设置。详见[配置文件](./config-files.md)。
 - **`tui.toml`**：终端界面客户端偏好，包括 `[upgrade].auto_install`（自动更新，默认开启）。可在 `/settings` 关闭，或手动设为 `auto_install = false`。
+- **`AGENTS.md`**：全局 Kimi 专属 Agent 指令。该文件会随 `KIMI_CODE_HOME` 移动；跨工具通用指令仍可放在 `~/.agents/AGENTS.md`。
 - **`mcp.json`**：用户级 MCP server 声明，启动时与项目内的 `.kimi-code/mcp.json` 合并加载。详见 [MCP](../customization/mcp.md)。
+- **`skills/`**：Kimi 专属用户级 Skills。该目录会随 `KIMI_CODE_HOME` 移动；跨工具通用 Skills 仍可放在 `~/.agents/skills/`。详见 [Agent Skills](../customization/skills.md)。
 - **`plugins/installed.json`**：记录已安装的 plugin、每个 plugin 的启用状态，以及通过 `/plugins` 或 `/plugins mcp disable|enable` 修改的 MCP server 能力状态。本地路径和 zip URL 安装的文件会复制到 `plugins/managed/<id>/`。详见 [Plugins](../customization/plugins.md)。
 - **`credentials/`**：OAuth 凭据目录，权限 `0o700`（目录）/ `0o600`（文件），仅当前用户可读写。托管供应商凭据存为 `credentials/<name>.json`，MCP server 凭据存在 `credentials/mcp/` 子目录下。凭据写入使用原子流程（tmp → fsync → rename）防止写损。
 
@@ -111,9 +117,10 @@ CLI 第一次需要 ripgrep 时会自动下载并缓存到 `bin/rg`（Windows
 | 强制重新下载 ripgrep | 删除 `~/.kimi-code/bin/` |
 | 清除供应商 OAuth 登录态 | 运行 `/logout`，或删除对应的 `credentials/<name>.json` |
 | 清除 MCP server OAuth 登录态 | 删除 `credentials/mcp/`（`/logout` 不会清理 MCP 凭据） |
-| 移除用户级 MCP 声明 | 删除 `~/.kimi-code/mcp.json` |
-| 清理 plugin 安装记录 | 删除 `~/.kimi-code/plugins/`（本地 plugin 源码不受影响） |
-| 清空用户级 Skills | 删除 `~/.kimi-code/skills/` |
+| 移除用户级 MCP 声明 | 删除 `$KIMI_CODE_HOME/mcp.json`（默认为 `~/.kimi-code/mcp.json`） |
+| 清理全局 Kimi 专属 Agent 指令 | 删除 `$KIMI_CODE_HOME/AGENTS.md`（默认为 `~/.kimi-code/AGENTS.md`） |
+| 清理 plugin 安装记录 | 删除 `$KIMI_CODE_HOME/plugins/`（本地 plugin 源码不受影响） |
+| 清空 Kimi 专属用户级 Skills | 删除 `$KIMI_CODE_HOME/skills/`（默认为 `~/.kimi-code/skills/`） |
 
 ## 下一步
 

diff --git a/docs/zh/customization/agents.md b/docs/zh/customization/agents.md
@@ -37,6 +37,10 @@ Kimi Code CLI 内置三种子 Agent，开箱即用，分别面向不同任务形
 
 如果需要某类工具在子 Agent 中始终不可用，应收紧主 Agent 的权限规则。
 
+## 指令文件
+
+全局 Kimi 专属指令可放在 `$KIMI_CODE_HOME/AGENTS.md`（默认：`~/.kimi-code/AGENTS.md`）。当你用 `KIMI_CODE_HOME` 移动数据根时，这份全局指令文件也会一起移动。跨工具通用指令仍可放在真实 OS home 下的 `~/.agents/AGENTS.md`，项目级指令仍放在项目目录中，例如 `.kimi-code/AGENTS.md` 或 `AGENTS.md`。
+
 ## 会话目录中的存储位置
 
 子 Agent 的运行状态持久化到当前会话目录的 `agents/` 子目录下，每个子 Agent 实例对应一个独立目录，其中包含按时间顺序记录提示词、消息历史与最终状态的 `wire.jsonl` 文件。后台子 Agent 还会通过 `tasks/` 子目录暴露生命周期状态。

diff --git a/docs/zh/customization/skills.md b/docs/zh/customization/skills.md
@@ -66,9 +66,11 @@ arguments:
 Kimi Code CLI 按作用域分四档扫描，越具体的作用域优先级越高：**Project > User > Extra > Built-in**
 
 **用户级**（对所有项目生效）：
-- `~/.kimi-code/skills/`
+- `$KIMI_CODE_HOME/skills/`（默认：`~/.kimi-code/skills/`）
 - `~/.agents/skills/`
 
+Kimi 专属用户级 Skill 目录会随 `KIMI_CODE_HOME` 移动，因此隔离数据根时也会隔离 Kimi 专属 Skills。通用 `~/.agents/skills/` 目录仍放在真实 OS home 下，以便跨工具共享。
+
 **项目级**（项目根 = 工作目录向上最近的含 `.git` 的目录）：
 - `.kimi-code/skills/`
 - `.agents/skills/`
@@ -120,7 +122,7 @@ arguments:
    - 值得肯定的地方
 ```
 
-保存为 `~/.kimi-code/skills/review-pr/SKILL.md`，检查清单放在同目录的 `references/checklist.md`，重开会话后即可通过 `/skill:review-pr #1234` 调用，其中 `#1234` 会展开到 `$pr_ref`。
+保存为 `$KIMI_CODE_HOME/skills/review-pr/SKILL.md`（未设置 `KIMI_CODE_HOME` 时为 `~/.kimi-code/skills/review-pr/SKILL.md`），检查清单放在同目录的 `references/checklist.md`，重开会话后即可通过 `/skill:review-pr #1234` 调用，其中 `#1234` 会展开到 `$pr_ref`。
 
 ## 下一步
 

diff --git a/packages/agent-core/src/profile/context.ts b/packages/agent-core/src/profile/context.ts
@@ -13,15 +13,16 @@ export type PreparedSystemPromptContext = Pick<SystemPromptContext, 'cwdListing'
 
 export async function prepareSystemPromptContext(
   kaos: Kaos,
+  brandHome?: string,
 ): Promise<PreparedSystemPromptContext> {
   const [cwdListing, agentsMd] = await Promise.all([
     listDirectory(kaos),
-    loadAgentsMd(kaos),
+    loadAgentsMd(kaos, brandHome),
   ]);
   return { cwdListing, agentsMd };
 }
 
-export async function loadAgentsMd(kaos: Kaos): Promise<string> {
+export async function loadAgentsMd(kaos: Kaos, brandHome?: string): Promise<string> {
   const workDir = kaos.getcwd();
   const projectRoot = await findProjectRoot(kaos, workDir);
   const dirs = dirsRootToLeaf(kaos, workDir, projectRoot);
@@ -39,11 +40,14 @@ export async function loadAgentsMd(kaos: Kaos): Promise<string> {
   };
 
   // User-level files come first so any project-level AGENTS.md overrides them.
-  const home = kaos.gethome();
-  await collect(join(home, '.kimi-code', 'AGENTS.md'));
+  // The brand dir follows KIMI_CODE_HOME (default ~/.kimi-code); the generic
+  // .agents dir stays under the real OS home so it can be shared across tools.
+  const realHome = kaos.gethome();
+  const brandDir = brandHome ?? join(realHome, '.kimi-code');
+  await collect(join(brandDir, 'AGENTS.md'));
 
   // Generic user-level dir (.agents) matches skill discovery.
-  const genericDirs = [join(home, '.agents')];
+  const genericDirs = [join(realHome, '.agents')];
   const genericFiles = genericDirs.flatMap((dir) =>
     ['AGENTS.md', 'agents.md'].map((name) => join(dir, name)),
   );

diff --git a/packages/agent-core/src/rpc/core-impl.ts b/packages/agent-core/src/rpc/core-impl.ts
@@ -778,6 +778,7 @@ export class KimiCore implements PromisableMethods<CoreAPI> {
     const explicitDirs = this.skillDirs.length > 0 ? this.skillDirs : undefined;
     return {
       userHomeDir: this.userHomeDir,
+      brandHomeDir: this.homeDir,
       explicitDirs,
       extraDirs: config.extraSkillDirs,
       pluginSkillRoots: this.plugins.pluginSkillRoots(),

diff --git a/packages/agent-core/src/session/index.ts b/packages/agent-core/src/session/index.ts
@@ -65,6 +65,8 @@ export interface SessionOptions {
 
 export interface SessionSkillConfig {
   readonly userHomeDir?: string;
+  /** Brand data dir (KIMI_CODE_HOME); user brand skills live under `<brandHomeDir>/skills`. */
+  readonly brandHomeDir?: string;
   readonly explicitDirs?: readonly string[];
   readonly extraDirs?: readonly string[];
   readonly pluginSkillRoots?: readonly SkillRoot[];
@@ -323,7 +325,7 @@ export class Session {
     agent: Agent,
     profile: ResolvedAgentProfile,
   ): Promise<void> {
-    const context = await prepareSystemPromptContext(agent.kaos);
+    const context = await prepareSystemPromptContext(agent.kaos, this.options.kimiHomeDir);
     agent.useProfile(profile, context);
   }
 
@@ -342,7 +344,7 @@ export class Session {
       });
       await handle.completion;
 
-      const agentsMd = await loadAgentsMd(mainAgent.kaos);
+      const agentsMd = await loadAgentsMd(mainAgent.kaos, this.options.kimiHomeDir);
       mainAgent.context.appendSystemReminder(initCompletionReminder(agentsMd), {
         kind: 'injection',
         variant: 'init',
@@ -399,6 +401,7 @@ export class Session {
     const roots = await resolveSkillRoots({
       paths: {
         userHomeDir: this.options.skills?.userHomeDir ?? homedir(),
+        brandHomeDir: this.options.skills?.brandHomeDir ?? this.options.kimiHomeDir,
         workDir: this.options.kaos.getcwd(),
       },
       explicitDirs: this.options.skills?.explicitDirs,

diff --git a/packages/agent-core/src/session/subagent-host.ts b/packages/agent-core/src/session/subagent-host.ts
@@ -362,7 +362,7 @@ export class SessionSubagentHost {
       thinkingLevel: parent.config.thinkingLevel,
     });
 
-    const context = await prepareSystemPromptContext(child.kaos);
+    const context = await prepareSystemPromptContext(child.kaos, this.session.options.kimiHomeDir);
     child.useProfile(profile, context);
     child.tools.inheritUserTools(parent.tools);
   }