From f2fe859c1a61a5decb70ae70c30a9a1dcb33fb50 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Wed, 2 Sep 2026 16:17:12 +0800
Subject: [PATCH] docs: clarify config imports in migration skill

---
 .agents/skills/migrate-to-rstack-cli/SKILL.md       | 13 ++++++-------
 .../migrate-to-rstack-cli/references/rsbuild.md     | 10 +++++-----
 .../migrate-to-rstack-cli/references/rspress.md     |  2 +-
 3 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/.agents/skills/migrate-to-rstack-cli/SKILL.md b/.agents/skills/migrate-to-rstack-cli/SKILL.md
index 0bb1957..770e99f 100644
--- a/.agents/skills/migrate-to-rstack-cli/SKILL.md
+++ b/.agents/skills/migrate-to-rstack-cli/SKILL.md
@@ -72,23 +72,22 @@ define.test({
 
 ### Modules and imports
 
-Keep type-only and Node.js built-in imports at the top level. In async config functions, use a separate `await import(...)` for each tool-specific runtime dependency.
+Rstack loads every top-level import when it reads `rstack.config.*`. Prefer static imports when a config is only for an application and its tests, a library and its tests, or a documentation site.
+
+If the same config also includes lint, formatting, or staged-file checks, dynamically import dependencies inside the relevant async config function to avoid loading them during checks. Keep type-only and Node.js built-in imports at the top level.
 
 ```ts
 define.app(async () => {
   const { pluginReact } = await import('@rsbuild/plugin-react');
-  const { pluginSass } = await import('@rsbuild/plugin-sass');
 
   return {
-    plugins: [pluginReact(), pluginSass()],
+    plugins: [pluginReact()],
   };
 });
-```
-
-`define.lint` provides `@rslint/core` APIs to its config factory, so no manual import is needed:
 
-```ts
 define.lint(({ js }) => [js.configs.recommended]);
 ```
 
+`define.lint` provides `@rslint/core` APIs to its config factory, so no manual import is needed.
+
 Rstack loads TypeScript configs as native ESM. Preserve runtime-resolvable file extensions, replace CommonJS globals such as `__dirname`.
diff --git a/.agents/skills/migrate-to-rstack-cli/references/rsbuild.md b/.agents/skills/migrate-to-rstack-cli/references/rsbuild.md
index 9abb19e..21e0be9 100644
--- a/.agents/skills/migrate-to-rstack-cli/references/rsbuild.md
+++ b/.agents/skills/migrate-to-rstack-cli/references/rsbuild.md
@@ -18,18 +18,18 @@ Read this reference when the project uses `@rsbuild/core`, `rsbuild.config.*`, `
 ## Config pattern
 
 ```ts
+import { pluginReact } from '@rsbuild/plugin-react';
 import { define } from 'rstack';
 
-define.app(async () => {
-  const { pluginReact } = await import('@rsbuild/plugin-react');
-  return {
-    plugins: [pluginReact()],
-  };
+define.app({
+  plugins: [pluginReact()],
 });
 ```
 
 If tests also use Rstest, read [rstest.md](rstest.md). `rs test` derives an Rsbuild test extension from `define.app` unless `define.test` sets `extends`.
 
+Follow [Modules and imports](../SKILL.md#modules-and-imports) when the config imports plugins or themes.
+
 ## Validate
 
 Run the migrated app build script. Smoke-test dev or preview when those scripts changed or their behavior is material.
diff --git a/.agents/skills/migrate-to-rstack-cli/references/rspress.md b/.agents/skills/migrate-to-rstack-cli/references/rspress.md
index 9b7b79b..e008fb3 100644
--- a/.agents/skills/migrate-to-rstack-cli/references/rspress.md
+++ b/.agents/skills/migrate-to-rstack-cli/references/rspress.md
@@ -22,7 +22,7 @@ define.doc({
 });
 ```
 
-Use an async config and dynamic imports when plugins or themes require runtime imports.
+Follow [Modules and imports](../SKILL.md#modules-and-imports) when the config imports plugins or themes.
 
 ## Validate