SSH Skill

English

SSH Skill for AI assistants (Claude, Kilo Code, etc.) to manage remote servers with session persistence, async execution, and JSON file storage.

Features

Session Management - Persistent SSH connections with auto-reconnect
Async Execution - Non-blocking command execution with task tracking
JSON Storage - Simple file-based storage, no native dependencies required
Message History - Full command/output history with read/unread status
Reconnect Support - Reconnect disconnected sessions without re-entering credentials
Auto Archive - Automatic session archiving with file rotation (100KB per file)
Sudo Support - Interactive sudo with password caching for reconnection

Installation

git clone https://github.com/ErixWong/erix-ssh-skill.git
cd erix-ssh-skill
npm install

Quick Start

# Start the background session manager
node scripts/ssh_client.js start-manager

# Connect to a server
node scripts/ssh_client.js connect --host 192.168.1.100 --username admin

# Execute a command
node scripts/ssh_client.js exec --session sess_xxx --command "df -h"

# Get command output
node scripts/ssh_client.js output --task task_xxx

Commands

Command	Description
`start-manager`	Start background session manager
`connect`	Connect to server
`disconnect`	Disconnect from server
`reconnect`	Reconnect a disconnected session
`exec`	Execute command (async)
`sudo`	Execute sudo command (password cached)
`history`	Get command history
`output`	Get task output
`list`	List all sessions

Connection Config File

You can use a config file to simplify server connections. The connect command supports --config option to read connection settings from a file.

JSON Format

{
  "host": "example.com",
  "port": 22,
  "username": "admin",
  "password": "your_password",
  "privateKey": "~/.ssh/id_rsa",
  "passphrase": "key_passphrase"
}

Usage

# Connect using config file
node scripts/ssh_client.js connect --config ./hosts/server.json

Config File Fields

Field	Required	Description
`host`	Yes	Server hostname or IP address
`port`	No	Server port (default: 22)
`username`	Yes	Username for authentication
`password`	No*	Password for authentication
`privateKey`	No*	Path to private key file (supports `~` for home directory)
`passphrase`	No	Passphrase for encrypted private key
`defaultPty`	No	Default PTY config for exec commands (see below)

*Either password or privateKey is required for authentication.

defaultPty Configuration

The defaultPty field allows you to set default PTY options for all exec commands in this session:

{
  "host": "example.com",
  "username": "admin",
  "password": "secret",
  "defaultPty": {
    "enabled": true,
    "cols": 120,
    "rows": 24,
    "term": "xterm-256color"
  }
}

Field	Type	Default	Description
`enabled`	boolean	`false`	Whether to allocate PTY by default
`cols`	number	`120`	Terminal width in columns
`rows`	number	`24`	Terminal height in rows
`term`	string	`xterm-256color`	Terminal type

Priority: CLI params > Config file defaults > Hardcoded defaults

# If config has defaultPty.enabled = true, PTY is allocated by default
node ssh_client.js exec --session sess_xxx --command "screen -ls"

# CLI --pty overrides config default
node ssh_client.js exec --session sess_xxx --command "ls"  # Uses config default
node ssh_client.js exec --session sess_xxx --command "ls" --pty=false  # Override to disable

PTY (Pseudo-Terminal) Support

PTY is a command-level configuration, not a connection-level configuration. This is because different commands have different PTY requirements:

Command Type	PTY Required	Example
Regular commands	No	`ls`, `cat`, `grep`
Interactive programs	Yes	`screen`, `tmux`, `vim`
System monitors	Yes	`top`, `htop`
Sudo commands	Auto	Password hiding requires PTY

Usage

# Regular command - no PTY needed
node scripts/ssh_client.js exec --session sess_xxx --command "ls -la"

# Interactive program - requires PTY
node scripts/ssh_client.js exec --session sess_xxx --command "screen -ls" --pty

# Custom terminal size
node scripts/ssh_client.js exec --session sess_xxx --command "htop" --pty --cols 200 --rows 50

PTY Options

Option	Description	Default
`--pty`	Allocate a pseudo-terminal	`false`
`--cols N`	Terminal width in columns	`120`
`--rows N`	Terminal height in rows	`24`
`--term TERM`	Terminal type	`xterm-256color`

Why PTY is Command-Level?

Different commands need different settings: ls doesn't need PTY, but screen does
Same connection, different commands: You may run both regular and interactive commands in the same session
Flexibility: You can specify different terminal sizes for different commands

Best Practices

Security Guidelines

Never read connection config files - Use --config parameter directly

# ✅ Correct - pass config file path
node scripts/ssh_client.js connect --config ./hosts/server.json

# ❌ Wrong - reading config file content
cat ./hosts/server.json  # DON'T DO THIS

Never store passwords to disk - Passwords are cached in memory only
- The SSH client automatically caches passwords for sudo commands
- No need to create password files for sudo operations
Save Session ID immediately - Session ID is your access credential
- Lost Session ID = Lost access (no session list for security)
- Only show first 8 characters for identification: sess_abc1...

LLM Usage Guidelines

When using this skill with AI assistants (Claude, Kilo Code, etc.):

Read SKILL.md first - Before any SSH operation, the AI must read the skill documentation
Trust existing features - Don't reinvent the wheel
- Sudo password caching is already implemented
- Session management is already handled
System differences - Know your target OS

System Sudo Group

RHEL/CentOS/AlmaLinux wheel

Debian/Ubuntu sudo

Typical Workflow

# 1. Start session manager
node scripts/ssh_client.js start-manager

# 2. Connect using config file (recommended)
node scripts/ssh_client.js connect --config ./hosts/server.json
# Save the returned session_id!

# 3. Execute commands
node scripts/ssh_client.js exec --session sess_xxx --command "df -h"

# 4. For sudo commands - just use sudo, password is cached
node scripts/ssh_client.js sudo --session sess_xxx --command "apt update"

# 5. Check output
node scripts/ssh_client.js output --task task_xxx

# 6. Disconnect when done
node scripts/ssh_client.js disconnect --session sess_xxx

Common Mistakes to Avoid

Mistake	Correct Approach
Reading config file content	Use `--config` parameter directly
Creating password files for sudo	Just use `sudo` command, password is cached
Losing session_id	Save it immediately after connection
Using wrong sudo group	Check OS: `wheel` for RHEL, `sudo` for Debian

Requirements

Node.js 18+

Skill Files

This project provides two skill definition files for different AI assistants:

File	Description
`SKILL.md`	Default skill file for Claude and other AI assistants
`skill-kilo-code.md`	Skill file optimized for Kilo Code

Kilo Code Deployment

To use this skill with Kilo Code:

Copy the scripts/ folder and skill-kilo-code.md to your Kilo Code skills directory:

.kilocode/skills/erix-ssh/
├── scripts/
│   ├── ssh_client.js
│   ├── session_manager.js
│   └── db-json.js
└── SKILL.md    # Rename from skill-kilo-code.md

Rename skill-kilo-code.md to SKILL.md
Run npm install in the skill directory to install dependencies (only ssh2 required, no native compilation needed)

For more details, see Kilo Code Skills Documentation.

中文

SSH Skill 是为 AI 助手（Claude、Kilo Code 等）设计的远程服务器管理技能，支持会话持久化、异步执行和 JSON 文件存储。

特性

会话管理 - 持久化 SSH 连接，支持自动重连
异步执行 - 非阻塞命令执行，任务追踪
JSON 存储 - 简单的文件存储，无需原生依赖
消息历史 - 完整的命令/输出历史，已读未读状态
重连支持 - 断开后重连，无需重新输入凭据
自动归档 - 自动会话归档，文件轮转（每文件 100KB）
Sudo 支持 - 交互式 sudo，密码缓存支持重连

安装

git clone https://github.com/ErixWong/erix-ssh-skill.git
cd erix-ssh-skill
npm install

快速开始

# 启动后台会话管理器
node scripts/ssh_client.js start-manager

# 连接服务器
node scripts/ssh_client.js connect --host 192.168.1.100 --username admin

# 执行命令
node scripts/ssh_client.js exec --session sess_xxx --command "df -h"

# 获取命令输出
node scripts/ssh_client.js output --task task_xxx

命令列表

命令	说明
`start-manager`	启动后台会话管理器
`connect`	连接服务器
`disconnect`	断开连接
`reconnect`	重连已断开的会话
`exec`	执行命令（异步）
`sudo`	执行 sudo 命令（密码已缓存）
`history`	获取命令历史
`output`	获取任务输出
`list`	列出所有会话

连接配置文件

可以使用配置文件简化服务器连接。connect 命令支持 --config 选项从文件读取连接配置。

JSON 格式

{
  "host": "example.com",
  "port": 22,
  "username": "admin",
  "password": "your_password",
  "privateKey": "~/.ssh/id_rsa",
  "passphrase": "key_passphrase"
}

使用方法

# 使用配置文件连接
node scripts/ssh_client.js connect --config ./hosts/server.json

配置文件字段

字段	必填	说明
`host`	是	服务器主机名或 IP 地址
`port`	否	服务器端口（默认：22）
`username`	是	认证用户名
`password`	否*	认证密码
`privateKey`	否*	私钥文件路径（支持 `~` 表示主目录）
`passphrase`	否	加密私钥的密码
`defaultPty`	否	默认 PTY 配置（详见下文）

*password 或 privateKey 至少需要提供一个用于认证。

defaultPty 配置

defaultPty 字段允许为该会话的所有 exec 命令设置默认 PTY 选项：

{
  "host": "example.com",
  "username": "admin",
  "password": "secret",
  "defaultPty": {
    "enabled": true,
    "cols": 120,
    "rows": 24,
    "term": "xterm-256color"
  }
}

字段	类型	默认值	说明
`enabled`	boolean	`false`	是否默认分配 PTY
`cols`	number	`120`	终端宽度（列数）
`rows`	number	`24`	终端高度（行数）
`term`	string	`xterm-256color`	终端类型

优先级：命令行参数 > 配置文件默认值 > 硬编码默认值

# 如果配置文件设置了 defaultPty.enabled = true，则默认分配 PTY
node ssh_client.js exec --session sess_xxx --command "screen -ls"

# 命令行 --pty 可以覆盖配置文件默认值
node ssh_client.js exec --session sess_xxx --command "ls"  # 使用配置文件默认值
node ssh_client.js exec --session sess_xxx --command "ls" --pty=false  # 覆盖为禁用

PTY（伪终端）支持

PTY 是命令级别的配置，不是连接级别的配置。这是因为不同的命令有不同的 PTY 需求：

命令类型	需要 PTY	示例
普通命令	否	`ls`, `cat`, `grep`
交互式程序	是	`screen`, `tmux`, `vim`
系统监控	是	`top`, `htop`
Sudo 命令	自动	密码隐藏需要 PTY

使用方法

# 普通命令 - 不需要 PTY
node scripts/ssh_client.js exec --session sess_xxx --command "ls -la"

# 交互式程序 - 需要 PTY
node scripts/ssh_client.js exec --session sess_xxx --command "screen -ls" --pty

# 自定义终端大小
node scripts/ssh_client.js exec --session sess_xxx --command "htop" --pty --cols 200 --rows 50

PTY 选项

选项	说明	默认值
`--pty`	分配伪终端	`false`
`--cols N`	终端宽度（列数）	`120`
`--rows N`	终端高度（行数）	`24`
`--term TERM`	终端类型	`xterm-256color`

为什么 PTY 是命令级别配置？

不同命令需要不同设置：ls 不需要 PTY，但 screen 需要
同一连接执行不同命令：同一会话中可能执行普通命令和交互式命令
灵活性：可以为不同命令指定不同的终端大小

最佳实践

安全准则

禁止读取连接配置文件 - 直接使用 --config 参数

# ✅ 正确 - 传递配置文件路径
node scripts/ssh_client.js connect --config ./hosts/server.json

# ❌ 错误 - 读取配置文件内容
cat ./hosts/server.json  # 不要这样做

禁止将密码存储到磁盘 - 密码仅在内存中缓存
- SSH 客户端自动缓存密码用于 sudo 命令
- 无需为 sudo 操作创建密码文件
立即保存 Session ID - Session ID 是访问凭证
- 丢失 Session ID = 丢失访问权限（出于安全考虑不提供会话列表）
- 仅显示前 8 个字符用于识别：sess_abc1...

LLM 使用指南

与 AI 助手（Claude、Kilo Code 等）配合使用时：

先阅读 SKILL.md - 在任何 SSH 操作之前，AI 必须阅读技能文档
信任现有功能 - 不要重复造轮子
- Sudo 密码缓存已实现
- 会话管理已处理
系统差异 - 了解目标操作系统

系统 Sudo 组

RHEL/CentOS/AlmaLinux wheel

Debian/Ubuntu sudo

典型工作流程

# 1. 启动会话管理器
node scripts/ssh_client.js start-manager

# 2. 使用配置文件连接（推荐）
node scripts/ssh_client.js connect --config ./hosts/server.json
# 保存返回的 session_id！

# 3. 执行命令
node scripts/ssh_client.js exec --session sess_xxx --command "df -h"

# 4. 执行 sudo 命令 - 直接使用 sudo，密码已缓存
node scripts/ssh_client.js sudo --session sess_xxx --command "apt update"

# 5. 检查输出
node scripts/ssh_client.js output --task task_xxx

# 6. 完成后断开连接
node scripts/ssh_client.js disconnect --session sess_xxx

常见错误

错误	正确做法
读取配置文件内容	直接使用 `--config` 参数
为 sudo 创建密码文件	直接使用 `sudo` 命令，密码已缓存
丢失 session_id	连接后立即保存
使用错误的 sudo 组	检查操作系统：RHEL 用 `wheel`，Debian 用 `sudo`

系统要求

Node.js 18+

技能文件

本项目提供两个技能定义文件，适用于不同的 AI 助手：

文件	说明
`SKILL.md`	默认技能文件，适用于 Claude 等主流 AI 助手
`skill-kilo-code.md`	专为 Kilo Code 优化的技能文件

Kilo Code 部署方式

在 Kilo Code 中使用此技能：

将 scripts/ 文件夹和 skill-kilo-code.md 复制到 Kilo Code 技能目录：

.kilocode/skills/erix-ssh/
├── scripts/
│   ├── ssh_client.js
│   ├── session_manager.js
│   └── db-json.js
└── SKILL.md    # 从 skill-kilo-code.md 重命名

将 skill-kilo-code.md 重命名为 SKILL.md
在技能目录中运行 npm install 安装依赖（仅需 ssh2，无需原生编译）

更多详情请参考 Kilo Code Skills 文档。

License

MIT

Name		Name	Last commit message	Last commit date
docs		docs
references		references
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
docker-compose.dual.yml		docker-compose.dual.yml
package-lock.json		package-lock.json
package.json		package.json
skill-kilo-code.md		skill-kilo-code.md

Latest commit

History

Folders and files

Repository files navigation

SSH Skill

English

Features

Installation

Quick Start

Commands

Connection Config File

JSON Format

Usage

Config File Fields

defaultPty Configuration

PTY (Pseudo-Terminal) Support

Usage

PTY Options

Why PTY is Command-Level?

Best Practices

Security Guidelines

LLM Usage Guidelines

Typical Workflow

Common Mistakes to Avoid

Requirements

Skill Files

Kilo Code Deployment

中文

特性

安装

快速开始

命令列表

连接配置文件

JSON 格式

使用方法

配置文件字段

defaultPty 配置

PTY（伪终端）支持

使用方法

PTY 选项

为什么 PTY 是命令级别配置？

最佳实践

安全准则

LLM 使用指南

典型工作流程

常见错误

系统要求

技能文件

Kilo Code 部署方式

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages