Project × Global | Subagents

You already know how to create an agent. Now the question is: where it lives? Claude Code reads agents from two different locations — the folder for the project (goes into git, shared with the team) and the folder global (yours alone, available in any project, never uploaded to the repository). The same logic applies to skills, hooks, and MCP servers: each has its own pair of scopes.

↑ Project: .claude/agents/ in the repo (it goes into Git). Global: ~/.claude/agents/ in the home directory (doesn’t go up).

Detailed content

📁 `.claude/agents/` in the repository

When you create a file .claude/agents/meu-agente.md within the project's repository, this agent belongs to that project. Anyone who clones the repo and opens Claude Code will see the same agent available — no setup required.

🔀 The agent goes along with the code

O .claude/agents/ lives inside the repository. This means:

•git add + git push — the agent ships with the code.
•git clone — the next developer finds it in the right place.
•Pull Requests — changes to the agent are reviewed like regular code.
•History — you can see exactly when and why the description changed.

What it is:

Folder .claude/agents/ within the repository—agents tracked by git, visible to all project collaborators.

Why learn:

It’s the right way to distribute agents across the team. Without it, each developer has to manually configure the same agents on their machine — making inconsistencies more likely.

Key concepts:

Project scope · agent version control · traceability · automatic onboarding.

📁

In the repo

within the project

🔀

Version-controlled

tracked by git

👥

Shared

the whole team uses

📝

Reviewable

via PR/code review

🏠 `~/.claude/agents/` — global scope

The folder ~/.claude/agents/ lives in your home directory — outside any repository. Agents placed there are available in all your projects, on any machine you’re logged into, but never get pushed to git.

✅ Good candidates for global scope

→Agent with your code style preferences
→Tools you use in all projects (e.g., security-auditor)
→Agents that contain sensitive information (tokens, internal endpoints)
→Personal workflows that don’t make sense for the team

❌ What should NOT stay global

→Agents specific to a single project (the team won’t find them)
→Agents that the team should audit and version
→Anything that needs to exist in CI/CD (the server doesn’t have your home directory)
→Agents with project domain context (architecture, business rules)

What it is:

Folder ~/.claude/agents/ in the user’s home directory — outside any repo, invisible to git, available in every project you open.

Why learn:

Prevents personal or sensitive tools from being accidentally committed. Creates a "personal drawer" of reusable agents without cluttering the repository.

Key concepts:

Global scope · home directory · invisible to git · multi-project · personal tools.

🔀 Sharing with the team via git

Agents in the .claude/agents/ from the repo are first-class citizens from the project. They take part in the same code review workflow as code: no one changes an agent's description without the team knowing.

Create the `.md` in the project folder

New agent → new responsibility for the team.

Put in meu-repo/.claude/agents/code-reviewer.md. The folder .claude/ already exists if you use CLAUDE.md or settings.json.

Commit and open a PR

The agent goes into version control.

The diff from .md appears in the PR like any code change. The description, allowed tools, and system prompt can be reviewed line by line.

The team clones it and already has everything

Zero manual setup for new developers.

Any contributor who clones the repository finds the agents ready to use. Tool onboarding is automatic—the same as with CLAUDE.md.

💡 Tip: add to the `.gitignore` the private agents

If you have project agents that must not leave (e.g., access to internal staging), add them to the .gitignore with the pattern .claude/agents/privado-*.md. That way, they stay in the local repo but are never committed.

What it is: agents as versioned artifacts — created, modified, and reviewed through the same workflow as the project's code.

Why learn: ensures everyone uses the same version of the agent and that dangerous changes (e.g., giving the agent access to Bash) go through review.

Key concepts: git as the source of truth · agent PR review · automatic onboarding · .gitignore selective.

🔒 Just you — the personal scope

The global scope (~/.claude/agents/) é your private collection. It’s not in any repo—it never appears in the git status, never gets pushed to GitHub, and is never seen by your colleague. This is where the tools you built for yourself live.

🧰 Your portable toolbox

Think of global as the the carpenter's toolbox: you bring it to every job site, but it's yours. The contractor on the next project doesn't know which tools you bring.

🏠 Always available

You open any project and the global agent is there. No need to copy or reinstall it.

🔐 Private by default

Never appears in the git status. Agents with sensitive data stay safe here.

⚙️ Your preferences

Code style, response language, personal workflows—nothing imposed on the team.

🚫 Doesn’t exist in CI/CD

CI servers don't have your home directory. Agents critical to pipelines should live in the repo.

What it is: the personal, portable collection of agents — available across all projects, but invisible to git and the team.

Why learn: without the global scope, you’d be forced to commit personal tools to every repo—cluttering the history and exposing private settings.

Key concepts: home directory · portability · privacy · not available in CI · personal preferences.

🚚 Move an agent = move the `.md`

Need to promote a personal agent to the team project? Or make a repo agent private? The process is exactly what it seems: move the file .md from one folder to another. There is no "linking" or "registering" — the scope is determined by the file path.

⌨️ The two moves

global → project (promote to the team)

mv ~/.claude/agents/meu-agente.md \
   meu-projeto/.claude/agents/meu-agente.md

project → global (make private)

mv meu-projeto/.claude/agents/meu-agente.md \
   ~/.claude/agents/meu-agente.md

📊 Why is it so simple?

Claude Code doesn’t have an agent database — it simply reads all the .md from both folders at startup. The agent's “registry” is the file's presence. Move it = change the scope immediately in the next session.

What it is: scope defined by the file path — changing the scope means moving the .md, with no additional configuration.

Why learn: demystifies the process: there is no "installation" or "import"—the agent simply exists where the file is.

Key concepts: path = scope · direct file reading · no database · immediate change.

⚡ Use the same agent in both scopes

Nothing prevents there from being a code-reviewer.md both in ~/.claude/agents/ how much in .claude/agents/ from the project. Claude Code joins at startup — both remain available. If they have the same name, the project one takes precedence over the global one.

Example: the same agent in both scopes code-reviewer.md

~/.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Revisa qualquer código que eu
  peça, com foco em legibilidade e segurança.
  Use em qualquer projeto.
model: claude-sonnet-4-5
tools: Read, Glob, Grep
---

Você é um revisor de código sênior.
Analise o código fornecido e aponte:
1. Problemas de segurança
2. Código difícil de manter
3. Sugestões de simplificação

Seja direto. Máximo 10 pontos por revisão.

Personal version — generic, multi-project

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Revisa código deste projeto
  seguindo nossas convenções internas
  (ESLint config, naming patterns do time).
model: claude-sonnet-4-5
tools: Read, Glob, Grep
---

Você é um revisor sênior deste projeto.
Siga RIGOROSAMENTE as convenções em
CLAUDE.md antes de qualquer sugestão.
Verifique também conformidade com:
- Padrões do ESLint do projeto
- Convenção de nomear hooks com useX
- Não usar any no TypeScript

Project version — specialized, takes precedence

💡 When they conflict: the project takes precedence

If both have name: code-reviewer, Claude uses the project version. This lets the team "override" your global version with one adapted to the context — without you having to delete your personal one.

What it is: the two scopes coexist — Claude combines global + project at startup, with the project taking precedence in case of a duplicate name.

Why learn: allows a generic global version and a project-specific one without conflicts — the most flexible pattern for teams that also have individual preferences.

Key concepts: project precedence · scope coexistence · progressive specialization · override without deletion.

🔗 The same logic: skills, hooks, and MCP

The project × global pattern isn’t unique to agents. Skills (.claude/skills/), hooks, and MCP servers follow exactly the same division. Learn once, apply across all Claude Code resources.

Resource	Project scope	Global scope
Agents	.claude/agents/	~/.claude/agents/
Skills	.claude/skills/	~/.claude/skills/
Hooks	.claude/settings.json	~/.claude/settings.json
MCP servers	.claude/settings.json	~/.claude/settings.json
CLAUDE.md	CLAUDE.md (repo root)	~/.claude/CLAUDE.md

📊 A unified mental model

The rule is always the same: project shares, global is yours. Once you've internalized this for agents, you already know how to think about skills, hooks, and MCP. Claude Code is consistent — learn the pattern once.

In hooks and MCP, the logic for precedence also applies: project settings merge with global settings, but a project hook can override a global one with the same name.

What it is: the project × global pattern is universal in Claude Code — it applies consistently to agents, skills, hooks, and MCP.

Why learn: you don’t need to learn a different model for each feature. One mental model covers the entire Claude Code configuration ecosystem.

Key concepts: unified model · ecosystem consistency · project-shared, global is yours · merging + precedence.

⌨️

Ready-made prompts (copy and paste)

Three prompts to manage agent scopes in Claude Code. Use them directly in your conversation with the orchestrator.

Prompt 1 — move an agent from global to the project promotes to the team

Mova o agente "code-reviewer" do meu escopo global
(~/.claude/agents/) para este projeto (.claude/agents/).
Depois me mostre o caminho final e confirme que o arquivo
saiu do global.

Prompt 2 — list agents from both scopes quick audit

Liste todos os agentes disponíveis nesta sessão,
separando os que vêm do escopo do projeto
(.claude/agents/) dos globais (~/.claude/agents/).
Mostre o nome e o caminho de cada um.

Prompt 3 — create a project-specific version of a global agent specialization

Leia o meu agente global "code-reviewer"
(~/.claude/agents/code-reviewer.md) e crie uma versão
especializada para este projeto em .claude/agents/,
adicionando as convenções do CLAUDE.md deste repo.
Mantenha o mesmo name para que o projeto tenha
precedência sobre o global.

🖥️

Simulated screen: two scopes in one session

See how Claude Code displays agents from both scopes in an actual listing. The code-reviewer the project's appears (it takes precedence); other agents come from the global scope without conflict.

claude code · meu-projeto · agents available /agents list

# Agents loaded in the session:

# [PROJECT] .claude/agents/

code-reviewer → .claude/agents/code-reviewer.md [takes precedence]

test-runner → .claude/agents/test-runner.md

doc-writer → .claude/agents/doc-writer.md

# [GLOBAL] ~/.claude/agents/

code-reviewer → ~/.claude/agents/code-reviewer.md [overridden by the project]

security-audit → ~/.claude/agents/security-audit.md

meu-setup → ~/.claude/agents/meu-setup.md

# Total: 5 active agents (1 overlapping, 4 unique)

orchestrator · Sonnet | 8% context | meu-projeto/

↑ Illustrative recreation. Note the code-reviewer appearing in both scopes—the project scope takes precedence.

🎯

Exercise — decide the scope of 4 agents

For each of the 4 agents below, decide whether it should be in scope for the project or in the global, and justify it with a objective reason.

🔍

A) sql-query-expert

Knows this project's database schema. Generates optimized queries for the system's specific tables.

✍️

B) pt-br-writer

Rewrites any text in my Brazilian Portuguese writing style. Personal preferences for tone and vocabulary.

🧪

C) e2e-test-runner

Runs this project’s end-to-end tests using Playwright. Knows the test:e2e scripts in package.json.

🔐

D) security-scanner

Performs security audits on any code. Searches for known vulnerabilities (OWASP Top 10). Use in all projects.

✅ Verification criteria

For each agent, your decision is correct if you can answer yes to the corresponding question:

A:Project → "Does the team need this agent to work in this repository?" (yes — the schema belongs to the project)
B:Global → "Is this a personal preference unrelated to any specific project?" (yes — it’s your style)
C:Project → "Does this agent break if it’s used outside this specific repository?" (yes — the scripts belong to this project)
D:Global → "Is this agent useful in any project, regardless of context?" (yes — security is universal)

The question that defines the scope

"This agent works outside from this repository?" — If so, consider making it global. If project context is essential for the agent to make sense, it belongs in the project. If it depends on sensitive data that should not be committed, it should remain global.

✅ Module summary

✓

.claude/agents/ in the repo — versioned, shared with the team via Git, and reviewed in code review.

✓

~/.claude/agents/ global — yours alone, available in all projects, never pushed to git.

✓

Share via git — project agents are repository citizens, with history and PR review.

✓

Just you — global is your personal, portable drawer; it doesn't exist in CI/CD or clutter the repo.

✓

Move = move the .md — there's no registration or installation; the scope is defined by the file path.

✓

Coexistence — both scopes are loaded; the project takes precedence when names are duplicated.

✓

Unified model — skills, hooks, and MCP follow the same project × global logic.

Next module:

2.6 — Creating with /agents + how Claude chooses. How the shortcut /agents works and the criterion the conductor uses to decide which agent to call.

← Module 2.4: Tools and permissions Next module →