CLI Coming Soon
    All tools

    Claude Code subagent builder and checker

    Published · Last updated · Docs checked 2026-11-14

    A Claude Code subagent is a Markdown file in .claude/agents/ or ~/.claude/agents/: YAML frontmatter with a required name and description, then the system prompt. Build one from the 19 documented fields below, or paste a file to check it.

    Runs in your browser. Nothing is uploaded. No AI model reads it.

    Docs examples:

    Copied from Code reviewer in the subagents docs.

    Up to 256 characters, no colon, not starting with a hyphen.

    Claude reads this to decide when to delegate. The docs suggest phrases like "use proactively" (automatic delegation).

    tools (4 ticked)

    Tick none to inherit every tool available to subagents. Names from the tools reference. Struck-through ones are taken from every subagent.

    The other 14 fields in the docs

    Need the hook itself? Make it in the hooks builder. Each field is described in the frontmatter table.

    .claude/agents/code-reviewer.md

    ---
    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.
    

    Claude Code picks up a new or edited file within a few seconds. Restart only if the .claude/agents/ folder did not exist when the session started (Write subagent files).

      Valid: 0 fail, 0 warn

      Example subagents from the docs

      The 4 files in Example subagents, copied as written. Load one into the builder to change it, or into the checker to see every rule pass.

      code-reviewer

      A read-only subagent that reviews code without modifying it.

      ---
      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
      ---
      Source

      debugger

      A subagent that can both analyze and fix issues.

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

      data-scientist

      A domain-specific subagent for data analysis work.

      ---
      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
      ---
      Source

      db-reader

      A subagent that allows Bash access but validates commands to permit only read-only SQL queries.

      ---
      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"
      ---
      Source

      The db-reader example calls ./scripts/validate-readonly-query.sh, a script the same docs section gives you to save first. Without it the hook fails instead of blocking writes.

      Where subagent files live

      You write files to two places: .claude/agents/ for the current project and ~/.claude/agents/ for all your projects. Claude Code also loads subagents from managed settings, the --agents flag and plugins, in this order:

      Where Claude Code looks for subagent files, highest priority first1Managed settingsOrganization-wide2--agents CLI flagCurrent session3.claude/agents/Current project · you save files here4~/.claude/agents/All your projects · you save files here5Plugin's agents/ directoryWhere plugin is enabled
      Priority 1 is highest. When two subagents share a name, the higher one wins (Choose the subagent scope).

      Project subagents are found by walking up from the working directory, and the closest .claude/agents/ wins on a name clash. Two files with the same name in one folder load only one of them, "chosen by filesystem read order rather than a documented precedence" (Choose the subagent scope). Keep names unique.

      Persistent memory folders by scope
      memoryFolder it writes toUse when
      user~/.claude/agent-memory/<name-of-agent>/the subagent should remember learnings across all projects
      project.claude/agent-memory/<name-of-agent>/the subagent's knowledge is project-specific and shareable via version control
      local.claude/agent-memory-local/<name-of-agent>/the subagent's knowledge is project-specific but shouldn't be checked into version control

      The memory field adds a second folder the subagent keeps notes in (Enable persistent memory).

      How Claude picks a subagent

      Claude "automatically delegates tasks based on the task description in your request, the description field in subagent configurations, and current context". So the description does the routing. Write it so it fits one subagent only, and add "use proactively" if you want Claude to reach for it without being asked.

      How Claude decides which subagent gets a taskThe task inyour requestEach subagent'sdescriptionThe currentcontextClaude delegatescode-reviewerExpert code review specialistdebuggerDebugging specialist for errors, test failures, and unex…data-scientistData analysis expert for SQL queries, BigQuery operation…code-reviewer works in its own context windowand returns only the summary
      The three inputs are quoted from Understand automatic delegation. Descriptions are the docs' example subagents.

      Keep descriptions short. Claude Code warns at startup when your subagents' descriptions add up to more than 15,000 tokens, and still loads every subagent. Put detail in the system prompt instead, which only loads when that subagent runs. To call one by hand, name it ("Use the code-reviewer subagent to...") or @-mention it.

      Every frontmatter field

      All 19 fields in the frontmatter table as of 2026-11-14. Names are case-sensitive camelCase, and Claude Code ignores a field it does not recognize without an error.

      FieldRequiredWhat it does (first line of the docs)Values
      nameYesUnique identifier of at most 256 characters, such as code-reviewer or reviewer-v2.
      descriptionYesWhen Claude should delegate to this subagent
      toolsNoTools the subagent can use, as a comma-separated string such as Read, Grep, Bash or a YAML list.
      disallowedToolsNoTools to deny, removed from inherited or specified list.
      modelNoModel to use: sonnet, opus, haiku, fable, a full model ID such as claude-opus-5-5, or inherit.sonnet, opus, haiku, fable, a full model ID, inherit
      permissionModeNoPermission mode: default, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual as an alias for default.default, acceptEdits, auto, dontAsk, bypassPermissions, plan, manual
      maxTurnsNoMaximum number of agentic turns before the subagent stops.
      autoCompactWindowNoLower the auto-compact window for this subagent to a token count from 100000 to 1000000.100000 to 1000000
      skillsNoSkills to preload into the subagent's context at startup.
      mcpServersNoMCP servers available to this subagent.
      hooksNoLifecycle hooks scoped to this subagent.
      memoryNoPersistent memory scope: user, project, or local.user, project, local
      backgroundNoSet to true to keep this subagent in the background even when Claude asks to wait for it.true
      omitClaudeMdNoSet to true to start this subagent without the user, project, and local CLAUDE.md files in its initial context; managed policy files still load, except for managed subagents.true
      effortNoEffort level when this subagent is active.low, medium, high, xhigh, max
      isolationNoSet to worktree to run the subagent in a temporary git worktree, giving it an isolated copy of the repository branched by default from your default branch rather than the parent session's HEAD.worktree
      colorNoDisplay color for the subagent in the task list and transcript.red, blue, green, yellow, purple, orange, pink, cyan
      initialPromptNoAuto-submitted as the first user turn when this agent runs as the main session agent (via --agent or the agent setting).
      experimentalNoMap of experimental options.cacheTtl: 5m or 1h

      Tool names for the tools field

      The 45 built-in names in the tools reference, the exact strings tools and disallowedTools take. Struck-through names are removed from every subagent "even when listed in the tools field" (Available tools).

      • Agent
      • Artifact
      • AskUserQuestion
      • Bash
      • CronCreate
      • CronDelete
      • CronList
      • Edit
      • EndConversation
      • EnterPlanMode
      • EnterWorktree
      • ExitPlanMode
      • ExitWorktree
      • Glob
      • Grep
      • ListAgents
      • ListMcpResourcesTool
      • LSP
      • Monitor
      • NotebookEdit
      • PowerShell
      • PushNotification
      • Read
      • ReadMcpResourceTool
      • RemoteTrigger
      • ReportFindings
      • ScheduleWakeup
      • SendFeedback
      • SendMessage
      • SendUserFile
      • ShareOnboardingGuide
      • Skill
      • SubagentHandback
      • TaskCreate
      • TaskGet
      • TaskList
      • TaskStop
      • TaskUpdate
      • TodoWrite
      • ToolSearch
      • WaitForMcpServers
      • WebFetch
      • WebSearch
      • Workflow
      • Write

      Agent is removed only at the nesting depth limit, and ExitPlanMode stays when permissionMode is plan. MCP tools use mcp__server__tool names, and mcp__github__* gives a subagent every tool from one server.

      What the checker flags

      One row per rule. Fail means Claude Code skips the file or the subagent fails to launch. Warn means it loads, but a field will not do what you meant.

      RuleDocs section
      Frontmatter starts on line 1Subagent files Claude Code skips
      Frontmatter YAML parsesSubagent files Claude Code skips
      name is presentSubagent files Claude Code skips
      description is presentSubagent files Claude Code skips
      name formatSubagent files Claude Code skips
      Only fields the docs listSupported frontmatter fields
      tools names resolveRestrict which tools a subagent can use
      disallowedTools names resolveRestrict which tools a subagent can use
      model is a documented valueChoose a model
      Other field values match the docsSupported frontmatter fields
      System prompt bodyWrite subagent files

      How it works

      Checker result for the broken example: Claude Code would skip this file, 1 fail for a name with a colon, and warns for permission_mode, the tool name read, model gpt-5 and an empty body
      The checker with the broken example loaded and "Only show fail and warn rows" ticked. Real capture, not cropped.
      1. A script in this site's repo reads the Markdown of the subagents page and the tools reference and writes a data file: the fields table, each field's allowed values, the scope and memory tables, the tool names and the example files. Nothing here is typed from memory.
      2. The builder prints fields in the docs' table order, quotes a value only when YAML needs it, and writes tools as a comma-separated string like the docs' examples. Load an example and the output matches the docs file.
      3. The checker parses the frontmatter with the open-source yaml library, then runs the 11 rules in the table above.

      It does not check inline MCP server definitions, the hook commands inside hooks, or whether a model ID exists on your account. Check hooks in your settings with the settings.json validator.

      FAQ

      What are Claude Code subagents?

      The docs call them "specialized AI assistants that handle specific types of tasks". Each one runs in its own context window with its own system prompt, tool access and permissions, and returns a summary to your main conversation (Create custom subagents). A custom subagent is one Markdown file with YAML frontmatter.

      Where do I save a subagent file?

      In .claude/agents/ for one project, or ~/.claude/agents/ for all your projects. Both folders are scanned recursively, so subfolders such as agents/review/ work. The subfolder does not change how the subagent is named or called (Choose the subagent scope).

      Which frontmatter fields are required?

      Only name and description. The other 17 are optional (Supported frontmatter fields). The file name does not have to match name.

      Why does Claude Code ignore my subagent?

      Check the file with the checker above. Claude Code skips a file without telling you when it has no name, no description, a --- that is not on line 1, a name with a colon, or YAML that does not parse (Subagent files Claude Code skips). If the agents folder did not exist when the session started, restart Claude Code.

      How do I make a read-only subagent?

      List only read tools, such as tools: Read, Grep, Glob, or keep everything else and add disallowedTools: Write, Edit. If you set both, disallowedTools is applied first (Restrict which tools a subagent can use). The docs' code-reviewer example works this way.

      Is what I type uploaded anywhere?

      No. The builder and the checker are JavaScript in your browser. There is no backend, no account and no model call. A file you choose is read with the browser's File API.

      Sources

      Both read on 2026-11-14. The hash is the sha256 of the page's Markdown export (the page URL with .md added).

      Pagesha256
      Create custom subagents00bda45456b22baae5d1a3f953f1d84b2fb8c191871d7e8753d13a24d9b74cf5
      Tools referencefe2d97e824c95da2dda7f2c47c3ebe35c063d952addacdb6cdc560ff30be9817