Portable skill for existing T3 session interfaces: scope and placement

[zachspartofaday]

Problem

An agent asked to read or message a T3 thread on another machine can mistake its
current MCP connection for a connection to every environment visible in the T3
client. A thread ID alone does not establish which environment to address.
Agents outside T3 also need to discover the supported interfaces without
inventing API requests or reading credentials from the installation.

T3 already supplies the underlying capabilities:

• Outside agents
  documents authenticated MCP access to a selected environment.
• Merged PR #22732 supplies
  t3 thread list, show, send, and start on the host running that environment.
• Open PR #16684, with
  #16655, proposes native routing
  to linked environments. #16719
  separately addresses remote delegated tasks.

The proposed contribution is discoverable guidance for those supported
interfaces, not another transport or an implementation of that open PR stack.

Proposed scope

One provider-neutral t3-sessions skill, with a short entrypoint and a CLI
reference only if the examples need the extra space. Its triggers would be
finding, inspecting, messaging, or explicitly starting a durable T3 conversation,
locally or on another environment. Ordinary coding and generic subagent requests
would continue to use the host's existing orchestration guidance.

The skill would teach these decisions:

1. Establish the destination environment, project and exact thread ID. Read the
   selected thread before acting. A local thread_not_found is not evidence
   that a remote thread disappeared.
2. Prefer an available, already-authorized MCP connection to the destination.
   Use only fields actually exposed by its tools; do not assume the pending
   environmentId routing feature has shipped.
3. When the task authorizes host access, use the destination's supported t3 thread CLI, locally or through an existing SSH route, as the account owning
   that environment. Check its help and explicit data-directory selection.
   Do not extract tokens, call undocumented dispatch endpoints, or edit live
   state. Existing caller and task restrictions still apply.
4. Inspect before sending; pass message text through stdin. Explain that CLI
   sends queue behind a busy turn. Use returned IDs and status to retrieve the
   result and distinguish acceptance from completion.
5. Start a top-level conversation only when requested. Choose the destination
   project and intended workspace. Use the supported worktree option for
   independent code changes; source refs must exist there and dirty local
   files do not transfer. Preserve requested provider/model/options and
   permission limits, reporting unsupported requirements before launching.
6. Keep a CLI-created conversation distinct from a delegated task. It does not
   acquire a parent callback or delegated-task lifecycle. Reconcile uncertain
   sends and launches before retrying; the CLI does not expose a retry key.

Remove all deployment-specific hosts, accounts, routes, paths, project names,
thread IDs, authority roles and installation rules. Point to the existing
outside-agent guide for setup rather than duplicating OAuth instructions.
Avoid copying the MCP tool catalog or T3's injected orchestration rules.

Placement and approval requested

Would maintainers accept this bounded guidance contribution, and where should
a user-installable skill live? The current .agents/skills collection contains
repository testing and triage skills; it is not evidence of a shipped user-skill
distribution mechanism.

An alternative first slice is a concise clarification in the existing
outside-agent guide covering environment selection and running the host CLI
over an existing SSH connection. Maintainers can choose that narrower scope
without committing to a new skill distribution mechanism.

This proposal seeks explicit direction and scope approval under
CONTRIBUTING
before implementation. The existing CLI merge and cross-environment PRs are
context, not approval of this separate contribution.

Verification for the eventual PR

Check all command examples against the approved upstream revision and current
CLI help. Use isolated development state for any live mutation checks. Exercise
destination selection, a queued send, a requested worktree launch, needs-input
exit 2, and uncertain-response reconciliation where applicable. Independently
evaluate realistic requests to catch accidental launch, invented routing fields,
silent option loss or automatic retry. Run vp run check:changed before pushing,
and report exactly which paths were tested and which were not. No production
threads need to be created for proposal research.

Keep the eventual PR to this one discoverability problem, use the repository PR
template and a conventional title, link the explicit approval, and end with the
model/harness attribution.

Prepared with GPT-6 Astra through the Codex harness in T3 Code.