What does this skill do, and when should you use it?
This is one of 25 skills bundled in the manaflow-ai/cmux repository, located at skills/cmux-socket-policy/SKILL.md. It is not an executable tool but a policy document written for AI coding agents, covering three areas: socket command threading (telemetry hot paths must stay off the main thread), focus policy (non-focus commands must never activate the app or raise windows), and remote relay authorization (v2 methods are denied by default and require security analysis to allowlist). The skill targets agents working directly on the cmux native macOS app (Swift/AppKit/Ghostty). It is an internal contribution standard for the repository, not a general-purpose tool for end users.
- Forbids DispatchQueue.main.sync for high-frequency telemetry commands such as report_*, ports_kick, status/progress updates, and log metadata updates; parsing, validation, dedup, and coalescing must happen off-main
- Requires new socket commands to default to off-main handling, with an explicit reason in code comments when main-thread execution is necessary
- Enumerates the only commands with explicit focus intent (window.focus, workspace.select/next/previous/last, surface.focus, pane.focus/last, browser focus commands); all other commands must preserve the current user focus context
- Makes open commands (vm/cloud shell, tui, open, new, workspace new/open, agent, surface open/new-terminal, cmux open, cmux ssh) focus only when run interactively and stay in the background when run by an agent or script, with --focus / --no-focus overrides and focus defaulting to false on socket methods
- Enforces default-deny remote relay authorization via RemoteRelayCommandPolicy, requiring the security analysis and policy tests documented in references/remote-relay-authorization.md before allowlisting any v2 method
- A developer contributing to the cmux repository loads this skill before having an agent add or modify socket/CLI commands, preventing main-thread blocking or focus-stealing defects
- An agent implementing telemetry hot paths like report_*, ports_kick, or status/progress updates follows the policy to parse, dedupe, and coalesce off-main
- Someone writing automation that calls the cmux CLI or socket verifies that open commands stay in the background and do not steal the current window focus
- A maintainer wants to allowlist a v2 method for remote cmux ssh relay and follows the skill's default-deny workflow with security analysis
- A code reviewer uses the skill as a checklist to judge whether a command's execution context and focus changes comply with repository conventions
- Everyday cmux terminal users — this is an internal contribution standard and says nothing about daily use, theming, or notification settings
- Developers hoping to reuse it in other projects — the rules are hard-bound to cmux-specific command names (ports_kick, workspace.select, etc.) and are nearly meaningless outside that codebase
- Teams not on the macOS/Swift/AppKit stack — the policy revolves around the AppKit main thread and the macOS app focus model and cannot be ported
How do you install this skill?
- This skill applies only when developing socket/CLI/focus features inside the cmux repository; do not invoke it in other projects or terminal environments.
- The skill files do not state their own license; the repo mixes GPL-3.0 and BUSL-1.1 (web/ and other directories) — verify licensing scope before reusing the policy text.
- The relay authorization policy is security-critical (deny-by-default, allowlist review); when touching related methods, verify the actual test files the references point to rather than acting on the skill text alone.
- This is a static source review with no execution; all scores are low confidence.
- Local filesystem
The skill is a file under the skills/ directory of the manaflow-ai/cmux repository; the source material documents no standalone install commands. To use it, clone the repository and place the skills/cmux-socket-policy/ directory into your Agent Skills-compatible client's skills directory, or simply ask the agent to read SKILL.md and the two reference documents under references/. Exact installation steps are not documented in the source.
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/manaflow-ai/cmux.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/skills/cmux-socket-policy" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- I'm adding a new report_metrics socket command to cmux — read the cmux-socket-policy skill first and implement it per the threading policy, with argument parsing and dedup off-main
- Write a script that opens 10 cmux workspaces; per the focus policy don't steal my current window focus, keep socket calls at the default focus=false
- I want to allowlist the workspace.rename v2 method for cmux ssh remote relay — read references/remote-relay-authorization.md first, do the security analysis, and add the policy tests
- Review the new CLI command in this PR: it calls DispatchQueue.main.sync for ports_kick telemetry and activates the app window — flag the violations against cmux-socket-policy
The skill declares its trigger conditions in the SKILL.md description: load it whenever a task involves adding or changing socket commands, CLI commands, telemetry commands, focus/select/open/close/send-key behavior, or automation that could steal app focus. The flow is to read the threading and focus policy bodies in SKILL.md, then consult the two references as needed: references/threading-and-focus.md (when adding a command or changing its execution context) and references/remote-relay-authorization.md (when adding or changing a v2 method or remote CLI command). Note that open commands support --focus / --no-focus flags, socket methods default focus to false, and a pane opened without focus is marked unread.
What are this skill's strengths and limitations?
- Rules are concrete down to command names and APIs (DispatchQueue.main.sync, defaultFocusForUserOpen), making them directly actionable rather than vague principles
- Sensible focus defaults: agent/script-triggered open commands run in the background by default, interactive use gets focus, with explicit opt-in/opt-out flags
- Remote relay uses a default-deny allowlist model with mandatory security analysis and policy tests — a clear security posture
- Pure documentation skill with no runtime dependencies; any agent client that can read files can use it directly
- Only useful for developing the cmux repository itself; near-zero transfer value to other projects
- The source provides no evidence of tests or CI enforcement verifying compliance with the policy
- Depends on two reference documents; a repo restructuring (e.g., remote-relay-authorization.md being renamed) would break the skill
- No install or invocation commands are given; adoption depends on the client supporting the Agent Skills directory convention
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| cmux Socket Policy Skill this page | 58 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Workspace Skill | 64 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux-browser: Browser Automation Skill for cmux | 60 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Diagnostics | 51 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Shared Behavior Rules | 48 · Use with care | ★ 28k | 1d ago | NOASSERTION |
The source does not compare this skill to any direct alternative. The cmux application itself is compared to tmux in the README (tmux is a multiplexer running inside any terminal; cmux is a native macOS app with vertical tabs, an embedded browser, and a socket API), but that is a product-level comparison, not relevant to this internal coding-policy skill.
How did FollowSkills review this skill?
The skill contains no executable code; it declares policies only: telemetry off main thread by default, non-focus commands must not steal app focus, remote relay denies by default and requires security analysis plus policy tests (GHSA-9vmv-3hjw-j28c). Data-flow disclosure is clear and least-privilege is explicit. Deducted for: unverified publisher and NOASSERTION repo-level license metadata; the skill itself does not state its license or attribution.
SKILL.md and both references are internally consistent, with concrete trigger conditions, an explicit focus-intent allowlist, and named defaults (defaultFocusForUserOpen, --focus/--no-focus) and test paths. Static review cannot execute anything; whether the cited test suites actually cover key paths was not reproduced — deducted.
Audience (developers/agents adding or changing cmux socket, CLI, telemetry, or focus behavior) and invocation timing are precisely described; the boundary (cmux-repo contribution only) is clear. Deducted for: extremely narrow scope, no explicit non-fit statement for other projects, English-only documentation.
Good layering: SKILL.md as main layer, references for progressive disclosure, agents/openai.yaml interface metadata, and a CI review-bot rule enforcing the relay policy. Deducted for: no version or changelog in the skill, NOASSERTION license metadata, and maintenance/update responsibility resting on repo-level context rather than the skill itself.
As a coding-policy guide it directly constrains agent behavior, preventing focus stealing and main-thread deadlocks — clear marginal value over letting an agent guess. Deducted for: static review cannot verify actual agent compliance, output is behavioral constraint rather than a directly usable artifact, and comparative-benefit evidence is limited.
Citations are auditable: a concrete GHSA id, concrete source and test paths (RemoteCLIRelayPolicyTests, CmuxRemoteWorkspace/Relay/), and a review-bot rule file. All are author claims; static review could not independently reproduce the policy implementation or test coverage — deducted.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →