docs(ai): introduce claude skill

Commit `1aaf713`

Eric Bower · 2026-03-31 09:23:00 -0400 EDT

parent 3477fb2

docs(ai): introduce claude skill

1 files changed, +74, -0

A SKILL.md

+74, -0

......@@ -0,0 +1,74 @@
---
name: zmx-session
description: This skill provides instructions for collaborative terminal debugging using zmx for session persistence. Use when the user wants to share a terminal session, debug server logs, troubleshoot infrastructure, or work together on a remote host via SSH. Triggers on mentions of "zmx", "shared session", "terminal debugging", or when user wants Claude to see terminal output.
---

# zmx Collaborative Terminal Sessions

## Overview

zmx is a lightweight terminal session persistence tool. It allows detaching from and reattaching to running shell sessions without killing processes. Unlike tmux, it focuses only on session persistence -- no windows, panes, or splits.

This skill covers using zmx for collaborative debugging where Claude can directly view session history and execute commands.

Run `zmx help` to understand the commands and when to run them.

## Session Setup

The user starts a zmx session and works within it:

```bash
# Create or attach to a named session
zmx attach <session-name>
```

Naming convention suggestion: use descriptive names like `debug-prod`, `k8s-issue`, `logs-api`.

## Viewing Session Context

Claude can directly view the terminal history without user intervention:

```bash
# List active sessions
zmx list

# View recent scrollback from a session (always pipe to tail to limit context)
zmx history <session-name> | tail -200
```

These are read-only commands—run them freely to understand what's happening.

If `zmx list` shows no sessions or the expected session is missing, inform the user and ask them to start or verify their zmx session.

## Command Execution Protocol

**Always ask permission before running commands that execute in the user's session.**

To execute a command in a running session without attaching:

```bash
zmx run <session-name> <command>
```

Then you can wait for the task to complete by running:

```bash
zmx wait <session-name>
```

And you can track the exit code by running:

```bash
zmx list | grep <session-name>
```

Example workflow:

1. User tells Claude the session name and describes the issue
1. Claude runs `zmx history <session-name> | tail -200` to see context
1. Claude analyzes and proposes a command
1. User approves
1. Claude runs via `zmx run <session-name> <command>`
1. Claude runs `zmx history <session-name> | tail -50` to see the output (zmx run does not return output directly -- it goes to the session's scrollback)
1. Claude evaluates the output and provides analysis
1. Repeat steps 3-7 as needed until the issue is resolved

...	...		@@ -0,0 +1,74 @@
	1	+	---
	2	+	name: zmx-session
	3	+	description: This skill provides instructions for collaborative terminal debugging using zmx for session persistence. Use when the user wants to share a terminal session, debug server logs, troubleshoot infrastructure, or work together on a remote host via SSH. Triggers on mentions of "zmx", "shared session", "terminal debugging", or when user wants Claude to see terminal output.
	4	+	---
	5	+
	6	+	# zmx Collaborative Terminal Sessions
	7	+
	8	+	## Overview
	9	+
	10	+	zmx is a lightweight terminal session persistence tool. It allows detaching from and reattaching to running shell sessions without killing processes. Unlike tmux, it focuses only on session persistence -- no windows, panes, or splits.
	11	+
	12	+	This skill covers using zmx for collaborative debugging where Claude can directly view session history and execute commands.
	13	+
	14	+	Run `zmx help` to understand the commands and when to run them.
	15	+
	16	+	## Session Setup
	17	+
	18	+	The user starts a zmx session and works within it:
	19	+
	20	+	```bash
	21	+	# Create or attach to a named session
	22	+	zmx attach <session-name>
	23	+	```
	24	+
	25	+	Naming convention suggestion: use descriptive names like `debug-prod`, `k8s-issue`, `logs-api`.
	26	+
	27	+	## Viewing Session Context
	28	+
	29	+	Claude can directly view the terminal history without user intervention:
	30	+
	31	+	```bash
	32	+	# List active sessions
	33	+	zmx list
	34	+
	35	+	# View recent scrollback from a session (always pipe to tail to limit context)
	36	+	zmx history <session-name> \| tail -200
	37	+	```
	38	+
	39	+	These are read-only commands—run them freely to understand what's happening.
	40	+
	41	+	If `zmx list` shows no sessions or the expected session is missing, inform the user and ask them to start or verify their zmx session.
	42	+
	43	+	## Command Execution Protocol
	44	+
	45	+	Always ask permission before running commands that execute in the user's session.
	46	+
	47	+	To execute a command in a running session without attaching:
	48	+
	49	+	```bash
	50	+	zmx run <session-name> <command>
	51	+	```
	52	+
	53	+	Then you can wait for the task to complete by running:
	54	+
	55	+	```bash
	56	+	zmx wait <session-name>
	57	+	```
	58	+
	59	+	And you can track the exit code by running:
	60	+
	61	+	```bash
	62	+	zmx list \| grep <session-name>
	63	+	```
	64	+
	65	+	Example workflow:
	66	+
	67	+	1. User tells Claude the session name and describes the issue
	68	+	1. Claude runs `zmx history <session-name> \| tail -200` to see context
	69	+	1. Claude analyzes and proposes a command
	70	+	1. User approves
	71	+	1. Claude runs via `zmx run <session-name> <command>`
	72	+	1. Claude runs `zmx history <session-name> \| tail -50` to see the output (zmx run does not return output directly -- it goes to the session's scrollback)
	73	+	1. Claude evaluates the output and provides analysis
	74	+	1. Repeat steps 3-7 as needed until the issue is resolved

Commit 1aaf713

Commit `1aaf713`