Setup Multirepo Git

Multi-Repo Git Workflow

This skill provides rules for working with multi-repo workspaces (multiple independent git repositories in one project directory) and a setup command for new projects.

Multi-Repo Git Rules

These rules apply whenever working in a project that has a .mgit.conf file in its root.

Always use mgit for service git operations

Rule: Use ./scripts/mgit for all git operations on service repositories. This wrapper runs git -C under the hood but puts the subcommand first and service last, enabling permission patterns to distinguish safe vs dangerous operations.

Use root or . as the service name for the root repo.

Never use cd && git ... (breaks auto-approval). Never run bare git add/status/commit expecting it to pick up service files — that targets the root repo.

# CORRECT — works from project root, auto-approvable for safe operations
./scripts/mgit status my-service --short
./scripts/mgit diff my-service
./scripts/mgit add my-service src/main/MyFile.scala
./scripts/mgit commit my-service -m "fix: something"
./scripts/mgit log my-service --oneline -5

# CORRECT — root repo operations
./scripts/mgit status root --short
./scripts/mgit diff .
./scripts/mgit add root AGENTS.md
./scripts/mgit commit . -m "docs: update agents"

# WRONG — requires manual approval (permission wildcards don't match mid-string)
git -C my-service status --short

# WRONG — changes directory, breaks auto-approval
cd my-service && git status --short

# WRONG — targets root repo, service folders are gitignored
git add my-service/src/main/MyFile.scala
git status  # only shows root repo changes

Which repo does a file belong to?

Check the first path component after the project root:

• If it matches a service name listed in .mgit.conf → use ./scripts/mgit
• If it's a root-level file (AGENTS.md, docs/, scripts/, etc.) → use ./scripts/mgit root (or .)

Multiple services in one session

When committing changes across multiple services, run separate mgit commands for each service. Each service gets its own commit.

Git best practices

• Staging: Never use git add -A. Add specific files instead.
• Commits: Keep commits small and focused. Use Conventional Commits style.
• Remote: Never git push or git pull automatically — ask first. git fetch is allowed.
• Resets: Do not git reset --hard or checkout the whole project.

Setup Instructions

When invoked as /setup-multirepo-git, set up a new multi-repo workspace:

Step 1: Discover services

Scan the project root for subdirectories that contain their own .git/ directory:

# Find subdirectories with their own git repos
for dir in */; do
  [ -d "$dir/.git" ] && echo "${dir%/}"
done

Present the discovered list to the user for confirmation. They may want to add or remove entries.

Step 2: Create .mgit.conf

Create a .mgit.conf file in the project root with the confirmed service list:

# Multi-repo workspace configuration
# Presence of this file marks the project root for mgit
services=service-a,service-b,service-c

Step 3: Symlink the mgit script

Ensure a scripts/ directory exists, then create the symlink:

mkdir -p scripts
SKILLS_DIR="${SKILLS_DIR:-${CODEX_HOME:-$HOME/.codex}/skills}"
if [[ ! -d "$SKILLS_DIR" ]]; then
  SKILLS_DIR="${CLAUDE_HOME:-$HOME/.claude}/skills"
fi
ln -sf "$SKILLS_DIR/setup-multirepo-git/scripts/mgit" scripts/mgit

Verify the symlink works:

./scripts/mgit status  --short
./scripts/mgit status root --short

Step 4: Output permission patterns

Read the permission template from the skill resources and output it for the user:

SKILLS_DIR="${SKILLS_DIR:-${CODEX_HOME:-$HOME/.codex}/skills}"
if [[ ! -d "$SKILLS_DIR" ]]; then
  SKILLS_DIR="${CLAUDE_HOME:-$HOME/.claude}/skills"
fi
cat "$SKILLS_DIR/setup-multirepo-git/templates/permissions.json"

Tell the user to merge these patterns into their agent-specific local settings file. The allow patterns enable auto-approval for safe read-only operations. The ask patterns require confirmation for dangerous operations.

Step 5: Output AGENTS.md block

Read the AGENTS template from the skill resources and output it:

SKILLS_DIR="${SKILLS_DIR:-${CODEX_HOME:-$HOME/.codex}/skills}"
if [[ ! -d "$SKILLS_DIR" ]]; then
  SKILLS_DIR="${CLAUDE_HOME:-$HOME/.claude}/skills"
fi
cat "$SKILLS_DIR/setup-multirepo-git/templates/AGENTS-MGIT.md"

Tell the user to include this block in their project's AGENTS.md file, customizing the service names and any project-specific details.

Step 6: Confirm setup

Verify everything works:

1. readlink scripts/mgit — should show the symlink target
2. ./scripts/mgit status — should show git status for a service
3. ./scripts/mgit status root — should show git status for the root repo
4. ./scripts/mgit status invalid-name — should error with valid service list

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: flurdy
• Source: flurdy/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.