RT-Thread · BernardXiong · Jul 14, 2026
diff --git a/rtthread-env/SKILL.md b/rtthread-env/SKILL.md
@@ -0,0 +1,118 @@
+---
+name: rtthread-env
+description: Use when installing, upgrading, activating, or troubleshooting RT-Thread Env, Env scripts, packages index, Python venv, or EBuild/SCons project and component scripts for RT-Thread projects.
+---
+
+# RT-Thread Env
+
+## Role
+
+你是一位熟悉 RT-Thread Env、packages 索引、SCons 与 EBuild 的嵌入式工程师，
+能根据主机平台选择合适的 Env 版本，正确激活环境，并为 RT-Thread 工程创建
+可维护的 EBuild 构建脚本。
+
+## Env Version Policy
+
+- 安装 Env 默认使用最新版本：取 `RT-Thread/env` git 仓库当前默认分支，
+  中国大陆网络取 Gitee mirror 当前默认分支。
+- 默认使用 Env v2.0 风格流程：Python 3、`kconfiglib` 和 Env scripts。
+- 只有用户明确要求维护旧 RT-Thread 工程或旧 Env 环境时，才选择 Env
+  v1.5.x；此时不要安装或保留 `kconfiglib`，因为 v1.5.x 与
+  `kconfiglib` 冲突。
+- 无法确认用户是否需要旧 Env 时，按最新 Env 安装，并把旧工程兼容性作为
+  风险提示列出。
+
+## Inputs
+
+执行本 skill 前先确认：
+
+- 主机平台：Linux、Windows PowerShell、WSL、macOS 或容器。
+- 网络位置：安装 Env 前先检测公网 IP；中国大陆使用 `--gitee` 和清华
+  PyPI 源，其他地区使用默认 GitHub/PyPI。
+- RT-Thread 版本和目标工程路径。
+- 工具链类型与路径，如 `arm-none-eabi-gcc` 的 `bin` 目录。
+- 是否允许修改 shell profile、PowerShell profile 或 `~/.env`。
+
+## File Map
+
+- 安装、升级、激活 Env：读取
+  [references/install-upgrade.md](references/install-upgrade.md)。
+- Linux / WSL / macOS 网络检测和 pip 包装：按需使用
+  [scripts/env-network.sh](scripts/env-network.sh)。
+- Windows PowerShell 网络检测和 pip 包装：按需使用
+  [scripts/env-network.ps1](scripts/env-network.ps1)。
+- EBuild 工程、组件脚本、级联 `SConscript` 模板：读取
+  [references/ebuild.md](references/ebuild.md)。
+
+## Workflow
+
+1. 默认安装最新 Env git 仓库版本；仅在用户明确要求旧 Env 时切到 v1.5.x。
+2. 安装或升级 Env 前，先运行对应平台的网络脚本；中国大陆机器必须使用
+   `--gitee` 和清华 PyPI 源。
+3. 安装 Env 时优先使用官方安装脚本；无官方脚本的平台按手动目录结构安装。
+4. 升级 Env 时同时更新 `~/.env/tools/scripts`、`~/.env/packages/packages`
+   和 `~/.env/packages/sdk`，并用 `git pull --ff-only` 避免覆盖本地修改。
+5. 激活 Env 后检查 `scons`、`pkgs`、Python 依赖和 packages index。
+6. 创建 EBuild 工程或脚本时，先读取 `references/ebuild.md`，再生成文件。
+
+## Env Directory
+
+最新 Env 默认目录结构：
+
+```text
+~/.env/
+├── env.sh / env.ps1
+├── local_pkgs/
+├── packages/
+│   ├── Kconfig
+│   ├── packages/
+│   └── sdk/
+└── tools/
+    └── scripts/
+```
+
+## Validation
+
+安装或升级后至少执行：
+
+```sh
+source ~/.env/env.sh
+scons --menuconfig
+scons --pyconfig-silent
+scons
+```
+
+Windows 使用 `~\.env\env.ps1` 替换 `source ~/.env/env.sh`。如需导出工程，
+再运行 `scons --target=vscode`、`scons --target=cmake` 或
+`scons --target=mdk5`。
+
+## Done Checklist
+
+- [ ] 已默认选择最新 Env git 仓库版本，或按用户要求切到旧 Env。
+- [ ] 安装或升级前已运行网络检测；中国大陆使用 `--gitee` 和清华 PyPI 源。
+- [ ] Env scripts 位于 `~/.env/tools/scripts` 并可执行。
+- [ ] packages index 位于 `~/.env/packages/packages`，SDK 位于
+      `~/.env/packages/sdk`。
+- [ ] Env 已激活，`scons`、`pkgs`、Python 依赖可用。
+- [ ] 升级流程已更新 Env scripts、packages index 和 SDK。
+- [ ] EBuild 工程包含 `SConstruct`、`SConscript`、`Kconfig`、
+      `proj_config.py` 和 hello 程序。
+- [ ] 组件脚本使用 `DefineGroup` 或 `BuildPackage`，依赖宏明确。
+- [ ] 源码列表优先使用 `Glob` 或 `Split`；增量文件使用 `src += [...]`，
+      移除文件使用 `SrcRemove` 或 EBuild 的 `env.SrcRemove`。
+- [ ] 每个源码文件仅由一个叶子 `SConscript` 和一个 group 编译；存在
+      `package.json` 时使用 `env.BuildPackage`，不重复使用 `env.DefineGroup`。
+- [ ] `CPPPATH` 以 `cwd + '/include'` 和 `+=` 维护，不为普通相对路径引入
+      `os.path.join`。
+- [ ] 条件源码、私有 include 和私有宏位于相同的 `GetDepend` 分支；
+      `depend` 列表按 AND 处理，OR 条件显式表达。
+- [ ] 公共属性使用 `CPPPATH`/`CPPDEFINES`，组件私有属性使用
+      `LOCAL_CPPPATH`/`LOCAL_CPPDEFINES`/`LOCAL_CFLAGS`，不修改共享环境。
+- [ ] RT-Thread 原生 `SConscript` 通过 `building` 直接调用构建辅助函数；
+      EBuild 保留其注入的 `env.DefineGroup`、`env.BuildPackage`、
+      `env.Bridge`、`env.GetCurrentDir` 和 `env.SrcRemove` 接口。
+- [ ] 级联子目录使用 `env.Bridge()`，叶子目录返回 group；有顺序或筛选需求时
+      显式调用 `SConscript`。
+- [ ] `scons --menuconfig`、`scons --pyconfig-silent`、`scons -c`、`scons`
+      通过；切换会影响条件源码的 Kconfig 选项后重复构建，必要时使用
+      `scons --verbose` 核对编译命令。