A Codex agent skill for working with repositories managed by
Jujutsu (jj).
The skill teaches Codex workflows for inspecting and editing jj change
graphs, moving and splitting changes, rebasing stacks, resolving conflicts,
and working with megamerge-style integration changes. It is intended for
repositories where jj is the primary version-control interface, including
colocated repositories that also contain a .git directory.
Codex discovers personal skills under:
~/.agents/skills/
Clone this repository into that directory:
mkdir -p ~/.agents/skills
git clone https://github.com/mhw/jj-skill.git ~/.agents/skills/jjThe resulting layout should look like:
~/.agents/skills/
└── jj/
├── SKILL.md
├── agents/
│ └── openai.yaml
└── references/
└── ...
Codex discovers skills from this directory. If a newly installed or updated skill is not available in the current session, restart Codex.
In the Codex CLI or IDE extension, /skills can be used to see the available
skills. The skill can also be invoked explicitly by mentioning:
$jj
Explicit invocation should not normally be necessary. Codex can select the
skill automatically when a task matches the description in SKILL.md.
If the skill was installed with the git clone command above, update it with:
git -C ~/.agents/skills/jj pull --ff-onlyInstalling the skill makes its detailed jj workflows available to Codex,
but there is a small bootstrap problem: Codex has to decide that the skill is
relevant before it reads the full SKILL.md.
For that reason, it is useful to put the basic repository-detection rule in
Codex's global AGENTS.md as well. Global instructions are loaded before
Codex starts work, so this provides a small, always-present rule telling it
that a repository containing .jj is managed with jj.
By default the global instructions file is:
~/.codex/AGENTS.md
If CODEX_HOME is set, use:
$CODEX_HOME/AGENTS.md
If you do not already have a global AGENTS.md:
mkdir -p "${CODEX_HOME:-$HOME/.codex}"
${EDITOR:-vi} "${CODEX_HOME:-$HOME/.codex}/AGENTS.md"Add the following:
## Version control
Before performing repository-management operations, determine whether the
working tree is managed by Jujutsu.
If the repository contains a `.jj` directory, use `jj` for version-control
operations. Do not use `git` commands to mutate the repository unless direct
Git interoperability is explicitly required.
When working in a Jujutsu repository, use the `jj` skill for detailed
workflow guidance.If you already have ~/.codex/AGENTS.md (or $CODEX_HOME/AGENTS.md), add the
section above to the existing file rather than replacing it.
The distinction between the two pieces is intentional:
AGENTS.mdcontains the small, unconditional rule: detect Jujutsu repositories and do not accidentally manage them with Git.- The
jjskill contains the more detailed, task-specific guidance that Codex loads when it is actually doingjjwork.
This is particularly useful for colocated repositories. A repository may
contain both .jj and .git; the presence of .git does not mean Codex
should fall back to Git commands.
To check that Codex is loading your global instructions, run this from a repository:
codex --ask-for-approval never "Summarize the current instructions."The response should include the Jujutsu/version-control guidance from your
global AGENTS.md.
You can then start Codex in a repository containing .jj and ask a normal
version-control question without explicitly mentioning the skill, for example:
Show me the current change and the changes immediately before it.
Codex should recognise the repository as a Jujutsu repository and use jj
rather than Git. If needed while testing the installation, explicitly invoke
the skill with $jj.
OpenAI's Codex documentation describes personal skills, skill discovery and implicit/explicit invocation here: