Commands

Add and remove

Command	Description
skul add <bundle>	Materialize a uniquely named cached bundle
skul add <source>	Fetch a source when needed and select one of its bundles
skul add <source> <bundle>	Fetch a source when needed and materialize a specific bundle
skul remove <bundle>	Remove one bundle and delete its managed files
skul reset	Remove all skul-managed files from the current worktree

Re-apply and inspect

Command	Description
skul apply	Re-materialize all desired bundles in the current worktree
skul list	List cached bundles
skul status	Show desired state and materialization status

Tracked root lifecycle

Command	Description
skul shadow --suspend	Restore tracked root instruction files back to HEAD and clear shadow state from the working tree
skul shadow --refresh	Rebuild tracked root-instruction shadows from the latest HEAD content plus bundle overlays
skul sync	Run the safe suspend / git pull --ff-only / refresh sequence in one command

Remote update flow

Command	Description
skul check [bundle]	Check remote-backed bundles for upstream updates
skul update [bundle]	Update remote-backed bundles to the latest upstream revision

skul add options

skul add [options] [source] [bundle]

Option	Description
-a, --agent <name>	Materialize for one tool only. Repeat to target multiple tools. Defaults to every tool the bundle ships content for.
--ref <selector>	Track a specific branch, tag, or commit instead of remote HEAD. Persisted in the registry and reused by skul apply.
--include <item>	Install only a specific bundle item. Repeat for multiple. Selectors: skills/<name>, commands/<name>, agents/<name>, root-instruction (AGENTS.md / CLAUDE.md also accepted).
--select-items	Open an interactive picker for bundle items. When combined with --include, the included items are preselected.
--all	Install every bundle from the source. Requires a source and cannot be combined with a bundle name.
-s, --ssh	Clone the source via SSH instead of HTTPS. git@host:owner/repo URLs are auto-detected as SSH. Protocol is persisted and reused by skul apply.
-g, --global	Install to global tool config under ~/ instead of the current worktree.
-y, --yes	Install without interactive confirmation prompts. Selects all available agents and auto-approves overwrite/replacement confirmations. Also available on remove, apply, update, and reset for confirmation prompts.
-n, --dry-run	Preview what would be written without making any changes.

Other flags

• Mutating commands accept --dry-run.
• skul add <source> --all installs every bundle from a source, and skul remove --all removes every active bundle.
• skul add, skul remove, skul apply, skul update, and skul reset accept -y, --yes to auto-approve overwrite/removal confirmations.
• skul list, skul status, and skul check accept --json.

Protocol behavior

Bare owner/repo references default to github.com/owner/repo. If you pass --ssh or use a git@host:owner/repo URL, skul persists that protocol choice and reuses it later during apply.

Root-instruction safety

Tracked root-instruction refresh refuses:

• staged changes
• unstaged edits
• unmerged files
• incompatible Git index flags
• manual edits to the current shadow render

Use skul status to inspect shadow health before running skul sync or skul shadow --refresh.