badseal/ssh-skill

What it solves

ssh-skill provides a unified, secure, and AI-friendly interface for managing remote servers via SSH. It eliminates the inconsistencies between Windows, macOS, and Linux platforms, providing a single Python CLI that AI agents (like Codex and Claude Code) can use to execute commands, transfer files, and manage tunnels without dealing with raw shell command construction or platform-specific quirks.

How it works

The project implements a unified entry point (scripts/ssh_skill.py) that wraps OpenSSH, Paramiko, and cluster execution logic. It enforces a strict JSON-based result protocol (v4) to ensure that AI agents receive structured, predictable data. To prevent AI-driven errors, it includes safety guards like mandatory preview modes for cluster operations and explicit confirmation for production environments. It also manages output limits (256 KiB) to prevent AI context window overflow.

Who it’s for

AI agents and developers using tools like Codex and Claude Code who need to be able to interact with remote infrastructure safely and securey across different operating systems.

Highlights

• Unified Protocol: Standardizes stdout as a single JSON document for consistent AI parsing.
• Cross-Platform Consistency: Ensures POSIX-style remote paths and consistent results across Windows, macOS, and Linux.
• Cross-Server Transfer: Supports direct server-to-server file transfers.
• AI Safety Guards: Prevents automatic retries on unknown outcomes to avoid side-effect duplication and requires --apply and --confirm-production for production cluster changes.
• Context Window Optimization: Truncates large directory listings to 100 samples to avoid filling the AI's context.
• Security First: Rejects plain-text passwords in new configurations and disables agent forwarding by default.