What does this skill do, and when should you use it?
cmux-markdown is a skill for cmux, a Ghostty-based macOS terminal, that shows how to render Markdown files in a split panel via `cmux markdown open`. The panel renders rich formatting — headings, code blocks, tables, lists — and watches the file on disk, re-rendering on every write with correct handling of atomic replacements like editor saves and `sed -i`. It is aimed at having coding agents write plans or task lists to .md files and displaying them live next to the terminal. It requires the cmux app itself to be installed.
- Opens a Markdown file in a split panel next to the current terminal with
cmux markdown open plan.md - Watches the file and re-renders the panel each time it is written to disk
- Resolves relative paths against the caller's cwd, expands
~, and returns the absolute path in the output - Renders h1-h6 headings, monospace code blocks, tables, nested lists, blockquotes, links, and inline images in light and dark mode
- Accepts
--workspace,--surface, and--windowoptions to place the panel
- A developer running coding agents like Claude Code who wants the agent to write its full plan to a .md file and track progress in a panel beside the terminal
- A developer juggling several workspaces who reads documentation or changelogs in a split pane while working
- Anyone running another process that updates a notes file progressively, where the panel should refresh on each update without reopening
- A team standardizing the workflow: the skill includes an AGENTS.md snippet to instruct agents in a project
- Non-macOS users — cmux is a macOS-only native app and this skill depends entirely on the cmux CLI
- Users who want generic Markdown rendering in any terminal without cmux — the panel rendering is built into the cmux app
How do you install this skill?
- The skill only works on machines with the cmux desktop app installed (macOS-only); this prerequisite is not declared in the skill docs, so non-macOS users will fail outright.
- Repository license metadata is NOASSERTION: actual terms are GPL-3.0-or-later, but web/ and related directories are BUSL-1.1 (commercial license required for production use/self-hosting) — verify scope before enterprise use.
- Panel rendering, live reload, and watcher behaviors are documentation claims not verified by execution or static testing; re-rendering files over ~100KB may cause brief UI hitches.
- If a watched file is deleted, the panel does not reconnect when the file reappears; the user must close and reopen the panel.
- Publisher is unverified by FollowSkills; no Chinese-language support statement, and docs/distribution are primarily overseas.
- Shell / CLI
- Local filesystem
cmux (macOS app with the cmux CLI)
The skill lives at skills/cmux-markdown/SKILL.md in the manaflow-ai/cmux repository, part of a collection of 25 skills; the README documents no per-skill install command. The prerequisite is installing the cmux app:
macOS (DMG / Homebrew)
brew tap manaflow-ai/cmux
brew install --cask cmuxOnce cmux is installed, copy the skill folder into your Agent Skills directory (e.g. Claude Code's skills directory); the exact path is not documented in the source.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- Write the implementation plan to plan.md and open it in cmux so I can watch it update as you work
- Create a task checklist file, open it in a cmux panel, and check off items as you complete them
- Draft the design doc in design.md and open a preview — refresh the panel automatically whenever I edit the file
The core flow is write-then-open: finish writing the full .md file before opening it so the panel never shows a partially written file; afterward, overwrite or append freely — each write triggers a re-render.
cmux markdown open plan.md
cmux markdown open design.md --workspace workspace:2Relative paths resolve against the caller's cwd and ~ expands; use --surface or --window to target a different location. To have coding agents in a project use this automatically, add the "Plan Display" section from the skill to the project's AGENTS.md.
What are this skill's strengths and limitations?
- Live reload handles atomic replacements (editor saves, sed -i) correctly, so no manual refresh is needed
- Broad rendering coverage: code blocks, tables, nested lists, links, inline images, with light and dark mode
- Deep-dive references (commands.md, live-reload.md) document command syntax and file-watching details
- Ships a ready-to-paste AGENTS.md snippet for agent integration
- Hard dependency on cmux — macOS only, and the cmux app must be installed and running
- The repo's License field is NOASSERTION; the README states GPL-3.0-or-later for the app, but per-skill terms should be confirmed
- No automated tests or non-cmux fallback are documented in the SKILL.md
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 Markdown Viewer this page | 52 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| Apple Bridges: Native Apple App Access for Claude Code | 53 · Use with care | ★ 48 | 1mo ago | MIT |
| Gorden PPT Skill | 61 · Recommended | ★ 3.2k | 3mo ago | NOASSERTION |
| LLM Wiki — a second brain for AI agents | 58 · Recommended | ★ 119 | 28d ago | MIT |
| Book-to-Skill Converter | 57 · Use with care | ★ 34k | 6d ago | MIT |
How did FollowSkills review this skill?
The skill is documentation-only: it instructs the agent to write a user-specified .md file and run `cmux markdown open` for a read-only local panel — no script execution, no network access, no credential or sensitive data flows, so least privilege is inherently satisfied; path resolution (cwd, ~ expansion, absolute path echoed back) is transparent. Deductions: repository license metadata is NOASSERTION (actual: GPL-3.0 with some BUSL-1.1 directories), and panel rendering/watcher behavior depends on the cmux binary that cannot be statically audited; publisher is unverified.
Docs are self-consistent: command syntax, flag defaults, and output shape (OK surface=... / -- fields) agree between SKILL.md and references/commands.md; live-reload.md documents atomic-replacement detection, the 500ms retry, the file-unavailable state, and >100KB performance limits — reasonably diagnosable failure modes. Deductions: static review cannot reproduce paths; no committed tests cover the skill's key claimed behaviors (repo CI tests target internal app modules, not the skill); non-OK output shapes are undocumented.
Trigger semantics are clear: the description precisely scopes 'open markdown files, rich rendering beside the terminal, live reload', with an AGENTS.md integration example; boundaries (requires cmux, macOS-only, read-only panel, no reconnect after deletion) are mostly inferable. Deductions: hard dependency on the installed cmux desktop app, unusable outside macOS, not declared at skill level; no Chinese-language support statement; the core function depends on a desktop app distributed via overseas channels, creating friction for mainland-China users.
Good architecture: concise SKILL.md plus two deep-dive references with progressive disclosure, command reference, flag table, behavior details, and performance limits; flags have documented defaults. Deductions: no per-skill versioning or changelog, no standalone license statement (NOASSERTION), maintenance ownership and update path only indirectly visible at repo level, known limitations scattered across references.
The core path (write .md → rich panel render → live reload) is clear and beats repeatedly dumping plans into the terminal; the write-then-open ordering guidance avoids partially written files. Deductions: static review cannot verify rendering quality (tables, inline images, light/dark modes) as claimed; comparative benefit rests mostly on author narrative; representative outputs are unverified, capping below the static limit's upper end.
Primary material is auditable: skill docs, sample output, and live-reload implementation details (DispatchSource/O_EVTONLY, inode reconnection) are readable claims, with repo-level corroboration from README and SECURITY.md. Deductions: no third-party or CI execution evidence validates the skill's claimed behaviors (markdown rendering, watcher semantics); cross-source corroboration is thin; fact/inference separation is not established.
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 →