jujutsu-workflow
Use when a coding agent works in a repository where Jujutsu (jj) is available (a `.jj/` directory) — running jj commands, making speculative edits, splitting changes, recovering with the operation log (jj undo / jj op restore), handing off a PR to Git/GitHub/GitLab, updating a PR after review, or coordinating parallel agents. Uses jj as the local change-management layer while keeping Git as the canonical remote, PR, CI, and audit interface. Also use to avoid jj's agent footguns (pager/editor hangs, commit absorption, colocated git/jj desync) or to replace fragile git reset/checkout/stash/rebase recovery with reversible jj operations.
How do I install this agent skill?
npx skills add https://github.com/netresearch/jujutsu-workflow-skill --skill jujutsu-workflowIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a comprehensive workflow for using the Jujutsu (jj) version control system alongside Git. It includes safety checks to prevent agent hangs from interactive commands and scripts for environment detection and verification. No malicious patterns were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Jujutsu Workflow
Prefer jj (Jujutsu) over raw git whenever a .jj/ repo is present. Git stays the canonical remote/PR/CI/audit interface: mutate with jj, verify with read-only Git.
1. Detect & gate first
Run ${CLAUDE_SKILL_DIR}/scripts/detect_jj_state.sh, or check manually:
.jj/present → jj repo: usejj, never mutating rawgit..jj/and.git(a directory, or a file in a jj 0.46+ workspace) → colocated: mutate withjj, read with git, never touch the git index/staging.- only
.git/→ plain Git repo: do not introducejjunless asked. - in a git worktree,
jj root≠git rev-parse --show-toplevel→ shadowed (exit 3): jj answers for the parent repo. Run nojj; use git, then ask.
See references/git-interop.md.
2. Agent-safety rules (non-negotiable)
- Always
--no-pageron commands that print. Do not writeui.paginateinto the user's config —--useroutlives the session and takes paging away from their interactivejjtoo. - Always
-mor--stdin(describe). Never run editor/TUI forms — barejj describe|commit|squash,jj split(interactive),jj squash -i,jj resolve,jj diffedit— they hang agents. jjsnapshots the working copy only when a jj command runs, not on every file write.
See references/agent-safety.md.
3. Edit loop
jj --no-pager status
# edit files (snapshotted on the next jj command)
jj --no-pager diff
jj describe --stdin <<'EOF' # quoted heredoc: no file in the repo, backticks stay literal
<project-conventional message>
EOF
jj new -m "<next unit>" # one change per logical unit
Split non-interactively: jj split <path> -m "<msg>". See references/command-map.md.
4. Recover (reversible)
jj --no-pager op log → jj undo or jj op restore <id>. Conflicts are first-class: jj status flags them; edit markers, then verify. See references/recovery-playbook.md.
5. Hand off via Git
jj git fetch
jj rebase -d <default-branch>
jj bookmark create <branch> -r @- # every pushed commit needs a description
jj git push --bookmark <branch> # new bookmarks push directly
Never push to a protected/default branch; never rewrite public history unless allowed. Open the PR with gh/glab. See references/pr-handoff.md.
6. Parallel agents
One jj workspace per concurrent agent — never share a working copy. See references/parallel-agents.md.
7. Verify before "done"
Run ${CLAUDE_SKILL_DIR}/scripts/verify_handoff.sh, or report jj --no-pager status, jj --no-pager log --limit 10, jj --no-pager diff --stat, git status --short --branch. Never claim "done/tested/ready" without that output; disclose force-pushes, recoveries, conflicts.
When jj helps, and when it doesn't: references/why-jj-for-agents.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/netresearch/jujutsu-workflow-skill/jujutsu-workflow">View jujutsu-workflow on skillZs</a>