How it stays out of Git
Skul never touches .gitignore, your history, or your index for files it creates. Three pieces make that work.
The cache and the registry
| Path | Holds |
|---|---|
~/.skul/library/ | Cloned bundle sources, reused by every project |
~/.skul/registry.json | What each repo wants, and what was written in each worktree |
Wanted and written are tracked separately. A new linked worktree inherits the wanted state immediately; skul apply writes it.
Exclude, not ignore
Files Skul creates are listed in .git/info/exclude — local to your clone, never committed or pushed. Remove the bundle and the entries go with it.
Skul also fingerprints everything it writes. If you edit a managed file, removal asks first (or fails under SKUL_NO_TUI=1) instead of silently destroying your change.
Root instructions
AGENTS.md, CLAUDE.md, and QWEN.md are the hard case: your team may already commit them.
Your layer stays local, with three costs:
- Pull with
skul sync, and wrap other Git commands that moveHEADinskul shadow --suspendand--refresh. - Don't edit the file by hand while Skul manages it.
- Only one bundle can own a tracked file's shadow at a time.
Not tracked
Skul writes the file like any other and hides it. A file that already existed locally is kept as the base, with bundle content appended inside SKUL:BUNDLE markers. Several bundles can share one file; when the last one leaves, your original comes back.
Use --root-instruction-mode replace to discard the base instead of appending to it (it's still restored on remove).
Tracked: the shadow
If Git already tracks the file, Skul can't hide a diff with an exclude rule. Instead it renders HEAD plus your overlay into the working file and sets skip-worktree. git status stays clean; skul status lists it under Shadowed Instructions.
A tracked file has one shadow owner at a time, and Skul treats the rendered file as generated output. Don't edit it by hand — later commands refuse to overwrite a file that no longer matches what Skul wrote.
Pulling upstream changes
skip-worktree hides upstream changes too, so shadows need a pause around anything that moves HEAD:
skul sync
That's git pull --ff-only wrapped in suspend and refresh. If the pull fails, shadows are restored first. If upstream stops tracking the file, the shadow is retired.
For other Git commands, do the same by hand:
skul shadow --suspend
git rebase origin/main
skul shadow --refresh
Skul refuses to create or refresh a shadow while the file has staged, unstaged, or unmerged changes.
Cleaning up
skul reset
Removes everything Skul manages in this worktree, restores shadowed files from HEAD, and restores preserved local bases. Run it before git worktree remove; otherwise the registry keeps a record of a clone that no longer exists.