git-submodule — Claude Code skill for Git submodules
A skill that first asks whether a submodule is the right boundary, then walks you through one safe workflow. Useful when your project pulls in outside code through .gitmodules.
npx skills add akillness/jeo-skills --skill git-submodule -a claude-codeWhat git-submodule does
Each run picks a single mode: pinning an external repo at a commit, bootstrapping nested repos on a fresh clone, restoring a submodule to the commit the superproject records, moving it along a tracked branch, editing inside it, taking it out, or wiring checkout in CI. Before any command appears, the skill sorts the request into fields — goal, submodule state, CI and auth context — and states its safest assumption when something is missing.
Reference files back this up: a decision matrix, a separate note on updates and detached HEAD, guidance for CI and automation, and command packets per mode with hosted-platform limits. The toolset is Bash, Read, Write, Edit, Glob, Grep, so it inspects the repo and answers with concrete steps instead of a general Git lecture.
Rebases, conflict recovery and history repair belong to git-workflow; shipping a dependency as a registry package is another skill. A submodule points at a commit, never at a branch, so git submodule update can drop you into detached HEAD — the skill flags that before you commit anything.
What it helps with
- judge whether an external dependency belongs in a submodule or a subtree
- attach someone else's repo and pin it to a commit
- clone a project whose submodules are still empty
- restore a submodule to the commit recorded upstream
- fetch submodules during CI, private ones included
Example prompts for the agent
- Add this external repo as a submodule and pin the current commit
- I cloned the project and the submodules are empty — initialize them recursively
- The submodule is in detached HEAD, put it back on the recorded commit
How to install git-submodule
1Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill git-submodule -a claude-code2Manually: put the files in place
~/.claude/skills/git-submodule/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/git-submodule/
1Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill git-submodule -a codex2Manually: put the files in place
.agents/skills/git-submodule/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill git-submodule -a cursor2Manually: put the files in place
.cursor/skills/git-submodule/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install akillness/jeo-skills git-submodule2Manually: put the files in place
.github/skills/git-submodule/SKILL.md1Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill git-submodule -a gemini-cli2Platform CLI
gemini skills install https://github.com/akillness/jeo-skills --path .agent-skills/git-submoduleManually: put the files in place
.devin/skills/git-submodule/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill git-submodule -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about git-submodule
How do I install git-submodule in Claude Code?
Run npx skills add akillness/jeo-skills --skill git-submodule -a claude-code. The skill file lands at ~/.claude/skills/git-submodule/SKILL.md.
What does git-submodule do?
It narrows a submodule problem to one mode — adding and pinning, bootstrapping, syncing a pointer, CI checkout — and returns commands for that mode only.
How is it different from git-workflow?
git-workflow covers local branches, rebasing and history repair. This one deals with the repo boundary: choosing a submodule, initializing it, updating the pointer, detached HEAD and CI behaviour.
