# Managing Global Claude Code Agents Across Multiple Projects: Best Practices

> Master managing global Claude code agents across projects. Discover best practices for efficient cross-project utilities, naming conventions, and updates with davila7/claude-code-templates.

- Repository: [Daniel Avila/claude-code-templates](https://github.com/davila7/claude-code-templates)
- Tags: best-practices
- Published: 2026-04-26

---

**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`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/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:

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

```

The SDK executes the following operations (starting at line 31 in [`global-agent-manager.js`](https://github.com/davila7/claude-code-templates/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash

# 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

```bash

# 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

```bash

# 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

```bash

# 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`](https://github.com/davila7/claude-code-templates/blob/main/cli-tool/docs_to_claude/SUB_AGENTS.md)
- **Verify PATH**: The SDK in [`cli-tool/src/sdk/global-agent-manager.js`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/global-agent-manager.js)) auto-detects the current project type by checking for [`package.json`](https://github.com/davila7/claude-code-templates/blob/main/package.json) (Node), [`requirements.txt`](https://github.com/davila7/claude-code-templates/blob/main/requirements.txt) or [`pyproject.toml`](https://github.com/davila7/claude-code-templates/blob/main/pyproject.toml) (Python), [`Cargo.toml`](https://github.com/davila7/claude-code-templates/blob/main/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.