Git Agent Skills

Evidence-driven Git workflow skills for AI coding agents. Skills are organized by desired postcondition, not individual Git commands.

Install

npx skills add hypercube-xyz/git-agent-skills

Install one skill when the installer supports selection:

npx skills add hypercube-xyz/git-agent-skills --skill craft-commits

Design goals

• Route from user symptoms and outcomes, including non-technical phrasing.
• Inspect current state before selecting a command.
• Preserve unrelated work and prevent silent semantic escalation.
• Apply controls per reachable path: read-only, local mutation, shared/external, and critical impact.
• Keep SKILL.md focused; load conditional detail from direct references.
• Verify intended effects, incidental bounds, protected state, and remote results where applicable.

See docs/SECURITY-EXECUTION.md for the common untrusted-content, executable-Git, retry, recovery-artifact, and runtime-enforcement contract.

Skill groups

Groups organize documentation and evaluation priority. Installers expose all skills unless they support explicit selection.

Core

Skill	Scope
diagnose-repository	Classify confusing Git state without mutation and route to the owning workflow.
configure-git	Own Git configuration, identity, signing, attributes, hooks, and helper selection.
craft-commits	Turn reviewed local changes into coherent atomic commits.
sync-branches	Reconcile and publish one local/remote branch relationship.
integrate-branches	Integrate one complete line, including subtree/vendor synchronization.
manage-worktrees	Own linked-worktree lifecycle and branch occupancy safety.
resolve-conflicts	Resolve semantic conflicts after a Git operation has stopped.
undo-changes	Reverse a known change or abort known operation state.
recover-lost-work	Restore intact but unreachable/deleted work additively.
repair-repository-integrity	Repair damaged/missing Git objects, packs, refs, alternates, or clone completeness.
edit-commit-history	Rewrite one existing commit series in place.
find-regression	Locate a behavioral transition with a validated bisect oracle.
manage-submodules	Own .gitmodules, gitlinks, and nested repository relationships.
manage-large-files	Own LFS pointer/object relationships and large-object policy.
manage-tags	Own tag object/ref lifecycle and verification.
migrate-repository	Transfer a complete repository and coordinated migration state.

Compact / optional

Skill	Scope
setup-repository	Create or clone a repository with the intended topology and completeness policy.
manage-remotes	Own remote identity, URLs, refspecs, and fork/upstream topology.
manage-branches	Own local branch lifecycle and metadata without integration.
preserve-work	Create a verified temporary rescue artifact from current uncommitted work.
transplant-commits	Replay selected commits or reviewed patch/mailbox series.
investigate-history	Explain provenance and historical change without mutation.
optimize-large-repository	Measure and tune a healthy large repository.
manage-stacked-branches	Restack and coordinate publication of dependent review branches.

Boundaries and references

General code review, secret detection, release preparation, hosting-provider administration, and deployment are outside this package. Multi-step Git know-how is kept in the direct references of the skill that owns the consequential decision, so installed agents can discover it without an umbrella workflow skill.

See docs/SKILL-CATALOG.md for routing boundaries, docs/COMPATIBILITY.md for supported environments, and docs/DESIGN-RATIONALE.md for the package design. Consequence-boundary handoff fields are stated directly in the relevant skills so they remain available when a skill is installed independently.

Development

python3 scripts/validate_skills.py
python3 scripts/security_regression.py
python3 scripts/smoke_test_git.py
python3 scripts/build_release.py --check

Link all packaged skills for local development:

python3 scripts/link_skills.py --dry-run
python3 scripts/link_skills.py

The release builder is a pure packager: it reads immutable committed blobs via git ls-tree and git cat-file, does not read working-tree file content as package input, and does not run validators. CI validates the checked-out revision before calling the builder. Each release output (ZIP, checksum, metadata) is written atomically per file; abrupt termination may leave a partial output set — rerunning the deterministic builder reconciles it.

Compatibility

• Skills and installation: Linux, macOS, Windows (Python 3.14, Git 2.35+)
• Release publishing: Linux CI only; artifact is a platform-neutral ZIP
• No OS/process sandbox is provided by this repository
• Concurrent local attacker with write access to the output parent directory is not defended against (known TOCTOU limitation)
• Hard-killed processes may leave process-local directories in the OS temp prefix and installer staging or backup directories beside the target

License

MIT