jumpserver-agent-skill

JumpServer Agent Skill

Overview

Use jumpserver-ssh-mcp as the capability layer and this skill as the operating playbook. The human should only need to provide a gateway name, a JumpServer SSH login command, and a target host; the Agent owns configuration, probe, smoke test, and matcher repair.

Agent Responsibility

The Agent must perform the operational setup work itself. Do not ask the human to hand-write profile internals or matcher JSON unless they explicitly want to.

Human-provided inputs should stay small:

• gateway name
• JumpServer SSH login command
• target host/IP or asset identifier for validation
• optional preferred asset account

Agent-owned outputs:

• MCP source installation or upgrade when requested
• Agent Skill installation when supported by the client
• MCP client configuration
• SSH_ASSIST_PROFILE profile file
• gateway entry
• matcher selection
• custom matcher JSON when built-in matchers fail
• probe and smoke-test evidence

Built-in matchers are packaged inside jumpserver-ssh-mcp and are available after installation. Agent-authored matchers should be written only to configured custom matcher directories, usually ~/jumpserver-ssh-mcp/matchers/.

Required Inputs

Ask for only missing essentials:

• gateway_name, such as pro-jumpserver or test-jumpserver
• JumpServer SSH login command, such as ssh -i ~/.ssh/pro.pem [email protected] -p2222
• one target host or asset identifier for validation

Optional:

• preferred asset account, such as root, __su, or deploy
• environment label, such as prod or test

Workflow

1. If the MCP or this Skill is missing, outdated, or exposes only part of the native Job tools, read references/install-and-upgrade.md and complete installation or upgrade first.
2. Read references/mcp-client-config.md and configure the Agent client when the MCP entry is missing or stale.
3. Read references/profile-authoring.md before creating or changing a profile file.
4. Read references/onboard-gateway.md before probing a gateway.
5. Create or update the profile using the simple gateway shape; do not expose internal fields like type: interactive_expect unless maintaining legacy config.
6. Start with matcher: builtin-generic unless a known reference matcher fits better.
7. Call ssh.matcher_list to verify available matchers and configured gateways.
8. Call ssh.matcher_probe with the target host and gateway. This must not execute a remote command.
9. If probe succeeds, run one non-destructive smoke command with ssh.run_command, such as hostname; whoami; id. Pass a stable owner_id for the current Agent/thread when the MCP tool supports it.
10. If probe fails because the JumpServer screen is not matched, read the MCP matcher docs and write a custom declarative matcher.
11. Validate custom matcher with ssh.matcher_validate, replay transcript snippets with ssh.matcher_test_transcript, then rerun ssh.matcher_probe.
12. Record the final gateway name, profile path, matcher name, target used for validation, and smoke evidence.
13. Before starting a download, build, install, or other long-running command, read references/background-jobs.md and select the native or compatibility route by MCP tool capability.