Creare subagent personalizzati

• Preservare il contesto mantenendo l’esplorazione e l’implementazione fuori dalla sua conversazione principale
• Applicare vincoli limitando quali strumenti un subagent può utilizzare
• Riutilizzare configurazioni tra progetti con subagent a livello utente
• Specializzare il comportamento con prompt di sistema focalizzati per domini specifici
• Controllare i costi instradando le attività a modelli più veloci e economici come Haiku

​

Subagent integrati

• Per bloccare un tipo integrato specifico, aggiungetelo a permissions.deny come mostrato in Disabilitare subagent specifici.
• Per impedire a Claude di delegare a qualsiasi subagent, negate lo strumento Agent stesso con permissions.deny.
• In modalità non interattiva e in Agent SDK, impostate CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 per rimuovere tutti i tipi integrati e fornire solo i vostri.

​

Quickstart: crea il suo primo subagent

/agents

A code improvement agent that scans files and suggests improvements
for readability, performance, and best practices. It should explain
each issue, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

​

Configuri i subagent

​

Usi il comando /agents

• Visualizzare tutti i subagent disponibili (integrati, utente, progetto e plugin)
• Creare nuovi subagent con configurazione guidata o generazione Claude
• Modificare la configurazione del subagent esistente e l’accesso agli strumenti
• Eliminare subagent personalizzati
• Vedere quali subagent sono attivi quando esistono duplicati

​

Scelga l’ambito del subagent

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

​

Scriva file subagent

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

​

Campi frontmatter supportati

​

Scelga un modello

• Alias modello: Usi uno degli alias disponibili: sonnet, opus, haiku, o fable
• ID modello completo: Usi un ID modello completo come claude-opus-4-8 o claude-sonnet-5. Accetta gli stessi valori del flag --model
• inherit: Usi lo stesso modello della conversazione principale
• Omesso: Se non specificato, predefinito a inherit (usa lo stesso modello della conversazione principale)

1. La variabile di ambiente CLAUDE_CODE_SUBAGENT_MODEL, quando impostata a un alias modello o ID modello
2. Il parametro model per invocazione
3. Il frontmatter model della definizione del subagent
4. Il modello della conversazione principale

​

Controlli le capacità del subagent

​

Strumenti disponibili

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode, a meno che la permissionMode del subagent non sia plan
• ScheduleWakeup
• WaitForMcpServers

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

​

Limiti quali subagent possono essere generati

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

tools: Agent, Read, Bash

​

Limiti i server MCP a un subagent

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

• --strict-mcp-config e --bare
• Configurazione MCP gestita aziendale
• Politiche allowedMcpServers e deniedMcpServers

​

Modalità di autorizzazione

​

Precarichi skills nei subagent

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

​

Abiliti memoria persistente

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

• Il prompt di sistema del subagent include istruzioni per leggere e scrivere nella directory di memoria.
• Il prompt di sistema del subagent include anche le prime 200 righe o 25KB di MEMORY.md nella directory di memoria, a seconda di quale sia minore, con istruzioni per curare MEMORY.md se supera quel limite.
• Gli strumenti Read, Write e Edit vengono automaticamente abilitati in modo che il subagent possa gestire i suoi file di memoria.

• project è l’ambito predefinito consigliato. Lo rende condivisibile tramite controllo della versione. Usi user quando la conoscenza del subagent è ampiamente applicabile tra progetti, o local quando la conoscenza non dovrebbe essere archiviata nel controllo della versione.
• Chieda al subagent di consultare la sua memoria prima di iniziare il lavoro: “Review this PR, and check your memory for patterns you’ve seen before.”
• Chieda al subagent di aggiornare la sua memoria dopo aver completato un’attività: “Now that you’re done, save what you learned to your memory.” Nel tempo, questo costruisce una base di conoscenza che rende il subagent più efficace.
• Includa istruzioni di memoria direttamente nel file markdown del subagent in modo che mantenga proattivamente la sua stessa base di conoscenza:
  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

​

Regole condizionali con hooks

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

​

Disabiliti subagent specifici

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

claude --disallowedTools "Agent(Explore)"

​

Definisca hook per i subagent

• Nel frontmatter del subagent: Definisca hook che vengono eseguiti solo mentre quel subagent è attivo
• In settings.json: Definisca hook che vengono eseguiti nella sessione principale quando i subagent iniziano o si fermano

​

Hook nel frontmatter del subagent

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

​

Hook a livello di progetto per gli eventi dei subagent

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

​

Lavori con i subagent

​

Comprenda la delegazione automatica

​

Invochi i subagent esplicitamente

• Linguaggio naturale: nomini il subagent nel suo prompt; Claude decide se delegare
• @-mention: garantisce che il subagent viene eseguito per un’attività
• A livello di sessione: l’intera sessione utilizza il prompt di sistema, le restrizioni di strumenti e il modello di quel subagent tramite il flag --agent o l’impostazione agent

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

​

Esegua i subagent in primo piano o in background

• Subagent in primo piano bloccano la conversazione principale fino al completamento. I prompt di autorizzazione vengono passati a lei mentre si presentano.
• Subagent in background vengono eseguiti contemporaneamente mentre continua a lavorare. A partire da v2.1.186, quando un subagent in background raggiunge una chiamata di strumento che necessita di autorizzazione, il prompt emerge nella sua sessione principale e nomina il subagent che sta chiedendo. Approvi per consentire al subagent di continuare, o premi Esc per negare quella singola chiamata di strumento senza fermare il subagent. Prima di v2.1.186, i subagent in background auto-negavano qualsiasi chiamata di strumento che avrebbe richiesto un prompt.

• Chiedere a Claude di “run this in the background”
• Premere Ctrl+B per mettere in background un’attività in esecuzione

​

Modelli comuni

​

Isoli operazioni ad alto volume

Use a subagent to run the test suite and report only the failing tests with their error messages

​

Esegua ricerca parallela

Research the authentication, database, and API modules in parallel using separate subagents

​

Concateni i subagent

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

​

Scelga tra subagent e conversazione principale

• L’attività necessita di frequenti scambi o raffinamento iterativo
• Più fasi condividono contesto significativo, come pianificazione, implementazione e test
• Sta facendo un cambio rapido e mirato
• La latenza è importante. I subagent iniziano da zero e potrebbero aver bisogno di tempo per raccogliere contesto

• L’attività produce output dettagliato che non ha bisogno nel suo contesto principale
• Vuole applicare restrizioni di strumenti o autorizzazioni specifiche
• Il lavoro è autonomo e può restituire un riassunto

​

Generi subagent annidati

​

Gestisca il contesto del subagent

​

Cosa si carica all’avvio

• System prompt: il prompt dell’agente stesso più i dettagli dell’ambiente che Claude Code aggiunge, non il prompt di sistema completo di Claude Code. I subagent personalizzati definiscono il loro nel corpo markdown o nel campo prompt. Gli agenti integrati hanno prompt predefiniti.
• Task message: il prompt di delegazione che Claude scrive quando consegna il lavoro.
• CLAUDE.md e memory: ogni livello della gerarchia di memoria che la conversazione principale carica, inclusi ~/.claude/CLAUDE.md, regole del progetto, CLAUDE.local.md e file di policy gestiti. Gli agenti Explore e Plan integrati saltano questo.
• Git status: uno snapshot preso all’inizio della sessione genitore. Assente quando la directory di lavoro non è un repository Git o quando includeGitInstructions è false. Explore e Plan lo saltano comunque.
• Preloaded skills: contenuto completo di qualsiasi skill denominata nel campo skills dell’agente. Gli agenti integrati non precaricano skills.

​

Riprenda i subagent

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• Compattazione della conversazione principale: quando la conversazione principale si compatta, le trascrizioni dei subagent non sono interessate. Sono archiviate in file separati.
• Persistenza della sessione: le trascrizioni dei subagent persistono all’interno della loro sessione. Può riprendere un subagent dopo aver riavviato Claude Code riprendendo la stessa sessione.
• Pulizia automatica: le trascrizioni vengono pulite in base all’impostazione cleanupPeriodDays, che per impostazione predefinita è 30 giorni.

​

Auto-compattazione

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

​

Esegua il fork della conversazione corrente

• Claude può generare un fork richiedendo esplicitamente il tipo di subagent fork. Gli spawn senza un tipo di subagent continuano a utilizzare il subagent general-purpose, e i subagent denominati come Explore continuano a generarsi come prima.
• Ogni spawn di subagent viene eseguito in background, sia che sia un fork che un subagent denominato. Imposti CLAUDE_CODE_DISABLE_BACKGROUND_TASKS su 1 per mantenere gli spawn sincroni.

/fork draft unit tests for the parser changes so far

​

Osservi e dirija i fork in esecuzione

​

Come i fork differiscono dai subagent denominati

​

Limitazioni

​

Subagent di esempio

​

Revisore di codice

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

​

Debugger

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

​

Data scientist

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

​

Validatore di query di database

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

Passaggi successivi

• Distribuisca subagent con i plugin per condividere i subagent tra team o progetti
• Esegua Claude Code a livello di programmazione con l’Agent SDK per CI/CD e automazione
• Usi i server MCP per dare ai subagent accesso a strumenti e dati esterni