Agent Skills › ryantsai/KKTerm › ssh-troubleshooter

ssh-troubleshooter

GitHub

用于诊断 KKTerm 中 SSH 连接、会话、tmux 恢复及 SFTP 启动失败等问题。通过只读检查定位原因，区分认证与传输故障，严格遵循安全规范处理主机密钥变更，避免泄露敏感信息。

assistant-skills/ssh-troubleshooter/SKILL.md ryantsai/KKTerm

Trigger Scenarios

SSH 连接或会话失败 tmux 恢复失败 SFTP 启动问题主机密钥警告认证错误 ProxyJump 配置问题

Install

npx skills add ryantsai/KKTerm --skill ssh-troubleshooter -g -y

More Options

Non-standard path

npx skills add https://github.com/ryantsai/KKTerm/tree/main/assistant-skills/ssh-troubleshooter -g -y

Use without installing

npx skills use ryantsai/KKTerm@ssh-troubleshooter

指定 Agent (Claude Code)

npx skills add ryantsai/KKTerm --skill ssh-troubleshooter -a claude-code -g -y

安装 repo 全部 skill

npx skills add ryantsai/KKTerm --all -g -y

预览 repo 内 skill

npx skills add ryantsai/KKTerm --list

SKILL.md

Frontmatter

{
    "name": "ssh-troubleshooter",
    "description": "Diagnose SSH Connection failures, tmux resume problems, host key warnings, authentication errors, ProxyJump issues, and SFTP-over-SSH startup problems in KKTerm."
}

SSH Troubleshooter

Use this skill when a user asks why an SSH Connection, SSH Session, tmux resume, or SFTP launch is failing.

Workflow

Identify whether the user is talking about a stored Connection, a Quick Connect draft, or a live Session.
Ask for the smallest missing fact only when the current context does not include it: host, port, auth method, proxy/jump path, or the visible error.
Prefer read-only checks first: Connection settings, host reachability, DNS, known host status, auth method, and tmux session name/history settings.
Explain likely causes in order of evidence, not in order of convenience.
Suggest commands only when they are reviewable and scoped to the target host or local config file.
For host key changes, treat the warning as security-sensitive. Do not tell the user to delete trust records until they confirm the host identity out of band.
For auth failures, separate password, key file, agent, and keyboard-interactive paths. Do not ask the user to paste secrets into chat.
For tmux issues, distinguish attach/resume failure from SSH transport failure.

KKTerm Boundaries

Stored resources are Connections, not profiles.
Live terminal state is a Session.
SFTP opens from an SSH Connection.
Secrets belong in the OS keychain, not chat or SQLite.
Native SSH uses KKTerm's NativeSsh transport; local Windows shells use ConPTY through the Pty transport.