From vcs-workflow-skill
Use whenever a new user request touches a version-controlled repository (`.jj` or `.git`). Classifies the request as continuation / scope-shift / new work, runs the matching jj or git command to set the change scope BEFORE editing, and on push targets the active branch/bookmark's own upstream — not `main` by default. Covers jj-colocated, pure-jj, and pure-git layouts.
How this skill is triggered — by the user, by Claude, or both
Slash command
/vcs-workflow-skill:vcs-workflowThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Per-prompt version-control discipline for AI coding agents. Use this skill at the **start of every new user request** that involves edits in a tracked repository — not at commit time.
Per-prompt version-control discipline for AI coding agents. Use this skill at the start of every new user request that involves edits in a tracked repository — not at commit time.
Portability note. On Claude Code this skill ships alongside a
UserPromptSubmithook that re-injects the same reminder on every turn (so the rule doesn't decay). On clients without a per-prompt hook (Cursor, Codex, Gemini, Windsurf, Cline, etc.), the skill is loaded once at session start — re-read this file at the top of each new user request to compensate.
From the project root, check filesystem only (no jj/git binary needed):
Has .jj | Has .git | Repo type | Dialect to use |
|---|---|---|---|
| ✓ | ✓ (at same root) | jj-colocated | jj commands; do not drive raw git |
| ✓ | ✗ | pure-jj | jj commands |
| ✗ | ✓ | pure-git | git commands |
| ✗ | ✗ | not tracked | skip — nothing to do |
When the layout is ambiguous (e.g. nested submodules, worktrees), ask the user.
jj st — note the active change's description and which bookmark sits nearest to @.git status and git branch --show-current — note the working tree state and current branch.Decide which bucket the user's request falls into before editing:
Continuation — same topic, refinement, or follow-up of in-progress work.
Scope shift — same change, but the goal has been refined or expanded.
jj describe -m "<refined summary>".New work — orthogonal topic or a different area.
jj new -m "<concise summary>" (descendant), or jj new @- -m "..." (sibling, if current work is unfinished).git switch -c <name> <base-branch> — so unrelated work doesn't pile onto the current branch.If unclear which bucket this prompt falls in, ask the user before editing.
main by default::@:
jj log -r 'heads(::@ & bookmarks())' -T 'bookmarks'
Advance it when ready (jj bookmark move <name> --to @) and push only it:
jj git push -b <name>
This goes to that bookmark's own upstream. Touch main only if main itself is the active bookmark.git push -u origin HEAD # first time, sets upstream
git push # subsequently
Don't commit to or push main unless main is the branch you're working on and the user asked. If the work belongs on a feature branch, create one first (git switch -c <name>).jj, not raw gitIn a jj-colocated repo, raw git writes (git commit, git checkout, git reset, git merge) can desync the jj working copy. Prefer the jj equivalent. If a raw git write is unavoidable (e.g. an external tool insists on it), follow it with:
jj git import
so the jj view reconverges with the git refs.
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub zelanton/claude-plugins --plugin vcs-workflow-skill