SSH Skill — Development skill for Claude Code

SSH Skill v4.0.0

**中文** | [English](README_EN.md)

`ssh-skill` 是面向 Codex 和 Claude Code 的 SSH 工作流 Skill。它以统一的 Python CLI 封装远程命令、文件传输、服务器间传输、批量操作、配置管理、 隧道和连接守护进程，并为 Windows、macOS、Linux 提供一致的结果协议。

**当前稳定主版本：v4.0.0。** 新的 AI 调用应使用统一入口和 v4 结果协议； 旧脚本仅作为迁移兼容入口保留。

v4 重点（更新日期：2026年8月24日）

• 所有新调用统一进入 scripts/ssh_skill.py。
• stdout 只输出一个 schema_version=1.0 的 JSON 文档。
• 远程命令按单独参数传递，不经过本地 PowerShell/Bash/Zsh 二次解析。
• OpenSSH、Paramiko 和集群执行在请求发出后超时时统一返回 outcome_unknown、retryable=false，防止 AI 自动重放副作用。
• 统一入口可在 stderr 实时转发有界 JSONL 进度；事件使用 ASCII-safe JSON， 可被 Windows 控制台和三个桌面平台稳定解析。
• 顶层 JSON 结果限制为 256 KiB；递归传输明细最多保留 100 条首尾样本， 同时保留真实总数，避免大目录占满 AI 上下文。
• 主机密钥默认采用 accept-new，已知密钥冲突会被拒绝。
• 集群默认只预览；执行需要 --apply，生产目标还需要 --confirm-production。
• 新配置拒绝明文密码；旧密码仅兼容读取并始终脱敏。
• agent forwarding 默认关闭。
• 保留旧脚本文件名作为迁移入口，但默认采用 v4 安全语义。

兼容范围

AI 工具	Windows	macOS	Linux
Codex	支持	支持	支持
Claude Code	支持	支持	支持

发布门槛覆盖 Python 3.10、3.11、3.12、3.13。运行时需要 Python、OpenSSH 客户端和 Paramiko。Python 3.8/3.9 仅尽力兼容，不属于正式测试矩阵。 v4.0.0 发布基线为 115 项离线测试，并由 GitHub Actions 在 Windows、macOS、 Ubuntu 及 Python 3.10-3.13 上验证。

Skill 路径

以当前 AI 实际加载的 [SKILL.md](SKILL.md) 所在目录为 ``。不要把任意一个目录写死为唯一安装位置。

常见候选位置包括：

• Codex 用户级：$CODEX_HOME/skills/ssh-skill/ 或 .agents/skills/ssh-skill/
• Codex 项目级：.codex/skills/ssh-skill/ 或 .agents/skills/ssh-skill/
• Claude Code 用户级或项目级：.claude/skills/ssh-skill/

`doctor` 会列出当前副本和候选副本的版本、内容哈希与漂移状态，但不会自动 复制、覆盖或选择另一个副本。同一个任务中解析一次路径即可，不要每次操作前 重复运行 doctor。

平台调用

Windows PowerShell：

python "\scripts\ssh_skill.py" doctor --json
python "\scripts\ssh_skill.py" exec example-host "hostname"

macOS / Linux：

python3 "/scripts/ssh_skill.py" doctor --json
python3 "/scripts/ssh_skill.py" exec example-host "hostname"

远程路径在三个系统上都保持 POSIX 格式。不要增加本地 Shell 包装层。

常用命令

以下示例假设当前目录就是源码根目录：

python scripts