[
    {
        "role": "user",
        "content": "when%20using%20claude%20code%2C%20why%20would%20i%20want%20a%20sub-agent%3F%20is%20it%20configured%20differently%3F%20does%20it%20have%20specialized%20knowledge%3F%20does%20that%20knowledge%20come%20from%20the%20agent%27s%20CLAUDE.md%20file%20or%20similar%20or%20is%20it%20different%3F"
    },
    {
        "role": "assistant",
        "content": "Here\u2019s a breakdown of *subagents* in Claude Code: what they are, why you\u2019d want them, how they\u2019re configured, where their \u201cknowledge\u201d comes from, and how they interact with Project-level files like `CLAUDE.md`. This should answer your questions in detail, with the latest from Anthropic documentation.\n\n---\n\n## What are Subagents\n\nSubagents are essentially specialized Claude instances meant to handle **focused tasks**. They:\n\n- Run in their **own context window**\u2014separate from the main conversation. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/subagents?utm_source=openai))  \n- Have their own **system prompt**, which defines their purpose. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/subagents?utm_source=openai))  \n- Can be restricted to use only certain tools (or have all tools by default). ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/subagents?utm_source=openai))  \n\nSo think of them like specialized workers: \u201ccode reviewer,\u201d \u201ctester,\u201d \u201cdata researcher,\u201d etc.\n\n---\n\n## Why Use Them\n\nYou\u2019d want subagents for several reasons:\n\n1. **Context Preservation**  \n   Long exploration, code search, or data gathering tasks can clutter up your main context. Subagents keep that separate and provide you just the relevant summary or result. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/subagents?utm_source=openai))\n\n2. **Specialization & Quality**  \n   By giving a subagent a focused role (via its system prompt and selected tools), those tasks are done better and more reliably. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/subagents?utm_source=openai))\n\n3. **Tool Access Control**  \n   Limit the tools a subagent has\u2014e.g. read-only vs. write-enabled. Keeps risk lower for powerful operations. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/subagents?utm_source=openai))\n\n4. **Parallelism & Reuse**  \n   You can invoke several subagents in parallel or reuse an agent across projects. Once you define a subagent, it can be used wherever it's applicable. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/subagents?utm_source=openai))\n\n---\n\n## How They\u2019re Configured\u2014Particularly Regarding \u201cKnowledge\u201d\n\nSubagents are configured using system prompts, tool restrictions, model selection, and more. Here\u2019s how those parts feed into what a subagent \u201cknows\u201d or can do:\n\n- **Definition via Markdown + YAML frontmatter**  \n  Each custom subagent is defined in a Markdown file with YAML frontmatter. That includes:\n\n  - `name`\n  - `description` \u2014 critical, because Claude uses this to decide when to delegate tasks automatically. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai))  \n  - `tools` or `disallowedTools` \u2014 specifying exactly what the subagent can do. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n  - `model` (alias or \u201cinherit\u201d) \u2014 to set which variant of Claude or environment it'll use. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/subagents?utm_source=openai))  \n  - Optional settings like memory scope, background vs foreground, etc. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai))\n\n- **System prompt**  \n  The body of the Markdown defines a \u201csystem prompt\u201d for the subagent. It is how you encode its personality, rules, approaches, constraints. This is \u201cknowledge\u201d only insofar as it sets how it should reason. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))\n\n- **What subagents inherit vs what they don\u2019t**  \n  *Inherit:* project files like `CLAUDE.md` (loaded via `settingSources`), tool definitions from the parent (unless restricted via `tools`/`disallowedTools`) ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai))  \n  *Don\u2019t inherit:* the parent\u2019s conversation history, parent\u2019s system prompt. So a subagent starts with fresh conversation context. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai))\n\n---\n\n## Role of `CLAUDE.md` and Project-Level Files\n\n`CLAUDE.md` functions as a kind of manifest or project \u201cidentity and policy\u201d file. It can include project context, guidelines, identity, operational rules, etc. ([arxiv.org](https://arxiv.org/abs/2509.14744?utm_source=openai))\n\n- **Loaded via settingSources**  \n  Subagents can see `CLAUDE.md` because it\u2019s part of \u201cproject setting sources.\u201d So that's one input to their knowledge base of \u201cwhat this project is.\u201d ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai))\n\n- **Not filling in system prompt or memory**  \n  `CLAUDE.md` does *not* stand in for a subagent\u2019s system prompt. The subagent has its own system prompt defined in its agent file. So `CLAUDE.md` gives project-wide background; the system prompt gives task-specific directions. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai))\n\n---\n\n## Summary: Is the Knowledge Different?\n\nYes. A subagent\u2019s \u201cknowledge\u201d comes from:\n\n1. **The system prompt and configuration**  \n   That defines how the agent behaves, what constraints it has, what focus it takes.\n\n2. **Tools + files it\u2019s allowed to access**  \n   If you restrict tools, the subagent is \u201cblind\u201d to ones you didn\u2019t include. If it has read-only tools, it can't modify. So its capacity depends on what you grant it. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/subagents?utm_source=openai))\n\n3. **Project-level context (`CLAUDE.md` etc.)**  \n   It inherits these setting sources, so it knows things you put in your project manifest. But you still need to encode task-specific instructions via its system prompt. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai))\n\nSo: subagents *don\u2019t* have magical extra domain knowledge built-in unless you give them that via prompt, tools, or project files. They just have more precise configuration.\n\n---\n\nIf you want, I can show an example: how you might turn a `code-reviewer` subagent into a CLAUDE.md-based project policy, how you set it up, and how it works in practice. Want me to walk you through that?"
    },
    {
        "role": "user",
        "content": "sounds%20a%20lot%20like%20a%20skill"
    },
    {
        "role": "assistant",
        "content": "Yes \u2014 you nailed it. A subagent in Claude Code *does* act a lot like a \u201cskill,\u201d but with several key differences. Below is a detailed comparison and some guidance on when to use skills vs. subagents.\n\n---\n\n## What Are Skills\n\n- Skills are reusable, modular pieces of behavior (knowledge, workflows, domain expertise) that agents can invoke when needed. ([code.claude.com](https://code.claude.com/docs/en/features-overview?utm_source=openai))  \n- They\u2019re generally defined via Markdown files (`SKILL.md`) with YAML frontmatter, describing what they do, triggers, metadata, example usage. ([zencoder.ai](https://zencoder.ai/blog/claude-code-skills-vs-subagents?utm_source=openai))  \n- They load into the *existing context* (conversation or agent session) and are used when relevant or explicitly called. They don\u2019t isolate context. ([support.claude.com](https://support.claude.com/en/articles/12512180-using-skills-in-claude?utm_source=openai))  \n\n---\n\n## What Are Subagents\n\n- Subagents are *fully separate assistant instances* spawned by Claude to perform focused, specialized tasks\u2014each with its own context window, tools, permissions, and system prompt. They then return only the final results or summary to the main session. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n- Their configuration includes:  \n  \u2022 A custom system prompt to define their role. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n  \u2022 Tool access restrictions or allowlists/denylists. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n  \u2022 An option to preload skills into them. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n\n---\n\n## Key Differences: Skills vs. Subagents\n\n| Aspect | Skill | Subagent |\n|---|---|---|\n| **Context isolation** | Shares the main session\u2019s context; content from skills is visible in your current conversation. ([code.claude.com](https://code.claude.com/docs/en/features-overview?utm_source=openai)) | Runs in a separate context; intermediate logs, file reads, etc., don\u2019t bloat the main conversation. Only the summary or result returns. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai)) |\n| **Tool permissions** | Inherits the main session\u2019s tools; doesn\u2019t have its own permissions. | Has its own tools or restrictions, which you explicitly configure. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai)) |\n| **System prompt & behavior** | Skills encode instructions/knowledge that any agent can draw on. | Subagents have their own system prompt that defines their behavior fully. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai)) |\n| **When they run** | On demand (you invoke or Claude invokes) when their triggers are met. | Automatically delegated by Claude if matching `description`, or explicitly requested. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai)) |\n| **Best use cases** | Shared domain knowledge, common procedures, style guides, workflows used across many tasks or sessions. | Tasks that are heavy, specialized, need isolation, involve lots of file operations, or you want separate QA or review agents. |\n\n---\n\n## When to Use Which\n\nUse **skills** when:\n\n- You have knowledge or expertise that many agents or tasks will draw on (coding conventions, security best practices, naming standards).\n- You want lightweight, quickly invoked workflows inside your current session.\n- You don\u2019t need separate context or permissions for a task.\n\nUse **subagents** when:\n\n- A task requires reading many files, extracting deep details, or lots of back-and-forth. Isolation helps keep the main session uncluttered. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n- You need restricted permissions (e.g. read-only vs edit/write) to reduce risk. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n- You want to run parallel tasks (e.g. one agent checking security, another reviewing performance) and combine results. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n\n---\n\nYes \u2014 in many senses, a subagent *is* like a \u201cskill plus\u201d: it has its own behavior, tool constraints, possibly domain knowledge (via preloaded skills), and works independently. But it\u2019s heavier-weight and brings isolation, which is often the trade-off you need when your tasks get more complex.\n\nIf you want, I can sketch out a practical example: how you might combine a subagent and skill for, say, automatic security auditing of your codebase."
    },
    {
        "role": "user",
        "content": "how%20do%20i%20invoke%20each%20from%20within%20claude%20code%3F"
    },
    {
        "role": "assistant",
        "content": "Here\u2019s how you invoke **skills** and **subagents** in Claude Code \u2014 different mechanisms, both pretty flexible. Below are the common ways to trigger each, plus examples.\n\n---\n\n## Invoking Skills\n\nSkills are modular capabilities (playbooks, procedures, domain logic, etc.) in Claude Code that you can either let the system decide to use automatically or explicitly invoke.\n\n- **Automatic invocation**: Claude loads and uses skills when your prompt matches the skill\u2019s *description* or seems relevant. You don\u2019t need to do anything special in many cases. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/skills?utm_source=openai))  \n- **Explicit invocation** using slash commands: Type `/skill-name` at the beginning of your message to trigger a specific skill. ([code.claude.com](https://code.claude.com/docs/en/slash-commands?utm_source=openai))  \n- **Restriction configuration** via frontmatter: In your skill\u2019s `SKILL.md`, you can set `disable-model-invocation: true` so only you can invoke it (not automatically), or `user-invocable: false` so only Claude can invoke it when appropriate. ([code.claude.com](https://code.claude.com/docs/en/slash-commands?utm_source=openai))  \n\n**Example**:\nIf you have a skill called \u201cformat-code\u201d, you might do:\n\n```\n/format-code\nPlease format these modules according to style guidelines.\n```\n\nOr you might just say:\n\n> \u201cI need this codebase cleaned up per style rules\u201d\n\nAnd Claude might automatically use your \u201cformat-code\u201d skill if your description matches.\n\n---\n\n## Invoking Subagents\n\nSubagents are separate-specialist agents with their own permissions, tools, and context. They\u2019re invoked in a few different ways.\n\n1. **Automatic delegation**  \nClaude observes your prompt, compares it against each subagent\u2019s `description`, and if there\u2019s a match, Claude can delegate the task to that subagent automatically. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai))\n\n2. **Explicit invocation by naming**  \nYou can *tell* Claude to use a specific named subagent. Examples:\n\n   - Natural language: \u201cUse the code-reviewer agent to look at this pull request\u201d ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/subagents?utm_source=openai))  \n   - @-mention: `@\"code-reviewer (agent)\" review this module` or `@agent-code-reviewer fix this bug in the auth system` ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n\n3. **Session-wide invocation**  \nMake the subagent the default agent for the entire session. You can use the command line flag `--agent <name>`, or set `\"agent\": \"<name>\"` in `.claude/settings.json`. Then all turns use that subagent\u2019s system prompt, tools, and model. ([code.claude.com](https://code.claude.com/docs/en/sub-agents?utm_source=openai))  \n\n---\n\n## When to Use Each\n\n| Scenario | Use Skill |\n|---|---|\n| Need a reusable procedure (checklist, formatting rules, policy) that\u2019s applied when relevant or manually | \u2714\ufe0f |\n| You want behaviour baked in across tasks without retyping instructions | \u2714\ufe0f |\n| Need to isolate tasks or restrict tools, run something heavy separately with its own context | \u274c |\n\n| Scenario | Use Subagent |\n|---|---|\n| Task involves complex work (e.g. long file reads, tests, code modifications) that would clutter main conversation | \u2714\ufe0f |\n| Need restricted permissions (e.g. read-only review, no write) | \u2714\ufe0f |\n| Want parallel agents or a specialist agent you can invoke explicitly or make default | \u2714\ufe0f |\n\n---\n\nLet me know if you want to try setting up both in one workflow\u2014with examples of your domain/codebase\u2014and I can sketch that out for you."
    }
]