Managing Global Claude Code Agents Across Multiple Projects: Best Practices

Global agents in Claude Code should be installed for cross-project utilities while tightly-coupled agents remain project-level, with strict naming conventions and regular updates to prevent stale scripts.

The davila7/claude-code-templates repository provides a JavaScript SDK that extends Claude Code with AI-driven agents—Markdown-defined tools that can be installed globally to work across any directory. When you need consistent linting, security auditing, or code generation capabilities in many unrelated repositories, managing global agents across multiple projects prevents duplication and ensures version consistency.

Architecture of the Global Agent System

The global agent manager is implemented in cli-tool/src/sdk/global-agent-manager.js and handles the complete lifecycle of portable agents.

Core Components

Component	Location	Function
Global Agent Manager	cli-tool/src/sdk/global-agent-manager.js (line 31)	Creates, lists, updates, and removes agents
Agent Definition	~/.claude-code-templates/agents/	Stores Markdown files with YAML front-matter containing system prompts
Executable Wrapper	Generated at runtime	Node.js scripts placed in BIN_DIR that invoke the Claude CLI
CLI Interface	cli-tool/bin/create-claude-config.js (line 77)	Parses --create-agent, --list-agents, and other flags

The SDK dynamically selects the installation directory based on filesystem permissions. It attempts to write to /usr/local/bin first, falling back to ~/.claude-code-templates/bin if the system directory is not writable (lines 25-27 of the manager).

Storage Precedence Rules

According to the Sub-agents guide documented in cli-tool/docs_to_claude/SUB_AGENTS.md (line 76), agent resolution follows a shadow hierarchy:

• Project-level agents located in .claude/agents/ inside a repository take precedence
• Global agents stored in ~/.claude/agents/ (or the configured AGENTS_DIR) are secondary
• Built-in agents provided by Claude Code serve as the final fallback

Global Agent Lifecycle

Creating Global Agents

To install an agent from the repository registry, use the --create-agent flag:

npx claude-code-templates@latest --create-agent security/audit

The SDK executes the following operations (starting at line 31 in global-agent-manager.js):

1. Determines the target BIN_DIR based on write permissions
2. Downloads the Markdown definition via findAgentUrl() (lines 536-576)
3. Writes the file to AGENTS_DIR (~/.claude-code-templates/agents/)
4. Generates an executable Node wrapper via generateExecutableScript() (lines 44-53)

The generated wrapper includes logic (lines 33-68) that auto-detects your project type—Node, Python, Rust, or Go—and injects a project-context block into the prompt.

Using Agents Anywhere

Once the bin directory is on your PATH (added automatically for user-level installations), invoke agents from any working directory:

code-reviewer "analyze authentication logic for vulnerabilities"

The wrapper strips the YAML front-matter from the Markdown definition, combines your input with auto-detected project context, and executes the Claude CLI with the agent's system prompt.

Listing Installed Agents

Verify your installation and check which agents are system-wide versus user-specific:

npx claude-code-templates@latest --list-agents

This command scans both system and user bin directories, de-duplicates entries, and marks each with 🌍 system or 👤 user indicators (lines 13-28 of listGlobalAgents).

Updating Global Agents

Synchronize agents with the latest repository definitions:

npx claude-code-templates@latest --update-agent audit

The updateGlobalAgent function (lines 20-35) re-downloads the Markdown file and regenerates the executable script, ensuring you receive prompt improvements and bug fixes.

Removing Agents

Clean up unused agents to prevent PATH pollution:

npx claude-code-templates@latest --remove-agent audit

The removal routine (lines 73-100 of removeGlobalAgent) deletes the executable from both potential bin locations (/usr/local/bin and the user bin) and removes the Markdown definition from AGENTS_DIR.

Best Practices for Cross-Project Agent Management

Choose the Right Scope

• Prefer project-level agents stored in .claude/agents/ when the tool is tightly coupled to specific codebase conventions (e.g., a custom linter for your company's API patterns)
• Use global agents for universal utilities like security audits, general code reviewers, or language-agnostic templates that operate consistently across repositories

Naming and Collision Avoidance

Keep agent names short, descriptive, and unique to avoid confusion with built-in agents or project-level overrides. While the manager gives precedence to project-level agents, name collisions can create unexpected shadowing behavior.

PATH Verification

Run --list-agents immediately after installation to verify the bin directory is accessible. If the SDK used the fallback user bin (~/.claude-code-templates/bin), it prompts you to source your shell profile (lines 94-99) to update PATH.

Maintenance Routine

• Update regularly: Run --update-agent monthly to incorporate upstream improvements
• Remove stale agents: Delete obsolete tools to prevent accidental execution of outdated scripts
• Test after creation: Execute the agent with a trivial prompt like "ping" to verify the Claude CLI integration and Markdown file accessibility

Version Control Strategy

Commit project-level agents to your repository (git add .claude/agents/*) to share team-specific tools. Treat global agents as disposable user-specific utilities that can be reconstructed from the source repository at any time.

Practical Code Examples

Installing a Cross-Project Security Agent

# Install globally for use in any repository

npx claude-code-templates@latest --create-agent security/audit

# Verify installation

npx claude-code-templates@latest --list-agents

Invoking Agents with Context

# From inside a Python project - the wrapper auto-detects the context

audit "check for SQL injection vulnerabilities in database models"

Creating a Custom Global Agent

# 1. Create your agent definition

cat > ~/my-custom-agent.md <<'EOF'
---
name: commit-helper
description: "Generates conventional commit messages"
tools: git
---
You analyze git diffs and write conventional commit messages...
EOF

# 2. Install globally (the SDK accepts local paths)

npx claude-code-templates@latest --create-agent ~/my-custom-agent.md

# 3. Use anywhere

commit-helper "write a message for these changes"

Periodic Maintenance

# Update all outdated agents

npx claude-code-templates@latest --list-agents | grep -v "✅" | while read name; do
  npx claude-code-templates@latest --update-agent $name
done

# Remove unused agents

npx claude-code-templates@latest --remove-agent old-linter

Summary

• Scope correctly: Use global agents in ~/.claude-code-templates/agents/ for cross-project utilities, but keep coupled tools in project-level .claude/agents/ directories
• Understand precedence: Project agents shadow global agents with identical names, as documented in cli-tool/docs_to_claude/SUB_AGENTS.md
• Verify PATH: The SDK in cli-tool/src/sdk/global-agent-manager.js installs to /usr/local/bin when possible, otherwise ~/.claude-code-templates/bin
• Maintain regularly: Use --update-agent and --remove-agent to prevent stale scripts and outdated prompts
• Leverage auto-context: The executable wrapper generated by generateExecutableScript() automatically detects Node, Python, Rust, or Go projects to enrich prompts

Frequently Asked Questions

How do I know if an agent is installed globally or locally?

Run npx claude-code-templates@latest --list-agents. The output explicitly marks each agent as 🌍 system or 👤 user, and the underlying logic in listGlobalAgents (lines 13-28) scans both directories while de-duplicating entries to show you the effective installation location.

Can I override a global agent with project-specific behavior?

Yes. Place an agent with the same filename in your project's .claude/agents/ directory. According to the precedence rules documented in cli-tool/docs_to_claude/SUB_AGENTS.md (line 76), project-level agents automatically shadow global agents, allowing repository-specific customizations while keeping the base utility available elsewhere.

Why can't I run my newly installed global agent?

The executable likely is not in your PATH. If the SDK lacked permissions to write to /usr/local/bin, it installed to ~/.claude-code-templates/bin and prompted you to source your shell profile (lines 94-99 of the manager). Run --list-agents to verify; if the agent appears but is not executable, reload your shell configuration with source ~/.bashrc or source ~/.zshrc.

How do custom global agents handle different programming languages?

The generateExecutableScript() function (lines 33-68 of global-agent-manager.js) auto-detects the current project type by checking for package.json (Node), requirements.txt or pyproject.toml (Python), Cargo.toml (Rust), or go.mod (Go). It injects a project-context block into the prompt, informing the model about the specific technology stack without requiring manual flags.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}