ssh

SSH Skill

Positioning

This is a lightweight SSH operations gateway. It does not maintain an independent server database and by default only reads and writes standard OpenSSH configuration:

~/.ssh/config

Core principles:

• Use Host aliases to identify servers, without directly memorizing IPs/passwords.
• Prioritize key authentication and native OpenSSH commands.
• Through this skill's scripts/ scripts, execute SSH, SCP, configuration checks, and tunnel operations.
• For environment detection, prioritize fixed read-only probes; do not use arbitrary command concatenation to temporarily collect scripts.
• Before writing to ~/.ssh/config , automatic backup is required.
• Storing passwords on disk is discouraged; if a password must be used, prioritize letting OpenSSH prompt interactively or having the user configure secure credentials themselves.

When to trigger

Use this skill when the user mentions the following tasks:

• SSH, remote servers, server IP/hostname,user@host
• login, execute remote commands, check server status
• upload, download, deploy, migrate files
• jump host,ProxyJump, intranet access
• tunnels, port forwarding, database connections
• Configure ~/.ssh/config, add/find server aliases

Do not use for local localhost, the current directory, local file operations, or general explanations of network concepts.

Script entry point

Prefer calling scripts from the current skill directory. The script directory is:

scripts/

Command examples are all based on the current skill directory.

Common commands

ssh_exec.py、ssh_transfer.py、ssh_tunnel.py all support:

--accept-new-host-key
--known-hosts-file <临时known_hosts路径>

When connecting for the first time to a new development board that has been confirmed trustworthy, you may explicitly append --accept-new-host-key. During testing, if you do not want to write to the global known_hosts, you may append --known-hosts-file <临时known_hosts路径>。

List servers

python scripts/ssh_config.py list

Find servers

python scripts/ssh_config.py find <关键词>
python scripts/ssh_config.py find <环境关键词> <能力关键词>

Multiple keywords use AND matching. First narrow the scope by environment group, then determine the target by device alias or tag. search is find 's equivalent command.

Determine the unique server

python scripts/ssh_config.py resolve <关键词...>

Continue only when the result is unique. Exit code 2 indicates multiple candidates; you must confirm with the user and must not automatically select the first item. Exact OpenSSH Host aliases take priority.

Verify alias resolution

python scripts/ssh_config.py show <别名>

Add server

Before writing, the script automatically backs up ~/.ssh/config：

python scripts/ssh_config.py add <别名> --host <IP或域名> --user <用户> --port 22 --key ~/.ssh/id_ed25519

Optional:

--description "说明"
--aliases "常用名称1,常用名称2"
--groups "环境1,环境2"
--tags tag1,tag2
--location "位置"
--proxy-jump <跳板机别名>

Execute remote command

python scripts/ssh_exec.py <别名> "命令" --timeout 30

The script outputs JSON, including success、exit_code、stdout、stderr。

Probe the remote environment

python scripts/ssh_probe.py <别名>

The probe script only executes built-in read-only commands and outputs structured JSON. It enables non-interactive authentication by default, prohibits port and Agent forwarding, and requires the host fingerprint to already be trusted. When you need to view the command first, use --dry-run; only use --accept-new-host-keywhen you have confirmed the new device is trustworthy. The probe entry point explicitly disables ProxyCommandin the SSH configuration; do not use it to connect to targets that must rely on proxy commands. OpenSSH will still parse the user configuration; if Match exec exists in the configuration, local commands may be executed, so use the probe entry point only with trusted SSH configurations.

Upload file

python scripts/ssh_transfer.py upload <别名> "<本地路径>" "<远程路径>"

Download file

python scripts/ssh_transfer.py download <别名> "<远程路径>" "<本地路径>"

Set up local port forwarding

python scripts/ssh_tunnel.py <别名> --local-port <本地端口> --remote-host 127.0.0.1 --remote-port <远程端口>

The tunnel command runs in the foreground. If it needs to stay running in the background long-term, first explain the impact and how to stop it to the user.

Configuration format

Recommended configuration:

# description: 开发板
# aliases: 测试板,主控板
# groups: 实验室测试环境
# tags: embedded,linux
# location: lab
Host 1380-P904
    HostName 192.168.137.76
    User root
    Port 22
    IdentityFile ~/.ssh/id_ed25519

Jump host:

Host bastion
    HostName bastion.example.com
    User root
    IdentityFile ~/.ssh/id_ed25519

Host internal-dev
    HostName 10.0.1.20
    User root
    IdentityFile ~/.ssh/id_ed25519
    ProxyJump bastion

Allow preserving comment metadata:

• description
• aliases
• groups
• tags
• location

Do not write real passwords, tokens, private key contents, or other sensitive information into the configuration.

Operating rules

• Query-type tasks can be executed directly.
• Before adding or modifying ~/.ssh/config , the script must create a backup.
• For risky operations such as deleting configurations, overwriting remote files, deployment, batch execution, and port forwarding, confirm with the user first.
• Do not run bare ssh/scpdirectly; prefer using this skill's scripts; only when the script is unavailable or the user explicitly requests it, explain the reason and use the fallback command.
• Do not modify Git, system services, firewalls, or remote production environment configurations unless the user explicitly requests it.
• When executing remote commands, prefer read-only checks; confirm first when restart, deletion, overwriting, installation, or upgrade is involved.
• When outputting to the user, explain the target alias, actual HostName, executed command, key results, and failure reasons.

Troubleshooting

Check first:

1. python scripts/ssh_config.py show <别名>
2. ssh -G <别名> Whether HostName/User/Port can be resolved
3. Whether the key file exists and whether its permissions are appropriate
4. ProxyJump Whether the alias is also in ~/.ssh/config
5. Whether the network is reachable and whether the port is open
6. Whether the first connection requires explicitly appending --accept-new-host-key

If the script fails, preserve the real stderr; do not swallow the error.