Syncing AGENTS.md and Claude Skills Across Git Worktrees and Submodules

Why Do Git Worktrees and Submodules Break AGENTS.md and Claude Skills?

Git worktrees and submodules break AGENTS.md and Claude skills because modern AI coding assistants resolve configuration files relative to the current working directory tree rather than shared developer state. When you branch off your repository to create an isolated worktree checkout, untracked agent instructions, local skill definitions in .claude/skills, and submodule pointers remain isolated within their original branch history. Consequently, an AI agent launched in a newly created worktree cannot access the prompts and guidelines you honed in other checkouts.

Git introduced linked working trees in version 2.5 (July 2015) to help developers manage multiple checkouts from a single repository without cloning duplicate objects. According to the official Git Worktree documentation:

"A git repository can support multiple working trees, allowing you to check out more than one branch at a time. With git worktree add a new working tree is associated with the repository, along with additional metadata..."

While this architecture is optimal for isolating compiler artifacts, local test runners, and node dependencies, it introduces three major architectural failure modes for AI agent configurations:

1. The Gitdir Text File Pointer Trap

In a primary repository checkout, the project root contains a physical .git/ directory housing hooks, configuration objects, and refs. However, when you invoke git worktree add ../feature-worktree feature-branch, Git creates a secondary directory where .git is not a directory at all. Instead, it is an ASCII text file containing a single line:

gitdir: /Users/developer/Projects/core-service/.git/worktrees/feature-worktree

Many developers attempt to share instructions across directories by creating relative symlinks (for example, linking .claude/skills or AGENTS.md to ../../shared-config/). Because the linked worktree directory lives at an entirely different filesystem depth or parallel path, relative traversals break immediately. Scripts expecting a physical .git/hooks/ directory fail to execute, leaving automated linting, test rubrics, and agent triggers unattached.

2. Branch-Isolated Commit Drift and Merge Collisions

When instruction files like AGENTS.md or .claude/skills/code-review/SKILL.md are checked directly into Git version control, they become immutable records of that branch commit. If an engineer optimizes a complex PostgreSQL migration skill on feature/user-auth, that refinement exists only inside that branch commit.

When switching to a hotfix worktree or checking out an older release branch, the AI agent reverts to whatever stale instructions existed when that branch was created—or finds no instruction file at all. Furthermore, when multiple engineers update prompt guidelines on 15+ concurrent branches in an enterprise monorepo, merging feature branches produces frequent merge conflicts in markdown instruction files.

3. Submodule Detached HEAD Desynchronization

Some engineering teams attempt to distribute shared agent rules by mounting a central repository as a Git submodule (e.g. .agent-rules). As documented in the official Git Submodule documentation:

"Submodules allow you to keep a Git repository as a subdirectory of another Git repository. The other repository is referred to as a superproject..."

While submodules sound elegant in theory, they create severe operational friction in practice. Secondary worktrees do not initialize submodules automatically; running git worktree add leaves the submodule directory empty until you manually run git submodule update --init --recursive. Furthermore, submodule checkouts operate in a detached HEAD state. If a developer edits a skill file inside a submodule and commits code, those changes are lost unless they create an explicit branch, push upstream, and commit the new commit hash in the parent repository.

The Sprawl Moment: The Hotfix Worktree That Silently Lost Your Agent Rules

It is 4:45 PM on a Friday, and a high-priority production regression surfaces in payment processing. You are deep in the middle of a complex refactor on your primary checkout with hundreds of uncommitted lines. Rather than stashing your work and risking unstash collisions, you do the right thing: you create a fresh Git worktree (git worktree add ../hotfix-payments hotfix/payment-gateway) and open your terminal. You launch your coding agent and ask it to diagnose the database deadlock and produce a patch.

Instead of following your team's strict transactional safety guidelines and Zod schema validations—which you spent weeks tuning in AGENTS.md and your local Claude skills—the agent proposes a raw, unparameterized SQL query that drops table locks and bypasses telemetry. You stare in disbelief. Your perfected instructions did not carry over to the new worktree. They were trapped inside the git history and local folder state of your main checkout, leaving you to manually rebuild prompts under production pressure while error rates spike.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

By managing your agent skills in a centralized cloud library that syncs directly into global filesystem locations on macOS, you ensure that every worktree, terminal session, and IDE instance shares the exact same verified instructions without touching Git branch state.

How Do Coding Agents Resolve Instructions in Linked Worktrees?

Coding agents resolve instructions in linked worktrees by traversing the directory tree upward from the current working directory until encountering the worktree boundary, and then merging local findings with global user directories. However, each agent framework implements distinct resolution hierarchies, filesystem scopes, and caching behaviors.

The following matrix illustrates how the primary AI coding agents resolve repository instructions and global skills across Git worktrees:

As highlighted in the official Anthropic Claude Code documentation:

"Claude Code reads instructions from CLAUDE.md in your project directory, but also merges personal user skills stored in ~/.claude/skills. This multi-tier hierarchy allows individual preferences to travel across all local workspaces."

Understanding this hierarchy is critical: while in-repo files like CLAUDE.md and AGENTS.md are branch-dependent, global user directories remain invariant across checkouts. For deeper comparisons across instruction schemas, explore our analysis of Codex skills vs Claude Code skills and our architectural guide on agent instructions across repos and worktrees.

3 Methods to Sync AGENTS.md and Claude Skills Across Worktrees

The 3 primary methods for synchronizing AGENTS.md and Claude skills across Git worktrees are: automating post-checkout Git hooks, maintaining pinned submodule repositories, and deploying an external cloud skill manager. Each method represents a distinct balance between manual operational overhead and automated cross-tool reliability.

Method 1: Automated Post-Checkout and Post-Merge Git Hooks

For teams committed to in-repo Git versioning, you can automate instruction parity by installing an automated post-checkout Git hook in your core repository. Whenever you create a new worktree or switch branches, the hook automatically links your canonical AGENTS.md and .claude/skills/ directory into the active worktree root.

Because Git 2.5 stores worktree metadata inside .git/worktrees/<worktree-name>/, you can place a universal hook inside the parent repository's .git/hooks/post-checkout. When executed, the hook runs in under 25 milliseconds, verifying that instructions exist without slowing down branch switching:

#!/usr/bin/env bash
# .git/hooks/post-checkout: Auto-link AGENTS.md & skills into new Git worktrees
set -euo pipefail

# Only execute on branch/worktree checkouts (flag 1)
CHECKOUT_TYPE="${3:-0}"
if [[ "$CHECKOUT_TYPE" -ne 1 ]]; then
    exit 0
fi

# Detect whether we are in a secondary linked worktree
GIT_DIR="$(git rev-parse --git-dir)"
COMMON_DIR="$(git rev-parse --git-common-dir)"

if [[ "$GIT_DIR" != "$COMMON_DIR" ]]; then
    MAIN_WORKTREE="$(dirname "$COMMON_DIR")"
    CURRENT_WORKTREE="$(pwd)"

    # Link canonical AGENTS.md if missing in current worktree
    if [[ -f "$MAIN_WORKTREE/AGENTS.md" ]] && [[ ! -e "$CURRENT_WORKTREE/AGENTS.md" ]]; then
        ln -sf "$MAIN_WORKTREE/AGENTS.md" "$CURRENT_WORKTREE/AGENTS.md"
        echo "[git-hook] Linked canonical AGENTS.md into worktree"
    fi

    # Link canonical .claude/skills directory if missing
    if [[ -d "$MAIN_WORKTREE/.claude/skills" ]] && [[ ! -e "$CURRENT_WORKTREE/.claude/skills" ]]; then
        mkdir -p "$CURRENT_WORKTREE/.claude"
        ln -sfn "$MAIN_WORKTREE/.claude/skills" "$CURRENT_WORKTREE/.claude/skills"
        echo "[git-hook] Linked canonical .claude/skills into worktree"
    fi
fi

While this hook prevents empty checkouts, it has limitations: it requires every developer to configure their local .git/hooks/ (Git does not clone hooks for security reasons), and symlinks can cause changes in one worktree to bleed unexpectedly into active branch states.

Method 2: Shared Submodule Repositories with Pinned Pointers

Large organizations managing 50+ microservice repositories often centralize agent prompts into an internal ai-agent-standards repository and mount it as a submodule in each superproject:

# Mount shared agent standards repository as a submodule
git submodule add git@github.com:org/ai-agent-standards.git .agent-rules

# Direct Codex and Claude to parse the mounted standards
echo "Include instructions from .agent-rules/AGENTS.md" >> AGENTS.md

While submodules ensure cryptographic commit pinning and strict CI/CD audit trails, they introduce operational drag across daily development. When creating a secondary worktree, developers must remember to run:

git worktree add ../feature-branch feature-branch
cd ../feature-branch
git submodule update --init --recursive

If developers forget the submodule initialization step, the .agent-rules folder remains completely empty. Submodules also suffer from detached HEAD states, meaning local prompt optimizations cannot be committed directly without navigating sub-repos and creating intermediate feature branches.

Method 3: Centralized Global Skill Management via Prompttly

The most robust, zero-friction architecture decouples prompt and skill management entirely from the Git commit graph. Instead of managing fragile worktree symlinks or detached submodule pointers, Prompttly synchronizes your prompt and skill library directly to the native global directories expected by AI agents:

• Universal Filesystem Mirroring: Prompttly automatically writes your skills to ~/.claude/skills/ for Claude Code and synchronizes runbook directives to ~/.codex/skills/ and AGENTS.md descriptors.
• Zero Branch Pollution: Because skills live in your user home directory, creating, switching, or deleting Git worktrees has zero impact on your agent's capabilities. Your AI assistant executes the exact same verified instructions across main, hotfix, and experimental branches.
• Sub-200ms Mac Hotkey Palette: Press a global keyboard shortcut anywhere on macOS to open your complete library and insert parameterized skills into Cursor, Xcode, Ghostty, or browser chats with sub-180ms latency.
• Two-Way Synchronization: If you edit a skill markdown file in your terminal, Prompttly detects the file modification and synchronizes it back to your cloud library instantly.

For teams coordinating multiple environments, explore our guide on how to sync Cursor rules across machines without git conflicts and our guide to building an automated MCP skill sync pipeline.

Should Agent Instructions Live in Git Version Control or a Global Library?

Agent instructions should live in Git version control when they define rigid, non-negotiable repository invariants, and live in a global skill library when they govern personal developer productivity workflows. Combining both scopes creates an optimal separation of concerns: team constraints stay versioned in the repo, while personal prompts follow the developer everywhere.

Step-by-Step: Setting Up an Automated Worktree Sync Hook

Setting up an automated worktree sync hook requires establishing a centralized templates directory, creating a post-checkout hook script, and verifying symlink resolution across newly spawned worktrees. Follow these step-by-step instructions to configure automated parity:

1. Step 1: Create a Centralized Instructions Directory

   In your primary repository checkout, ensure your canonical AGENTS.md and .claude/skills/ folders are organized in the project root:

   cd ~/Projects/core-api
   touch AGENTS.md
   mkdir -p .claude/skills/migration-check

2. Step 2: Install the Git Post-Checkout Hook

   Write the automated worktree resolution script into .git/hooks/post-checkout and mark it executable:

   cat << 'EOF' > .git/hooks/post-checkout
   #!/usr/bin/env bash
   COMMON_DIR="$(git rev-parse --git-common-dir 2>/dev/null || echo "")"
   GIT_DIR="$(git rev-parse --git-dir 2>/dev/null || echo "")"
   
   if [[ -n "$COMMON_DIR" ]] && [[ "$GIT_DIR" != "$COMMON_DIR" ]]; then
       MAIN_ROOT="$(dirname "$COMMON_DIR")"
       if [[ -f "$MAIN_ROOT/AGENTS.md" ]] && [[ ! -e "./AGENTS.md" ]]; then
           ln -sf "$MAIN_ROOT/AGENTS.md" ./AGENTS.md
       fi
   fi
   EOF
   chmod +x .git/hooks/post-checkout

3. Step 3: Spawn a Secondary Worktree and Verify Parity

   Add a new worktree checkout and confirm that AGENTS.md is automatically symlinked without manual intervention:

   # Spawn secondary worktree in a parallel directory
   git worktree add ../hotfix-worktree -b hotfix/critical-patch
   cd ../hotfix-worktree
   
   # Verify that the AGENTS.md link resolves cleanly
   ls -la AGENTS.md
   # Output: AGENTS.md -> /Users/developer/Projects/core-api/AGENTS.md

Streamlining AI Agent Workflows Across All Repositories

As software development shifts toward multi-agent automation across Cursor, Claude Code, OpenAI Codex, and Google Antigravity, instruction sprawl becomes the primary bottleneck to developer velocity. Forcing developers to manage detached submodules or fight broken relative symlinks across Git worktrees wastes hours of engineering focus.

By combining clear in-repo architectural guidelines with a centralized, hotkey-accessible skill manager, you ensure your AI assistants operate at peak accuracy in every checkout, worktree, and repository. You can generate standardized, schema-compliant skill definitions using our free Claude Skill Creator tool or test your prompt boundaries with the Custom Instructions Generator.

For additional developer guides, skill sync tutorials, and prompt architectures, visit the Prompttly resources hub.