From 608bb77d4280a7e6489080232a3384a93366e76e Mon Sep 17 00:00:00 2001 From: Amolith Date: Mon, 6 Apr 2026 17:39:49 -0600 Subject: [PATCH] feat(jj): add skill --- README.md | 21 +++++-- skills/using-jujutsu/SKILL.md | 104 ++++++++++++++++++++++++++++++++++ 2 files changed, 121 insertions(+), 4 deletions(-) create mode 100644 skills/using-jujutsu/SKILL.md diff --git a/README.md b/README.md index f904612c21a7453b30a22abdf4a6bd59f9452bc5..c138dfe6a605d8034faaeff65ee37d02fcc2f870 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,9 @@ token count, plus overall metadata usage. I've used and tested them most with - [using-exe-dev](skills/using-exe-dev/SKILL.md): Guides working with [exe.dev] VMs, which provide Linux VMs with persistent disks, instant HTTPS, and built-in auth via SSH. +- [using-jujutsu](skills/using-jujutsu/SKILL.md): Guides [jujutsu] (jj) + workflows, covering commit selection, change creation, diff reading, and + common pitfalls that trip up agents. - [working-with-tmux](skills/working-with-tmux/SKILL.md): Spawns and manages background processes via tmux. Creates windows, sends commands, and captures output without blocking the main session. Useful for servers and long tasks. @@ -132,6 +135,7 @@ token count, plus overall metadata usage. I've used and tested them most with [wt]: https://git.secluded.site/wt [gum]: https://github.com/charmbracelet/gum [exe.dev]: https://exe.dev +[jujutsu]: https://jj-vcs.github.io/jj/latest/ ## Installation @@ -517,6 +521,15 @@ Token breakdown: ─────────────────────────────────────────────── Total: 420 tokens +=== using-jujutsu === + +Token breakdown: + Name: 9 tokens + Description: 55 tokens + Body: 735 tokens (92 lines) + ─────────────────────────────────────────────── + Total: 799 tokens + === working-with-tmux === Token breakdown: @@ -565,10 +578,10 @@ Token breakdown: SUMMARY ============================================================ -Skills: 30 -Metadata: 1885 tokens -Combined bodies: 32121 tokens -Overall: 87519 tokens +Skills: 31 +Metadata: 1949 tokens +Combined bodies: 32856 tokens +Overall: 88318 tokens Validation errors: 0 Largest skills (by total tokens): diff --git a/skills/using-jujutsu/SKILL.md b/skills/using-jujutsu/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..e811d1e4b11c5a93108e9449e66c7f11e13ac70e --- /dev/null +++ b/skills/using-jujutsu/SKILL.md @@ -0,0 +1,104 @@ +--- +name: using-jujutsu +description: >- + Guides jujutsu (jj) version control workflows and avoids common agent + pitfalls. Use when the project uses jj or jujutsu for version control, + when committing changes, creating new changes, or inspecting history + with jj. Not for use with git repos. +license: GPL-3.0-or-later +metadata: + author: Amolith +--- + +Jujutsu (jj) is a Git-compatible VCS with a different mental model. This skill +covers the non-obvious bits that trip agents up. + +## Never use --interactive + +`jj split --interactive`, `jj commit --interactive`, `jj squash --interactive`, +and any other `--interactive` flag open a TUI diff editor that agents cannot +interact with. Always use path arguments to select files instead: + +```bash +# Bad — hangs forever waiting for TUI input +jj commit --interactive -m "Add config parser" + +# Good — selects specific files +jj commit -m "Add config parser" internal/config/config.go internal/config/config_test.go +``` + +If changes within a file ought to be split, politely ask the user to run split, +give them the appropriate command, and include instructions on what to split. +It's very easy, so having the user do the splits manually is no trouble :) It's +worth it for nice, small, focused changes. + +## Specify files when committing + +`jj commit -m "msg"` with no paths grabs everything in the working copy. This +easily pulls in scratch files, experiments, or unrelated changes. Always list +the files you intend to commit: + +```bash +jj commit -m "Add snapshot screen" internal/ui/screens/snapshot.go internal/ui/screens/snapshot_test.go +``` + +The remaining changes stay in the new working-copy commit on top. + +## jj new vs jj commit + +`jj new` and `jj commit` both create a new change, but they work +differently: + +- **`jj new -m "msg"`** creates an empty change on top of the current one. The + current change keeps all its content as-is. +- **`jj commit -m "msg" [files]`** is like `jj describe` + `jj new` but lets you + select which files stay in commit you're creating. The rest move to the new + working-copy commit. + +Use `jj new` when starting fresh work on top of a completed change. Use `jj +commit [files]` when you want to finalize specific files and continue working on +the rest. Use `jj diff --summary` to see what's changed before running either, +so you don't accidentally leave changes in the previous commit that should move +into the new working copy. + +## Use jj diff --git for readable diffs + +The default `jj diff` output interleaves old and new lines in a format that is +hard to parse. Always use `jj diff --git` for standard unified diffs: + +```bash +# Hard to read +jj diff + +# Standard unified diff format +jj diff --git + +# Also works with revision arguments +jj diff --git -r usnrpsky +``` + +For a quick overview without the full diff, `jj diff --summary` (or `-s`) lists +just the changed files with their M/A/D status. Prefer this over `--stat` when +you only need to know which files changed: + +```bash +jj diff --summary +# M cmd/root.go +# A internal/ui/screens/confirm.go +# A internal/ui/screens/confirm_test.go +``` + +`--stat` can still be useful at times. + +## Change IDs vs git commit hashes + +jj uses short change IDs like `usnrpsky` for its own commands. Many external +tools (code review CLIs, CI systems, etc.) need git SHAs instead. To get them: + +```bash +# Show change IDs alongside git commit hashes +jj log --limit 5 -T 'change_id ++ " " ++ commit_id ++ "\n"' + +# Just the git hash for a specific change +jj log -r usnrpsky -T 'commit_id ++ "\n"' --no-graph +```