What does this skill do, and when should you use it?
This is the skill at skills/cmux-ghostty in the manaflow-ai/cmux repository, aimed at contributors working on cmux itself. It prescribes the commit-and-push workflow for the Ghostty submodule, the Release-optimized GhosttyKit.xcframework build command, and the safe order for updating the parent repo's submodule pointer. Its core value is preventing a subtle class of git accidents: committing submodule changes on a detached HEAD, which leaves the parent pointing at a SHA unreachable from any remote branch and breaks future checkouts or CI jobs. It also mandates keeping docs/ghostty-fork.md current with fork changes and conflict notes.
- Rebuilds GhosttyKit.xcframework with ReleaseFast via
zig build -Demit-xcframework=true -Dxcframework-target=universal -Doptimize=ReleaseFastinside the ghostty submodule - Identifies the manaflow-ai/ghostty fork remote with
git remote -v(usually origin), then creates branches, commits, and pushes inside the submodule - Adds ghostty-org/ghostty as an upstream remote, fetches/merges upstream main, and pushes back to the fork
- Commits the updated ghostty submodule pointer in the parent repository only after the submodule commit is pushed
- Verifies reachability with
git merge-base --is-ancestor HEAD origin/main - Maintains fork change and conflict notes in docs/ghostty-fork.md
- A contributor modifying the ghostty submodule in cmux who needs to rebuild GhosttyKit.xcframework; a maintainer syncing changes from upstream ghostty-org/ghostty into the manaflow-ai/ghostty fork; a developer updating the parent repo's submodule pointer who wants to guarantee the SHA is reachable from a remote branch; a team defining a safe push order for a multi-submodule repo (ghostty, vendor/bonsplit, homebrew-cmux).
- Everyday cmux users who never touch the source — the skill is for contributors, not app users
- Non-macOS or non-zig environments — the xcframework build depends on macOS and the zig toolchain
- Generic submodule projects unrelated to cmux — the fork remote names and submodule list (ghostty, vendor/bonsplit, homebrew-cmux) are cmux-specific
How do you install this skill?
- This is a narrow workflow skill for cmux repository contributors, not general Ghostty terminal users; the skill's license metadata is NOASSERTION — verify GPL-3.0-or-later applicability yourself before use.
- Push and merge instructions write to external repositories; if the upstream or fork remote is unreachable (e.g., from mainland-China networks), the workflow breaks and no alternative is provided.
- Build commands depend on the zig and Xcode toolchains with no version requirements or failure-diagnosis guidance.
- Shell / CLI
- Network access
- Local filesystem
gitzigmacOS (for building GhosttyKit.xcframework)
The source does not document install commands. The skill lives at skills/cmux-ghostty/ in the manaflow-ai/cmux repo (SKILL.md plus references/submodule-safety.md). In an Agent Skills-compatible client, copy the folder into your skills directory per that client's convention, e.g.:
git clone https://github.com/manaflow-ai/cmux.git
cp -r cmux/skills/cmux-ghostty ~/.claude/skills/(The exact destination depends on your client; the source does not spell out this step.)
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- I changed code in the ghostty submodule inside cmux — walk me through committing and pushing it to the manaflow-ai/ghostty fork, then updating the parent submodule pointer
- Merge upstream ghostty-org/ghostty main into our fork and sync the parent repo pointer
- Rebuild GhosttyKit.xcframework and make sure ReleaseFast optimizations are used
- Check that my latest submodule commit is reachable from origin/main so CI won't fail to fetch it
The skill triggers on its SKILL.md description: when modifying the ghostty submodule, rebuilding GhosttyKit.xcframework, updating the parent submodule pointer, or documenting fork conflict notes, the agent follows these rules. Key flow: run git remote -v first to find the fork remote; commit and push inside the submodule to a remote branch; verify reachability with merge-base; only then commit the pointer update in the parent. Details are in the bundled references/submodule-safety.md (ordered safe sequence and fork documentation expectations). The xcframework build command is:
cd ghostty && zig build -Demit-xcframework=true -Dxcframework-target=universal -Doptimize=ReleaseFastWhat are this skill's strengths and limitations?
- Authored in the official cmux repo, so the rules match the project's actual fork and submodule structure
- Explicitly guards against dangling submodule pointers — a common, silent git failure — with a runnable verification command
- Handles the historical remote-naming difference (fork may be origin or manaflow), reducing copy-paste errors
- Ships references/submodule-safety.md with a more detailed ordered sequence
- Only applies to cmux and its submodule layout; limited transferability
- The build step requires the zig toolchain on macOS; other platforms cannot perform the xcframework build
- Installation and triggering are not verbatim documented in the source; relies on generic Agent Skills support in the client
- The repo's license is marked NOASSERTION on GitHub (README states GPL-3.0-or-later plus some BSL 1.1 components) — confirm terms before reusing skill content
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 Ghostty Submodule Workflow Skill this page | 54 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Debugging Skill | 56 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Workspace Skill | 64 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Customization | 55 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Custom Sidebar | 50 · Use with care | ★ 28k | 1d ago | NOASSERTION |
The source does not compare this skill against other skills or tools; what distinguishes it from generic git guidance is that it is tailored to the manaflow-ai/ghostty fork and cmux's submodule set.
How did FollowSkills review this skill?
The skill provides instructional guidance only for git submodule and GhosttyKit build workflows; no network calls, credential handling, or destructive operations. 'Push submodule before updating parent pointer' and the merge-base reachability check reflect a defensive process. Deducted for: no explicit user confirmation, rollback guidance, or failure-recovery steps; external effects of remote pushes are not disclosed as data flow.
Instructions are self-consistent, handle the historical remote-naming difference (git remote -v first), and provide a merge-base --is-ancestor verification command. Deducted for: static review cannot execute; no failure feedback for merge conflicts, fetch failures, or non-fast-forward pushes; tests and edge-case coverage are thin.
Frontmatter description and triggers are clear (modifying the ghostty submodule, rebuilding GhosttyKit.xcframework, updating the pointer); non-fit boundaries are implicit (cmux contributors only). Deducted for: very narrow audience, no environment-fit notes, no disclosure of dependence on GitHub/Ghostty upstream reachability, no Chinese-language consideration.
Good document layering: SKILL.md main flow plus references/submodule-safety.md plus agents/openai.yaml interface; stable naming. Deducted for: skill-level license metadata is NOASSERTION; no versioning, changelog, or explicit update path; the repo mixes GPL-3.0-or-later and BUSL-1.1 and the skill does not state which terms apply.
The core task (safely committing/pushing the submodule and updating the parent pointer) is complete and directly usable, and prevents the real orphaned-SHA pain point versus unguided manual work. Deducted for: static review cannot verify build command reproducibility; output quality and cost/benefit lack execution evidence.
Key claims (safe sequence, orphaned-SHA risk) are partially corroborated by in-repo CI workflows (submodule SHA download logic). Deducted for: no third-party execution evidence, no tests directly covering this skill path, and no fact/inference separation.
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 →