{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://catalog.lintel.tools/schemas/claude-code/agent/latest.json",
  "title": "Claude Code Subagent",
  "description": "Frontmatter schema for [Claude Code subagent](https://code.claude.com/docs/en/sub-agents) definitions (`.claude/agents/*.md`). Subagents are specialized AI assistants that run in their own context window with a custom system prompt, specific tool access, and independent permissions. The markdown body after the `---` frontmatter becomes the subagent's **system prompt** (not the full Claude Code system prompt — only the body plus basic environment details). Subagents are stored at `~/.claude/agents/` (personal), `.claude/agents/` (project), `<plugin>/agents/` (plugin), or passed via `--agents` CLI flag (session-only). When multiple subagents share the same name, higher-priority locations win: CLI > project > personal > plugin. Subagents cannot spawn other subagents.",
  "x-lintel": {
    "source": "https://raw.githubusercontent.com/lintel-rs/catalog/master/schemas/claude-code/agent.json",
    "sourceSha256": "ba6c64d4b6e08b1af233b035dc75b587848863ab4da54bc9196f412e24faf103",
    "fileMatch": [
      "**/.claude/agents/*.md",
      ".claude/agents/*.md"
    ],
    "parsers": [
      "markdown"
    ],
    "catalogDescription": "Frontmatter for Claude Code subagent definitions."
  },
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Unique identifier for the subagent using lowercase letters, numbers, and hyphens. Used to reference the subagent in `Task(agent-name)` tool restrictions, [permission deny rules](https://code.claude.com/docs/en/permissions#tool-specific-permission-rules), hook matchers, and the `/agents` interface. Plugin subagents appear namespaced as `plugin-name:agent-name`.",
      "pattern": "^[a-z][a-z0-9-]*$",
      "examples": [
        "code-reviewer",
        "debugger",
        "data-scientist"
      ]
    },
    "description": {
      "type": "string",
      "description": "Describes when and how Claude should delegate to this subagent. Claude uses this to decide **automatic delegation** — write it as a triggering guide with concrete task patterns. Include phrases like *\"use proactively\"* to encourage automatic delegation. This is the single most important field for subagent behavior — a vague description means Claude won't know when to delegate. See [automatic delegation](https://code.claude.com/docs/en/sub-agents#understand-automatic-delegation).",
      "examples": [
        "Expert code reviewer. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.",
        "Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.",
        "Data analysis expert for SQL queries, BigQuery operations, and data insights."
      ]
    },
    "tools": {
      "description": "[Tools](https://code.claude.com/docs/en/settings#tools-available-to-claude) the subagent can use. If omitted, inherits **all** tools from the main conversation (including MCP tools). Specify a subset to restrict access. Built-in tools: `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Task`, `Skill`, `NotebookEdit`. Supports patterns: `Bash(git *)` allows only `git` subcommands, `Skill(commit)` allows invoking a specific skill, `Task(worker, researcher)` restricts spawnable subagent types (only meaningful for agents run as main thread via `claude --agent`). MCP tools follow the pattern `mcp__<server>__<tool>`.",
      "oneOf": [
        {
          "type": "string",
          "description": "Comma-separated list of tool names.",
          "examples": [
            "Read, Grep, Glob, Bash"
          ]
        },
        {
          "type": "array",
          "items": {
            "$ref": "https://catalog.lintel.tools/schemas/claude-code/permission/latest.json"
          },
          "description": "Array of tool names.",
          "examples": [
            [
              "Read",
              "Grep",
              "Glob",
              "Bash"
            ]
          ]
        }
      ]
    },
    "disallowedTools": {
      "description": "Tools to explicitly deny, removed from the inherited or specified tool list. Use when you want to grant most tools but block a few specific ones (e.g. block `Write` and `Edit` for a read-only agent). Supports the same tool name formats as `tools`.",
      "oneOf": [
        {
          "type": "string",
          "description": "Comma-separated list of tool names to deny.",
          "examples": [
            "Write, Edit"
          ]
        },
        {
          "type": "array",
          "items": {
            "$ref": "https://catalog.lintel.tools/schemas/claude-code/permission/latest.json"
          },
          "description": "Array of tool names to deny.",
          "examples": [
            [
              "Write",
              "Edit"
            ]
          ]
        }
      ]
    },
    "model": {
      "type": "string",
      "description": "Which [Claude model](https://code.claude.com/docs/en/model-config) the subagent uses. Set to `inherit` (default) to use the same model as the main conversation. Use `haiku` for fast, low-latency tasks (search, exploration). Use `sonnet` for balanced capability. Use `opus` for the most capable reasoning.",
      "enum": [
        "opus",
        "sonnet",
        "haiku",
        "inherit"
      ],
      "default": "inherit",
      "examples": [
        "sonnet",
        "inherit"
      ]
    },
    "permissionMode": {
      "type": "string",
      "description": "Controls how the subagent handles [permission prompts](https://code.claude.com/docs/en/permissions). Subagents inherit the permission context from the main conversation but can override the mode. If the parent uses `bypassPermissions`, it takes precedence and cannot be overridden. Background subagents auto-deny unpermitted actions rather than prompting.\n\n- `default`: Standard permission prompts\n- `acceptEdits`: Auto-accept file edits (`Write`, `Edit`)\n- `dontAsk`: Auto-deny permission prompts (explicitly allowed tools still work)\n- `bypassPermissions`: Skip all permission checks (**use with caution**)\n- `plan`: Read-only exploration, requires approval before implementation",
      "enum": [
        "default",
        "acceptEdits",
        "dontAsk",
        "bypassPermissions",
        "plan"
      ],
      "examples": [
        "default",
        "plan"
      ]
    },
    "maxTurns": {
      "type": "integer",
      "description": "Maximum number of agentic turns (API round-trips) before the subagent automatically stops and returns results. Each tool use counts as one turn. Use to prevent runaway subagents or control cost.",
      "minimum": 1,
      "examples": [
        10,
        25,
        50
      ]
    },
    "skills": {
      "description": "[Skills](https://code.claude.com/docs/en/skills) to [preload](https://code.claude.com/docs/en/sub-agents#preload-skills-into-subagents) into the subagent's context at startup. The **full content** of each skill is injected (not just made available for invocation). Subagents do **not** inherit skills from the parent conversation — you must list them explicitly. This is the inverse of [running a skill in a subagent](https://code.claude.com/docs/en/skills#run-skills-in-a-subagent) (`context: fork`).",
      "oneOf": [
        {
          "type": "string",
          "description": "Single skill name."
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Array of skill names."
        }
      ],
      "examples": [
        [
          "api-conventions",
          "error-handling-patterns"
        ],
        "code-review-checklist"
      ]
    },
    "mcpServers": {
      "type": "object",
      "description": "[MCP servers](https://code.claude.com/docs/en/mcp) available to this subagent. Each key is a server name — the value is either an empty object `{}` to reference an already-configured server by name, or an inline definition with a full [MCP server config](https://code.claude.com/docs/en/mcp#configure-mcp-servers). MCP tools are **not** available in [background subagents](https://code.claude.com/docs/en/sub-agents#run-subagents-in-foreground-or-background).",
      "examples": [
        {
          "github": "github",
          "slack": "slack"
        },
        {
          "custom-db": {
            "command": "python",
            "args": [
              "/path/to/mcp-server.py"
            ],
            "env": {
              "DB_URL": "postgresql://localhost:5432"
            }
          }
        }
      ],
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "description": "Reference to an already-configured MCP server by name."
          },
          {
            "$ref": "https://catalog.lintel.tools/schemas/claude-code/mcp-server-config/latest.json",
            "description": "Inline MCP server definition."
          }
        ]
      }
    },
    "hooks": {
      "$ref": "https://catalog.lintel.tools/schemas/claude-code/hooks/latest.json",
      "description": "Lifecycle [hooks](https://code.claude.com/docs/en/hooks) scoped to this subagent. Hooks defined here only fire while this subagent is active and are cleaned up when it finishes. `Stop` hooks in frontmatter are automatically converted to `SubagentStop` events at runtime. See [hooks in skills and agents](https://code.claude.com/docs/en/hooks#hooks-in-skills-and-agents)."
    },
    "memory": {
      "type": "string",
      "description": "Enable [persistent memory](https://code.claude.com/docs/en/sub-agents#enable-persistent-memory) that survives across conversations. The subagent gets a dedicated memory directory to build knowledge over time (codebase patterns, debugging insights, architectural decisions). When enabled, the first 200 lines of `MEMORY.md` are included in the system prompt, and `Read`/`Write`/`Edit` tools are automatically enabled.\n\n- `user`: `~/.claude/agent-memory/<name>/` — learnings across all projects\n- `project`: `.claude/agent-memory/<name>/` — project-specific, shareable via VCS\n- `local`: `.claude/agent-memory-local/<name>/` — project-specific, gitignored",
      "enum": [
        "user",
        "project",
        "local"
      ],
      "examples": [
        "user"
      ]
    },
    "background": {
      "type": "boolean",
      "description": "When `true`, always run this subagent as a [background task](https://code.claude.com/docs/en/sub-agents#run-subagents-in-foreground-or-background). Background subagents run concurrently while the main conversation continues. Before launching, Claude prompts for needed tool permissions upfront. Background subagents auto-deny unpermitted actions and cannot use MCP tools or ask clarifying questions via `AskUserQuestion`. Set `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` to disable all background tasks. Users can also press **Ctrl+B** to background a running foreground subagent.",
      "default": false,
      "examples": [
        true
      ]
    },
    "isolation": {
      "type": "string",
      "description": "Set to `worktree` to run the subagent in a temporary [git worktree](https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), giving it an isolated copy of the repository. The subagent can make changes without affecting the main working tree. The worktree is automatically cleaned up if the subagent makes no changes. Useful for parallel exploration or risky operations that should be isolated.",
      "enum": [
        "worktree"
      ],
      "examples": [
        "worktree"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "name",
    "description"
  ]
}