/ssh-skill

name: ssh-skill
version: 4.0.0
description: "Use when a task requires SSH or SCP/SFTP behavior, a remote server, server alias/IP/hostname/user@host, bastion or jump-host access, remote command execution, upload/download, server transfer, deployment, tunnels, port forwarding, or remote internal services; Chinese triggers include 服务器, 远程, 连接, 登录, 上传, 下载, 部署, 跳板机, 隧道. DO NOT use for local shell commands, localhost/current-machine work, local Docker, browser downloads, Git remotes, or direct non-SSH database access."
allowed-tools: Bash, Read, Write, Glob
keywords: SSH,SCP,SFTP,server,remote,bastion,jump-host,upload,download,transfer,tunnel,deploy,服务器,远程,连接,登录,上传,下载,部署,跳板机,隧道

SSH Skill v4

Purpose

Use this contract for SSH-mediated work in Codex and Claude Code on Windows, macOS, and Linux. The deterministic Python CLI owns transport, retries, output limits, host-key policy, and compatibility behavior.

Chinese intent examples: 连接服务器, 远程执行, 上传文件, 下载日志, 通过跳板机, 建立隧道. Continue the user-facing conversation in the user's language.

Scope

Use for:

• Commands or inspections on a remote host.
• Upload, download, SFTP, SCP-equivalent, or server-to-server transfer.
• SSH aliases, keys, agents, bastions, ProxyJump, tunnels, and port forwarding.
• Remote deployment, remote database access through a tunnel, and cluster work.

DO NOT use for:

• Local commands, localhost, current-machine services, or local Docker.
• Browser or HTTP downloads that do not traverse SSH.
• Git remote operations; use the relevant Git workflow instead.
• Direct database connections that do not require an SSH tunnel.

Hard Rules

1. Resolve the root containing this loaded `SKILL.md`; call it `<SSH_SKILL_ROOT>` for the current task. 2. Invoke `<SSH_SKILL_ROOT>/scripts/ssh_skill.py`; do not construct raw `ssh`, `scp`, `sftp`, or `rsync` commands. 3. Pass arguments as discrete process arguments. Never add a local shell wrapper around remote command text. 4. Parse the one JSON document on stdout before deciding the next action. 5. Treat `outcome_unknown` as a stop condition. Report its request ID and do not repeat the command automatically. 6. Do not retry authentication failures, destructive commands, or partially completed multi-host operations without new evidence and user intent. 7. Never expose passwords, private-key content, tokens, or askpass data. 8. Preview multi-host and irreversible operations before applying them.

Resolve The Skill Root Once

• Prefer the directory of the `SKILL.md` that activated this skill.
• If the runtime provides an explicit loaded-skill path, use it directly.
• Do not assume `.agents`, `.codex`, `.claude`, or any user-home path.
• Run `doctor --json` when the root is ambiguous, a dependency is missing, or

multiple installed copies may have drifted.

• Do not run doctor before every operation. Reuse the resolved root within the

same task unless the environment changes.

• If doctor reports several copies, keep using the currently loaded copy and

disclose version or content drift; never copy or overwrite automatically.

Read exactly one platform guide when invocation syntax is needed:

• Windows: [references/platforms-windows.md](references/platforms-windows.md)
• macOS: [references/platforms-macos.md](references/platforms-macos.md)
• Linux: [references/platforms-linux.md](references/platforms-linux.md)

Standard Workflow

1. Classify the request as exec, transfer, cluster, config, tunnel, or doctor. 2. Resolve `<SSH_SKILL_ROOT>` once. 3. Identify the SSH alias. If it is unknown, use `config list-servers` or `config find`; do not guess from an IP or a similar name. 4. Separate read-only discovery from mutation. Ask for missing target or scope only when it materially changes the operation. 5. Preview multi-host, production, delete, or overwrite work. 6. Invoke the unified CLI once with the smallest complete operation. 7. Parse `success`, `data`, `error`, and `meta`, then report the actual result.

Do not add connection tests, repeated status calls, or daemon restarts unless the result indicates that one of them is necessary.

Invocation Contract

Use the platform-appropriate Python executable and path syntax:

<PYTHON> "<SSH_SKILL_ROOT>/scripts/ssh_skill.py" <operation> <arguments>

• Keep remote paths in POSIX form, such as `/var/log/app.log`.
• Keep the entire remote command as one argument.
• Prefer one remote command that gathers closely related read-only facts.
• Keep dependent or separately risky mutations as separate operations.
• Use `--progress` only when progress events are useful to the user.
• Use `--no-progress` when a clean noninteractive stderr is required.

See [references/commands.md](references/commands.md) for complete syntax.

Operations

| Operation | Use | | --- | --- | | `exec` | Run one command on one SSH alias. | | `upload` | Copy a local file or directory to a remote POSIX path. | | `download` | Copy a remote file or directory to a local path. | | `transfer` | Move data between two SSH aliases. | | `cluster` | Preview or apply one command to resolved host targets. | | `config` | List, find, create, update, delete, or export SSH aliases. | | `tunnel` | Start, list, inspect, or stop local SSH tunnels. | | `daemon` | Inspect or manage the optional connection daemon. | | `doctor` | Diagnose local runtime, copies, OpenSSH, agent, and config. |

Execution And Transfer

• `exec` uses daemon reuse only where safe; `--no-daemon` is an explicit

diagnostic escape hatch, not a routine first step.

• A timeout after request transmission through OpenSSH, Paramiko, or cluster

execution can mean the remote side executed the command. The CLI returns `outcome_unknown` with `retryable=false`; stop and ask the user how to verify state.

• For upload/download, preserve the distinction between local native paths and

remote POSIX paths. Use `--recursive` only for directories.

• Use `--resume` when continuing a known