From b1b294938c2c5e97a6995b22897de8cf5e671e49 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Thu, 20 Aug 2026 17:48:55 +0800
Subject: [PATCH] docs(skills): clarify Rslint migration config

---
 .agents/skills/migrate-to-rstack-cli/SKILL.md |  8 +++++++-
 .../references/rslint.md                      | 20 ++++++++++++++++---
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/.agents/skills/migrate-to-rstack-cli/SKILL.md b/.agents/skills/migrate-to-rstack-cli/SKILL.md
index 992cf06c..01612d1b 100644
--- a/.agents/skills/migrate-to-rstack-cli/SKILL.md
+++ b/.agents/skills/migrate-to-rstack-cli/SKILL.md
@@ -34,7 +34,11 @@ Read every matching reference before editing. Load only the tools present in the
 
 Rsbuild, Rslib, Rstest, Rslint, and Prettier remain transitive `rstack` dependencies. Remove obsolete direct dependencies and imports from the migrated scope; do not expect their names to disappear from the lockfile.
 
-## Configuration Rules
+## Configuration
+
+### Config Files
+
+Treat each workspace or config root independently. A monorepo may need multiple Rstack config files when commands run from different package directories; validate config discovery from each directory.
 
 Use one of the default names: `rstack.config.ts`, `.js`, `.mts`, or `.mjs`.
 
@@ -53,6 +57,8 @@ define.test({
 });
 ```
 
+### Modules and Imports
+
 Use dynamic imports in async config functions only for external plugins, presets, and other dependencies:
 
 ```ts
diff --git a/.agents/skills/migrate-to-rstack-cli/references/rslint.md b/.agents/skills/migrate-to-rstack-cli/references/rslint.md
index d193b09a..e2c68154 100644
--- a/.agents/skills/migrate-to-rstack-cli/references/rslint.md
+++ b/.agents/skills/migrate-to-rstack-cli/references/rslint.md
@@ -6,9 +6,10 @@ Read this reference when the project uses `@rslint/core`, `rslint.config.*`, `rs
 
 1. Replace the `rslint` executable prefix with `rs lint`. For example, replace `rslint --fix` with `rs lint --fix`.
 2. Move the old config into `define.lint`, replacing Rslint's `defineConfig()` wrapper and import. Receive `@rslint/core` exports from the factory parameter.
-3. Replace custom `--config` paths with the migrated `rstack.config.*` path.
-4. Remove `@rslint/core` only when no uncovered direct runtime API remains. Delete `rslint.config.*`.
-5. If tracked VS Code configuration recommends `rstack.rslint`, replace it with the unified `rstack.rstack` extension. Move relevant `rslint.*` settings to their current `rstack.rslint.*` equivalents according to the [Rstack extension documentation](https://github.com/rstackjs/rstack-editor/blob/main/packages/vscode/README.md). Keep `source.fixAll.rslint` unchanged.
+3. If the old config imports the `globals` package for environment maps such as `globals.browser`, receive `globals` from the factory parameter instead. Remove the direct `globals` dependency after confirming that no other file uses it.
+4. Replace custom `--config` paths with the migrated `rstack.config.*` path.
+5. Remove `@rslint/core` only when no uncovered direct runtime API remains. Delete `rslint.config.*`.
+6. If tracked VS Code configuration recommends `rstack.rslint`, replace it with the unified `rstack.rstack` extension. Move relevant `rslint.*` settings to their current `rstack.rslint.*` equivalents according to the [Rstack extension documentation](https://github.com/rstackjs/rstack-editor/blob/main/packages/vscode/README.md). Keep `source.fixAll.rslint` unchanged.
 
 ## Config Pattern
 
@@ -23,6 +24,19 @@ define.lint(({ js, ts }) => [
 
 Preserve existing presets and rules during migration.
 
+The factory also provides Rslint's built-in globals catalog, so an external `globals` import is unnecessary:
+
+```ts
+define.lint(({ globals }) => [
+  {
+    files: ['**/*.{js,cjs,mjs}'],
+    languageOptions: {
+      globals: globals.browser,
+    },
+  },
+]);
+```
+
 ## Script Pattern
 
 If a script also runs Prettier, migrate its formatting command as described in [prettier.md](prettier.md).