docs: clarify Windows agent CLI invocation

README.md

@@ -136,7 +136,7 @@ cd gitlink-cli
 make install
 ```
 
-> **Windows users:** Run `npm install -g @gitlink-ai/cli` in PowerShell or CMD. For building from source, use `go install .` instead of `make install`.
+> **Windows users:** Run `npm install -g @gitlink-ai/cli` in PowerShell or CMD. For building from source, use `go install .` instead of `make install`. If your Agent or shell uses Git Bash, see the FAQ below for the `node .../bin/cli.js` fallback invocation.
 
 #### Configure & Use
 
@@ -742,6 +742,35 @@ If the error persists, check whether the release page contains the asset for you
 for example `gitlink-cli_<version>_windows_amd64.zip` on Windows x64.
 You can also download the binary manually from the release page or build from source with `go install .`.
 
+### Q: What if `gitlink-cli` works in PowerShell/CMD but fails in Git Bash or a Windows Agent shell?
+
+On Windows, `npm install -g @gitlink-ai/cli` creates npm shims. PowerShell and CMD can execute those shims directly, but some Git Bash based Agents cannot.
+
+Use the direct Node entry instead:
+
+```bash
+GITLINK_CLI="$(npm root -g)/@gitlink-ai/cli/bin/cli.js"
+node "$GITLINK_CLI" user +info --login <login> --format json
+```
+
+If `npm root -g` is unavailable, locate the global package first and run the entry file manually:
+
+```bash
+npm list -g @gitlink-ai/cli --depth=0
+node "/c/Program Files/nodejs/node_modules/@gitlink-ai/cli/bin/cli.js" user +info --login <login> --format json
+```
+
+For Skills and Agent prompts, prefer documenting both forms:
+
+```bash
+# PowerShell / CMD / macOS / Linux
+gitlink-cli user +info --login <login> --format json
+
+# Windows Git Bash or shim-incompatible Agent shells
+GITLINK_CLI="$(npm root -g)/@gitlink-ai/cli/bin/cli.js"
+node "$GITLINK_CLI" user +info --login <login> --format json
+```
+
 ### Q: Where are credentials stored on Windows?
 
 gitlink-cli uses Windows Credential Manager for secure token storage. If Credential Manager is unavailable, it automatically falls back to file storage (`~/.config/gitlink-cli/credentials`).

README.zh-CN.md

@@ -144,7 +144,7 @@ make install
 npx skills add ./skills -y -g
 ```
 
-> **Windows 用户注意：** 请在 PowerShell 或 CMD 中运行 `npm install -g @gitlink-ai/cli`。从源码构建请使用 `go install .` 代替 `make install`。
+> **Windows 用户注意：** 请在 PowerShell 或 CMD 中运行 `npm install -g @gitlink-ai/cli`。从源码构建请使用 `go install .` 代替 `make install`。如果你的 Agent 或 Shell 使用 Git Bash，请参考下方 FAQ 中的 `node .../bin/cli.js` 兜底调用方式。
 
 #### 配置与使用
 
@@ -617,6 +617,35 @@ npm install -g @gitlink-ai/cli
 
 如果仍然失败，请检查 Release 页面是否包含当前平台的资产，例如 Windows x64 对应 `gitlink-cli_<version>_windows_amd64.zip`。也可以从 Release 页面手动下载二进制，或使用 `go install .` 从源码构建。
 
+### Q: 为什么 `gitlink-cli` 在 PowerShell/CMD 可用，但在 Git Bash 或 Windows Agent Shell 里失败？
+
+在 Windows 上，`npm install -g @gitlink-ai/cli` 会生成 npm shim。PowerShell 和 CMD 可以直接执行这些 shim，但部分基于 Git Bash 的 Agent Shell 不能正确处理。
+
+这时请直接调用 Node 入口文件：
+
+```bash
+GITLINK_CLI="$(npm root -g)/@gitlink-ai/cli/bin/cli.js"
+node "$GITLINK_CLI" user +info --login <login> --format json
+```
+
+如果 `npm root -g` 不可用，先定位全局安装目录，再手动执行入口文件：
+
+```bash
+npm list -g @gitlink-ai/cli --depth=0
+node "/c/Program Files/nodejs/node_modules/@gitlink-ai/cli/bin/cli.js" user +info --login <login> --format json
+```
+
+在 Skill 或 Agent 提示词中，建议同时写明这两种调用方式：
+
+```bash
+# PowerShell / CMD / macOS / Linux
+gitlink-cli user +info --login <login> --format json
+
+# Windows Git Bash 或不兼容 npm shim 的 Agent Shell
+GITLINK_CLI="$(npm root -g)/@gitlink-ai/cli/bin/cli.js"
+node "$GITLINK_CLI" user +info --login <login> --format json
+```
+
 ### Q: Windows 上凭证存储在哪里？
 
 gitlink-cli 使用 Windows Credential Manager 安全存储 Token。如果 Credential Manager 不可用，会自动降级到文件存储（`~/.config/gitlink-cli/credentials`）。

doc/changes/windows-agent-invocation.md

@@ -0,0 +1,11 @@
+# Windows Agent Shell 调用说明
+
+在 Windows 上通过 `npm install -g @gitlink-ai/cli` 安装 CLI 后，PowerShell 和 CMD 可以直接执行 npm 生成的 shim，但部分基于 Git Bash 的 Agent Shell 不能正确处理 `.cmd` 包装器，导致 `gitlink-cli` 命令执行失败。
+
+本次更新不修改 Go 主程序，而是补充稳定的调用约定：
+
+- PowerShell / CMD / macOS / Linux 继续直接使用 `gitlink-cli ...`
+- Windows Git Bash 或 shim 不兼容的 Agent Shell 改为通过 Node 直接执行 `@gitlink-ai/cli/bin/cli.js`
+- 在 `README`、`README.zh-CN` 和 `skills/gitlink-shared/SKILL.md` 中都增加了可复制的 fallback 命令
+
+这样做可以让 Skill、Agent 提示词和人工排障文档对齐，避免 Windows 上 “PowerShell 可用、Git Bash 失败” 的调用差异继续反复出现。

skills/gitlink-shared/SKILL.md

@@ -48,6 +48,29 @@ gitlink-cli auth login
 - 确认用户是否有对应资源的权限
 - 确认 owner/repo 是否正确
 
+### Windows Shell 调用说明
+
+- PowerShell、CMD、macOS、Linux：优先直接调用 `gitlink-cli`
+- Windows Git Bash 或部分 Agent Shell：npm 生成的 shim 可能无法正常执行，此时改为直接调用 Node 入口文件
+
+```bash
+# 常规调用方式
+gitlink-cli user +info --login <login> --format json
+
+# Windows Git Bash / shim 不兼容时的兜底方式
+GITLINK_CLI="$(npm root -g)/@gitlink-ai/cli/bin/cli.js"
+node "$GITLINK_CLI" user +info --login <login> --format json
+```
+
+如果 `npm root -g` 不可用，先查全局安装路径，再手动执行入口文件：
+
+```bash
+npm list -g @gitlink-ai/cli --depth=0
+node "/c/Program Files/nodejs/node_modules/@gitlink-ai/cli/bin/cli.js" user +info --login <login> --format json
+```
+
+在 Windows Agent 场景里，如果用户只提供了 `gitlink-cli ...` 命令且当前 shell 是 Git Bash，优先改写成上面的 `node "$GITLINK_CLI" ...` 形式后再执行。
+
 ## 全局参数
 
 | 参数 | 说明 |