ssh-skill

SSH スキル v4

目的

Windows、macOS、Linux 上の Codex および Claude Code で、SSH を介した作業を行う際にこの契約を使用します。決定論的な Python CLI が、トランスポート、再試行、出力制限、ホストキーのポリシー、互換性の動作を管理します。

中国語での意図の例：连接服务器、远程执行、上传文件、下载日志、通过跳板机、 建立隧道。ユーザーとの会話は、引き続きユーザーの言語で行ってください。

対象範囲

次の場合に使用します。

• リモートホストでのコマンド実行や調査。
• アップロード、ダウンロード、SFTP、SCP 相当の操作、サーバー間転送。
• SSH エイリアス、鍵、エージェント、踏み台サーバー、ProxyJump、トンネル、ポートフォワーディング。
• リモートデプロイ、トンネル経由のリモートデータベースアクセス、クラスターでの作業。

次の場合は使用しないでください。

• ローカルコマンド、localhost、現在のマシン上のサービス、ローカル Docker。
• SSH を経由しないブラウザーや HTTP によるダウンロード。
• Git リモート操作。代わりに該当する Git ワークフローを使用してください。
• SSH トンネルを必要としない直接のデータベース接続。

厳守事項

1. 読み込まれた SKILL.md を含むルートを特定し、現在のタスクでは <SSH_SKILL_ROOT> として扱います。
2. <SSH_SKILL_ROOT>/scripts/ssh_skill.py を呼び出します。生の ssh、scp、sftp、rsync コマンドを組み立てないでください。
3. 引数は個別のプロセス引数として渡します。リモートコマンドのテキストを囲むローカルシェルの ラッパーは追加しないでください。
4. 次のアクションを決定する前に、標準出力に出力された 1 つの JSON ドキュメントを解析します。
5. outcome_unknown は停止条件として扱います。リクエスト ID を報告し、コマンドを自動的に 再実行しないでください。
6. 新たな根拠とユーザーの意図がない限り、認証失敗、破壊的なコマンド、または 一部のみ完了した複数ホスト操作を再試行しないでください。
7. パスワード、秘密鍵の内容、トークン、askpass のデータは決して公開しないでください。
8. 複数ホストへの操作や取り消し不能な操作は、適用前にプレビューしてください。

スキルのルートを一度だけ特定する

• このスキルを有効にした SKILL.md のディレクトリを優先します。
• ランタイムから読み込まれたスキルのパスが明示されている場合は、そのパスを直接使用します。
• .agents、.codex、.claude、またはユーザーホームのパスを想定しないでください。
• ルートが曖昧な場合、依存関係が不足している場合、または複数のインストール済みコピーで差異が生じている可能性がある場合は、 doctor --json を実行します。
• 操作のたびに doctor を実行しないでください。同じタスク内では、環境に変化がない限り、特定済みのルートを再利用します。
• doctor で複数のコピーが報告された場合は、現在読み込まれているコピーを引き続き使用し、バージョンまたはコンテンツの差異を開示します。自動的にコピーまたは上書きしないでください。

呼び出し構文が必要な場合は、プラットフォームガイドを 1 つだけ正確に読んでください。

• Windows: references/platforms-windows.md
• macOS: references/platforms-macos.md
• Linux: references/platforms-linux.md

標準ワークフロー

1. リクエストを exec、transfer、cluster、config、tunnel、doctor のいずれかに分類します。
2. <SSH_SKILL_ROOT> を一度だけ特定します。
3. SSH エイリアスを特定します。不明な場合は config list-servers または config find を使用し、IP や似た名前から推測しないでください。
4. 読み取り専用の調査と変更操作を分けます。操作に重大な影響がある場合に限り、不足している対象や範囲を確認します。
5. 複数ホスト、本番環境、削除、上書きに関わる作業は、事前にプレビューします。
6. 統合 CLI を一度だけ呼び出し、必要最小限の完全な操作を実行します。
7. success、data、error、meta を解析し、実際の結果を報告します。

結果から必要だと判断されない限り、接続テスト、ステータス確認の繰り返し、 デーモンの再起動は追加しないでください。

呼び出し契約

プラットフォームに適した Python 実行ファイルとパス構文を使用してください。

<PYTHON> "<SSH_SKILL_ROOT>/scripts/ssh_skill.py" <operation> <arguments>

• リモートパスは /var/log/app.log のように POSIX 形式にしてください。
• リモートコマンド全体を 1 つの引数として指定してください。
• 密接に関連する読み取り専用の情報を収集する場合は、1 つのリモートコマンドを優先してください。
• 依存関係のある変更や、別々にリスクを伴う変更は、個別の操作に分けてください。
• 進捗イベントがユーザーにとって有用な場合に限り、--progress を使用してください。
• クリーンな非対話型の標準エラー出力が必要な場合は、--no-progress を使用してください。

完全な構文については、references/commands.md を参照してください。

操作

操作	用途
exec	1 つの SSH エイリアスで 1 つのコマンドを実行します。
upload	ローカルのファイルまたはディレクトリをリモートの POSIX パスにコピーします。
download	リモートのファイルまたはディレクトリをローカルパスにコピーします。
transfer	2 つの SSH エイリアス間でデータを移動します。
cluster	解決されたホストの対象に対して、1 つのコマンドをプレビューまたは適用します。
config	SSH エイリアスの一覧表示、検索、作成、更新、削除、またはエクスポートを行います。
tunnel	ローカル SSH トンネルの開始、一覧表示、検査、または停止を行います。
daemon	オプションの接続デーモンを検査または管理します。
doctor	ローカルのランタイム、コピー、OpenSSH、エージェント、設定を診断します。

実行と転送

• exec は安全な場合にのみデーモンを再利用します。--no-daemon は明示的な診断用の回避策であり、通常の最初の手順として使用するものではありません。
• OpenSSH、Paramiko、またはクラスター実行を介したリクエストの送信後にタイムアウトした場合、リモート側でコマンドが実行されている可能性があります。CLI は retryable=false の outcome_unknown を返します。処理を止め、状態をどのように確認するかユーザーに尋ねてください。
• アップロード／ダウンロードでは、ローカルのネイティブパスとリモートの POSIX パスを区別してください。ディレクトリの場合に限り、--recursive を使用してください。
• 中断したことが確認済みの転送を再開する場合は、--resume を使用してください。
• サーバー間のダイレクトモードでは、送信元ホストに SSH エージェントが公開される可能性があります。--allow-agent-forwarding を明示しない限り、エージェント転送は無効のままです。

クラスターと設定のゲート

• --apply を指定しない cluster は対象のプレビューであり、SSH 接続は開きません。
• プレビューの targets、target_count、production_targets を確認してください。
• 要求された対象の集合が確認されてから、--apply を追加してください。
• いずれかの対象が本番環境に分類されている場合は、--confirm-production を追加してください。
• --apply を指定しない設定の削除はプレビューです。削除を適用すると、タイムスタンプ付きのバックアップを作成してから、アトミックに置き換えます。
• SSH 設定のメタデータに、新たな平文パスワードを含めないでください。

トンネルとデーモン

• トンネルの開始後、割り当てられたローカルポートとトンネル ID を返してください。
• 安全なデフォルト設定に従ってのみ、ローカルフォワーディングをバインドしてください。
• 識別子が曖昧な場合は、トンネルを停止する前にステータスまたは一覧を確認してください。
• 2 つ目のコマンドが続いたからといって、デーモンを再起動しないでください。デーモンは、互換性のある呼び出し間で再利用できるように設計されています。

結果の契約

CLI は、バージョン付きの JSON ドキュメントを標準出力に正確に 1 つ書き込みます。

• schema_version：結果スキーマ。現在は 1.0 です。
• success：要求された操作が正常に完了したかどうか。
• operation：安定した操作識別子。
• data：操作固有のデータ。サイズに上限があります。
• error：失敗時の安定したコード、メッセージ、再試行可能性、結果。
• meta：リクエスト ID、プラットフォーム、トランスポート、経過時間、警告。

標準出力の最上位の結果サイズは 256 KiB に制限されています。再帰的な転送の詳細では、先頭と末尾のサンプルをそれぞれ最大 100 件保持しますが、合計数のフィールドには実際の規模が保持されます。明示的に有効にした場合、進捗情報はリアルタイムで、サイズに上限があり、ASCII セーフな JSONL として標準エラー出力に書き込まれます。標準出力と混在させないでください。出力が切り詰められた場合は、その旨を明示し、出力を増やすことだけを目的に再実行せず、保持された診断の末尾を使用してください。

安全性のデフォルト設定

• ホストキーはデフォルトでaccept-newに設定され、変更された既知のキーは拒否されます。
• 通常の使用では、ホストキーの検証を無効にしたり、known_hostsを破棄したりしないでください。
• 既存のレガシーパスワードは警告付きで読み取れますが、必ずマスキングしてください。
• キーとプラットフォームのSSHエージェントを優先し、秘密鍵の値を求めないでください。
• 本番環境および複数ホストを対象とする操作では、確認フラグによる明示的な確認が必要です。
• 認証情報の変更、本番環境での作業、エージェント転送、設定の削除、または結果が不確かな場合は、references/safety.mdを読んでください。

エラーへの対応

• invalid_alias：エイリアスを一度だけ一覧表示または検索し、名前を総当たりで試さないでください。
• config_not_found：doctorを実行してから、想定されるローカル設定ファイルのパスを報告してください。
• 認証失敗：使用した方式と解決方法を報告し、繰り返し試さないでください。
• outcome_unknown：操作を中止し、リクエストIDを保持して、別途状態を確認してください。
• クラスターの一部で障害が発生した場合：ホストごとの結果を報告し、成功した操作を再実行しないでください。
• 依存関係の不足：別のシェルではなく、該当するプラットフォームガイドを使用してください。

互換性

• CodexとClaude Codeは、このファイルと同じPython CLIを共有します。
• Windows、macOS、Linuxではコア動作を共有します。異なるのは、ローカルでの呼び出し方法と依存関係の解決方法のみです。
• v4への移行期間中、レガシーのスクリプトファイル名は互換性のためのエントリーポイントとして維持されます。
• --legacy-jsonは、旧バージョンの利用側が特定されている場合にのみ使用します。新しいAI呼び出しではv1エンベロープを使用し、レガシー出力は要求しません。

最終確認

• 正しい読み込み先のルートとプラットフォーム構文を使用したこと。
• 正しいエイリアス、リモートパス、対象範囲を使用したこと。
• 必須のプレビューと本番環境での確認を完了したこと。
• stdoutのJSONを1つ解析し、警告とリクエストIDを保持したこと。
• 秘密情報を漏らしておらず、結果が不確かな操作を再実行していないこと。