remote

Remote skill

Overview

Used to remotely access Linux servers and maintain setup state and server information in the local state directory.remote Only identifies the execution environment, not the code agent; the execution environment is uniformly determined by references/setup.md as windows-msys、linux-wsl、linux-native、macos-native。

The local state directory is uniformly ~/.local/share/remoteacross platforms (i.e. $XDG_DATA_HOME/remote, falling back to $HOME/.local/share/remotewhen XDG is not set). PowerShell's $HOME and git bash's $HOME point to the same physical directory, so the ps1 and sh entry points read and write the same state, and AppData\Local\remote。

Password passing mechanism:

• Windows（windows-msys): use the SSH_ASKPASS environment variable mechanism (natively supported by OpenSSH, no additional installation required)
• Linux/macOS/WSL: use sshpass

When to use

• Need to connect to a Linux server to execute read-only queries
• Need to collect output of multiple commands in parallel on the same server
• Need to reuse previously saved server address, port, username, and password
• First time accessing a server, or need to reconfirm connection information after an old record fails to log in
• Not applicable to high-risk operations actions such as batch write operations, restarts, file deletion, or configuration changes

Core flow

1. Entry point selection (two-level determination, OS first then shell):

   • Level 1 — OS determination:linux-wsl、linux-native、macos-native always goes through remote.sh / setup.sh，Do not check $BASH_VERSION(under macOS zsh it is also empty, which would cause a misjudgment).
   • Level 2 — only under windows-msys , use echo "${BASH_VERSION:-}" to distinguish the shell:
     • non-empty → currently git bash → go through scripts/remote.sh / scripts/setup.sh
     • empty → currently pwsh/cmd → go through scripts/remote.ps1 / scripts/setup.ps1
   • Principle: if already in git bash,directly use remote.sh, do not go around powershell -File remote.ps1 and then back to bash, otherwise it will introduce PowerShell↔bash path/escaping bridging issues.remote.ps1 is only used as the entry point for a pure PowerShell environment.

2. Check the bootstrap state through the standard script (do not directly read or guess the state file path):

   • bash environment:bash ./skills/remote/scripts/remote.sh --check-bootstrap
   • pwsh environment:powershell -ExecutionPolicy Bypass -File .\skills\remote\scripts\remote.ps1 -CheckBootstrap Exit code 0 means the environment is ready; a non-zero exit code means setup is required.

3. If the exit code is non-zero, you must read references/setup.md, and complete environment setup only through the standard script; do not manually probe authentication tools or run SSH bare. The setup entry point is likewise selected according to the two-level determination in step 0 (bash goes through setup.sh, pwsh goes through setup.ps1）。

4. Then check whether servers.json already has a record for the target server: use -Show -Address <目标> / --show "<目标>" to find a specific server, or use -Show / --show(without an address) to list all saved records. If a record is found, reuse it directly; if no record is found, immediately ask the user for the server address, username, and password, with the port defaulting to 22。

5. The standard entry points are fixed as follows (according to the two-level determination in step 0):

   • bash environment (including Windows git bash, Linux, macOS, WSL): through scripts/remote.sh and scripts/setup.sh
   • pwsh environment (Windows only): through scripts/remote.ps1 and scripts/setup.ps1
   • remote.ps1 provide named parameters:-Address、-Port、-Username、-Password、-Command、-Commands、-Save、-Show、-Parallel

6. Diagnostic tasks follow references/remote-guidelines.md: complete collection in the first round, prioritize parallelism, do not filter in advance, and do not perform destructive actions.

7. After a successful connection, update servers.json; when the connection fails, output in the format "conclusion / evidence / inference / next step", and allow at most one minimal retry based on the standard main chain.

8. When the remote end returns Permission denied , the only conclusion that can be drawn is "password authentication was rejected"; it cannot be directly interpreted as special characters in the password or a compatibility issue.

9. windows-msys use SSH_ASKPASS mechanism to automatically provide the password, remaining purely non-interactive; if the credentials are incorrect, it should fail directly.

Continue loading as needed

Read the corresponding document when the following scenarios occur:

• Need to install, repair, or verify the environment:references/setup.md
• Need to confirm the structure of bootstrap-state.json or servers.json (such as inconsistent debugging state):references/state.md
• Need to perform diagnostic collection, parallel commands, or high-risk judgment boundaries:references/remote-guidelines.md

Output requirements

• First state whether locally saved records are being used, or information newly entered in this round
• When the connection fails, clearly indicate whether the issue to be confirmed is the address, port, username, password, or environment
• Diagnostic answers are output in the format "conclusion / evidence / inference / next step"
• Do not try different password-passing parameters one by one after a failure (only applicable to sshpass on Linux/macOS)
• Do not execute high-risk commands by default; when write operations, restarts, deletions, or stopping services are involved, user confirmation must be obtained first
• Local state files are uniformly written as UTF-8 without BOM; when reading, historical BOM files are supported, and the main chain must not be interrupted due to an encoding header