---
name: houmao-agent-messaging
description: Use Houmao's supported messaging and control surfaces to communicate with already-running managed agents through prompt, interrupt, gateway, raw-input, mailbox routing, or reset-context workflows, preferring live gateway-backed delivery when available.
license: MIT
---

# Houmao Agent Messaging

Use this Houmao skill when you need to communicate with an already-running Houmao-managed agent, whether the caller is another agent with an installed Houmao skill home or an external operator working from outside the managed session. If the real task is generic read-only managed-agent inspection rather than communication, use `houmao-agent-inspect` instead.

The trigger word `houmao` is intentional. Use the `houmao-agent-messaging` skill name directly when you intend to activate this Houmao-owned skill.

## Scope

This packaged skill covers exactly these managed-agent communication and control actions:

- `discover`
- `prompt`
- `interrupt`
- `gateway-queue`
- `send-keys`
- `mail-handoff`
- `reset-context`

Supported surfaces for this skill include:

- `houmao-mgr agents state`
- `houmao-mgr agents gateway status`
- `houmao-mgr agents mail resolve-live`
- `houmao-mgr agents prompt`
- `houmao-mgr agents interrupt`
- `houmao-mgr agents gateway prompt`
- `houmao-mgr agents gateway interrupt`
- `houmao-mgr agents gateway send-keys`
- `houmao-mgr agents gateway tui state|history|note-prompt`
- managed-agent HTTP routes under `/houmao/agents/*`

This packaged skill does not cover:

- `houmao-mgr agents launch|join|stop|relaunch|cleanup`
- `houmao-mgr project easy specialist create|list|get|remove`
- `houmao-mgr project easy instance launch|list|get|stop`
- generic managed-agent inspection of liveness, mailbox posture, runtime artifacts, logs, or direct tmux backing
- ordinary mailbox `status|list|peek|read|send|reply|archive` operations
- mailbox transport-specific filesystem or Stalwart internals
- gateway attach or detach lifecycle work
- direct filesystem editing under runtime or mailbox paths

## Workflow

1. Identify which messaging intent the user actually wants: discovery, ordinary prompt with gateway preference, interrupt, explicit gateway queueing, raw control input, mailbox handoff, or reset-context.
2. If the request is really about generic read-only inspection of liveness, mailbox posture, logs, runtime artifacts, or tmux backing, route it to `houmao-agent-inspect` instead of handling it as messaging.
3. Recover the target managed-agent selector from the current prompt first and recent chat context second when it was stated explicitly.
4. If the selected action still lacks a required target or explicit message input, ask the user in Markdown before proceeding.
5. Choose one `houmao-mgr` launcher for the current turn:
   - first run `command -v houmao-mgr` and use the `houmao-mgr` already on `PATH` when present
   - if that lookup fails, use `uv tool run --from houmao houmao-mgr`
   - only if the PATH lookup and uv-managed fallback do not satisfy the turn, choose the appropriate development launcher such as `pixi run houmao-mgr`, repo-local `.venv/bin/houmao-mgr`, or project-local `uv run houmao-mgr`
   - if the user explicitly asks for a specific launcher, follow that request instead of the default order
6. Reuse that same chosen launcher for the selected messaging action.
7. Prefer the managed-agent seam first:
   - `houmao-mgr agents ...` for CLI-driven work
   - `/houmao/agents/*` for pair-managed HTTP control
8. Before ordinary prompt or mailbox handoff work, resolve current live gateway capability unless the current prompt or recent chat context already provides that fact explicitly:
   - use `houmao-mgr agents gateway status` or `GET /houmao/agents/{agent_ref}/gateway` for prompt-lane gateway decisions
   - use `houmao-mgr agents mail resolve-live` or `GET /houmao/agents/{agent_ref}/mail/resolve-live` for mailbox bindings and the exact live `gateway.base_url`
   - when mailbox work is required, use that discovery result to hand off to `houmao-agent-email-comms` for ordinary mailbox actions or `houmao-process-emails-via-gateway` for one open-mail round
9. Use direct gateway `/v1/...` HTTP only when the task genuinely needs gateway-only control behavior and the exact live `gateway.base_url` is already available from current context or supported discovery.
10. Load exactly one action page:
   - `actions/discover.md`
   - `actions/prompt.md`
   - `actions/interrupt.md`
   - `actions/gateway-queue.md`
   - `actions/send-keys.md`
   - `actions/mail.md`
   - `actions/reset-context.md`
11. Use the local references only when you need the intent matrix or the managed-agent HTTP route summary:
   - `references/intent-matrix.md`
   - `references/managed-agent-http.md`

## Missing Input Questions

- Recover required values from the current prompt first and recent chat context second, but only when the user stated them explicitly.
- If any required input is still missing after that check, ask the user for exactly the missing fields instead of guessing.
- When asking for missing input, use readable Markdown:
  - a short bullet list when only one or two fields are missing
  - a compact table when the intended lane or several required fields need clarification
- Name the command or route you intend to use and show only the missing fields needed for that path.

## Routing Guidance

- Use `houmao-agent-inspect` when the user wants generic managed-agent inspection of current liveness, mailbox posture, runtime artifacts, logs, or direct tmux backing.
- Use `actions/discover.md` when you first need to identify the target managed agent or discover current gateway and mailbox capability.
- Use `actions/prompt.md` when the user wants one normal conversational turn; discover gateway availability first and prefer the gateway-backed prompt lane when a live gateway exists.
- Use `actions/interrupt.md` when the user wants the transport-neutral interrupt path for one managed agent.
- Use `actions/gateway-queue.md` when the user explicitly wants gateway queue management, raw gateway-owned TUI inspection, or prompt-note provenance beyond the ordinary gateway-preferred prompt path.
- Use `actions/send-keys.md` when the user needs exact key delivery such as slash-command menus, arrow navigation, `Escape`, or partial typing in a live TUI session.
- Use `actions/mail.md` when the target has mailbox capability and you need to route the work to the correct mailbox skill after resolving live bindings.
- Use `actions/reset-context.md` when the user wants clear-context, reset-then-send, or next-prompt chat-session control.

## Guardrails

- Do not guess the target managed agent, gateway base URL, mailbox capability, or intended messaging lane.
- Do not present this skill as the owner of generic managed-agent inspection; use `houmao-agent-inspect` for that broader read-only work.
- Do not skip live gateway discovery when prompt or outgoing mailbox routing depends on whether the target currently has a gateway.
- Do not treat raw `send-keys` as a substitute for ordinary prompt-turn work.
- Do not redirect raw terminal shaping to `agents prompt` or `agents gateway prompt`.
- Do not guess a direct gateway host or port when the exact live `gateway.base_url` is not already available.
- Do not skip `command -v houmao-mgr` as the default first step unless the user explicitly requests a different launcher.
- Do not probe Pixi, repo-local `.venv`, or project-local `uv run` before the PATH check and uv fallback unless the user explicitly asks for one of those launchers.
- Do not treat this skill as the owner of ordinary mailbox operations; hand mailbox work to `houmao-agent-email-comms` or `houmao-process-emails-via-gateway`.
- Do not restate filesystem mailbox layout, Stalwart transport detail, or the `/v1/mail/*` contract in full here; delegate that work to the mailbox skills.
- Do not invent unsupported `houmao-mgr` reset-context flags.
- Do not use deprecated `houmao-cli` or `houmao-cao-server` entrypoints for managed-agent messaging.
