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
• macOS: references/platforms-macos.md
• Linux: 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 for complete syntax.

Operations

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 interrupted transfer.
• Server-to-server direct mode may expose an SSH agent to the source host.
  Agent forwarding remains off unless --allow-agent-forwarding is explicit.

Cluster And Configuration Gates

• cluster without --apply is a target preview and opens no SSH connection.
• Review targets, target_count, and production_targets from the preview.
• Add --apply only after the requested target set is confirmed.
• Add --confirm-production when any target is classified as production.
• A config delete without --apply is a preview. Applied deletion creates a
  timestamped backup before atomic replacement.
• Do not put new plaintext passwords into SSH configuration metadata.

Tunnels And Daemons

• Return the allocated local port and tunnel ID after starting a tunnel.
• Bind local forwarding only according to the tool's safe default.
• Prefer status or list before stopping a tunnel when the identifier is vague.
• Do not restart a daemon merely because a second command follows the first.
  The daemon is designed for reuse across compatible calls.

Result Contract

The CLI writes exactly one versioned JSON document to stdout:

• schema_version: result schema, currently 1.0.
• success: whether the requested operation completed successfully.
• operation: stable operation identifier.
• data: bounded operation-specific data.
• error: stable code, message, retryability, and outcome on failure.
• meta: request ID, platform, transport, elapsed time, and warnings.

The top-level stdout result is capped at 256 KiB. Recursive transfer details
retain at most 100 head/tail samples while their total-count fields preserve the
actual scale. Progress, when explicitly enabled, is real-time, bounded,
ASCII-safe JSONL on stderr. Do not merge it with stdout. If output is truncated,
disclose truncation and use the retained diagnostic tail instead of rerunning
solely to obtain more output.

Safety Defaults

• Host keys default to accept-new; changed known keys are rejected.
• Do not disable host-key verification or discard known_hosts in routine use.
• Existing legacy passwords may be read with warnings but must stay redacted.
• Prefer keys and the platform SSH agent; never request a private key value.
• Production and multi-host scope require observable confirmation flags.
• Read references/safety.md before credential changes,
  production work, agent forwarding, config deletion, or uncertain outcomes.

Error Decisions

• invalid_alias: list or find aliases once; do not brute-force names.
• config_not_found: run doctor, then report the expected local config path.
• Authentication failure: report the method and remediation; do not loop.
• outcome_unknown: stop, preserve request ID, and verify state separately.
• Partial cluster failure: report per-host outcomes; do not replay successes.
• Missing dependency: use the relevant platform guide, not another shell.

Compatibility

• Codex and Claude Code share this file and the same Python CLI.
• Windows, macOS, and Linux share core behavior; only local invocation and
  dependency remediation differ.
• Legacy script filenames remain compatibility entrypoints during v4 migration.
• --legacy-json is only for an identified old consumer. New AI calls use the
  v1 envelope and never request legacy output.

Final Check

• Correct loaded root and platform syntax used.
• Correct alias, remote path, and target scope used.
• Required preview and production confirmation completed.
• One stdout JSON parsed; warnings and request ID preserved.
• No secret exposed and no uncertain operation replayed.