Using jjj with AI Agents

jjj ships a skill file that teaches AI coding assistants — Claude Code, Gemini CLI, or any agent that supports skills — to use jjj commands natively. Once installed, your agent can create problems, propose solutions, add critiques, and manage milestones without you having to explain the commands each time.

Installing the Skill

Claude Code

Skills live in ~/.claude/skills/. Download the jjj skill with:

mkdir -p ~/.claude/skills/jjj && \
  curl -fsSL https://jjj.recursivewhy.com/SKILL.md \
    -o ~/.claude/skills/jjj/SKILL.md

Then invoke it with /jjj in any Claude Code session, or Claude will pick it up automatically when working in a jj repository.

Gemini CLI

Add the skill as a custom slash command in your GEMINI.md:

mkdir -p ~/.gemini/skills/jjj && \
  curl -fsSL https://jjj.recursivewhy.com/SKILL.md \
    -o ~/.gemini/skills/jjj/SKILL.md

Or paste the skill content directly into your project’s GEMINI.md under a ## jjj section.

Raw skill file

The skill file is plain Markdown and works with any agent that accepts context files:

https://jjj.recursivewhy.com/SKILL.md

What the Skill Teaches

The skill is the agent-facing manual, and it is checked against the real CLI by tests/skill_test.rs, so it cannot drift into teaching commands that do not exist. It covers:

The machine interface

The full command reference with correct syntax (current vocabulary: submit / approve / withdraw, not older aliases)
Entity resolution — fuzzy title match, UUID prefix, or full UUID, and why anything scripted should use ids
--json on every command, and reading ids back out of it
Establishing identity first (JJJ_USER, jjj whoami), because without it every agent shares one identity and work claims overwrite each other

Orienting instead of re-deriving

Starting every turn with jjj prime — one call for what to do, what is already proposed, what is already measured, and what is blocked on a person
jjj query as the single filter grammar across all five kinds, including waiting for work that is not ready yet
jjj contention for seeing where the fleet is piled up
Surviving context compaction

Evidence and argument

Investigations are findings, not solutions — and conjectures cite them
Writing the argument in the body rather than the title, with - reading stdin so long text survives shell quoting
jjj plan apply to create a whole graph in one call

Writing safely under concurrency

Guarding a write with --if-lamport, and treating exit 13 as “re-read and retry” rather than as a failure
What is enforced versus what is merely convention — notably that an open critique blocks approval as a matter of mechanism, not etiquette

Multi-agent patterns, each with a worked example: the claim loop (work distribution without a scheduler), rival conjectures, adversarial review, collision avoidance, distributed prioritization, and pods with parallel push.

It also documents the known failure modes and how to set the whole thing up in an agent harness.

Example Prompts

Once the skill is active, you can give natural-language instructions:

Create a critical problem for the login crash we just found,
propose a nil-guard solution, and link it to the current change.

Show me everything blocking the v1.0 milestone.

The rate-limiting critique on the auth solution is resolved —
address it and approve the solution with a rationale.

Search the event log for any decisions we made about caching.

Benchmark the search path, record what you measured as a finding,
then propose a solution that cites it.

What is blocked on me? Answer the escalations you can and clear them.

What the Agent Can Do

Task	What to say
Triage a bug	”Add a critical problem for X”
Start work	”Create a solution for problem Y and attach it to the current change”
Code review	”Add a high-severity critique about missing error handling to solution Z”
Check status	”What’s blocking progress right now?”
Roadmap	”Show the milestone roadmap as JSON”
Audit	”Search the event log for decisions about authentication”
Orient	”Run `jjj prime` and tell me what you’re picking up and why”
Record evidence	”Measure it, then file a finding with the method you used”
Plan a body of work	”Draft this as a jjj plan and apply it in one call”
Ask for help	”Escalate anything only I can unblock, then keep going”

Keeping the Skill Current

The skill file at jjj.recursivewhy.com/SKILL.md is updated with each release. Re-run the install command to get the latest version:

curl -fsSL https://jjj.recursivewhy.com/SKILL.md \
  -o ~/.claude/skills/jjj/SKILL.md