NetFabric/intelligentium / .agents/skills/claude-code-custom-agents
claude-code-custom-agents
VerifiedCreate and maintain Claude Code custom subagents (.claude/agents/*.md files). USE FOR: authoring project (.claude/agents/) or user (~/.claude/agents/) subagent files; frontmatter fields (name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, initialPrompt); writing descriptions that drive automatic delegation and 'use proactively' phrasing; invoking subagents via natural language, @-mention, session-wide --agent, or the Agent tool; restricting which subagent types a coordinator can spawn with Agent(name1, name2); nested subagents and depth limits; built-in subagents (Explore, Plan, general-purpose, claude); troubleshooting a subagent that won't load or isn't invoked. DO NOT USE FOR: GitHub Copilot CLI custom agents (use copilot-cli-custom-agents); agent teams/teammates (a different, session-spanning feature); MCP server authoring; SKILL.md authoring (use create-skill).
Claude Code Custom Agents
A subagent is a Markdown file (.md) with YAML frontmatter plus a system-prompt body. Only name and description are required. Claude Code matches your request (and its own reasoning) against every subagent's description to decide when to delegate — a vague description rarely gets used.
Anatomy
| Part | Purpose |
|---|---|
| Frontmatter | name + description (required) + optional tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, initialPrompt |
| Body | System prompt: role, numbered workflow, output format. The subagent receives only this plus basic environment details (CLAUDE.md, git status) — not the full Claude Code system prompt |
| Location | .claude/agents/ (project, walked to Git root) and ~/.claude/agents/ (user) are watched live, no restart needed for edits to an existing directory; managed settings and --agents CLI JSON outrank both; plugin agents/ is lowest priority |
Minimal example
---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use proactively after code changes.
tools: Read, Grep, Glob
model: sonnet
---
You are a senior code reviewer. When invoked, run `git diff`, focus on
modified files, and provide feedback organized by priority (critical,
warnings, suggestions) with specific fix examples.
Invocation
| Method | Syntax |
|---|---|
| Automatic delegation | Claude matches your request against every subagent's description — include "use proactively" to encourage it |
| Natural language | Name the subagent in your prompt; Claude decides whether to delegate |
| @-mention | @agent-<name> — guarantees that specific subagent runs for one task |
| Session-wide | claude --agent <name> or "agent": "<name>" in .claude/settings.json — the whole session adopts that subagent's prompt, tools, and model |
| From another agent | The Agent tool (renamed from Task in v2.1.63) — nests up to 3 layers below the main conversation by default |
Full frontmatter field table, tool-availability filters, and location priority → references/frontmatter-reference.md.
Built-in subagents
Explore (read-only search, model inherited/capped at Opus), Plan (plan-mode research), general-purpose (every subagent tool, for mixed research+edit tasks), claude (catch-all, also the default background-session agent), plus helper agents (statusline-setup, claude-code-guide) Claude invokes automatically. A user/project subagent named Explore overrides the built-in.
Workflow
- Scope one focused role per subagent; pick a scope (
.claude/agents/project vs~/.claude/agents/user) → references/authoring-workflow.md - Run
agent-markdown-best-practicesto write a specificdescription(add "use proactively" where delegation should be eager) and a numbered-workflow prompt body - Restrict
tools/disallowedToolsto the minimum the role needs; on a coordinator, allowlist spawnable subagent types withtools: Agent(worker, researcher)→ references/delegation-and-squads.md - Choose
model:(andeffort:) using themodel-selectionskill before finalizing frontmatter — never leave it on theinheritdefault without a deliberate reason - New agent files in an existing
.claude/agents//~/.claude/agents/load within seconds, no restart — restart only when that scope'sagents/directory didn't exist when the session started - Check references/authoring-workflow.md if a subagent doesn't load or never gets invoked
- Check references/undocumented-and-gotchas.md for version-specific behavior (background-by-default execution, model resolution order, output scanning) missing from a quick skim of the docs
- Run
markdown-best-practicesover the finished subagent file for heading/list hygiene, fenced blocks, and other Markdown rendering rules
Reference Files
| File | Load When |
|---|---|
| references/frontmatter-reference.md | Writing or reviewing any frontmatter field, the available-tools list, or file location/priority rules |
| references/delegation-and-squads.md | Building a coordinator + specialist squad, nested subagents, Agent(...) allowlisting, or resuming a subagent |
| references/authoring-workflow.md | Creating a subagent (via Claude or by hand), choosing its scope, or troubleshooting why it won't load/invoke |
| references/undocumented-and-gotchas.md | Hitting a version-specific behavior the quickstart doesn't cover — background execution, permission-mode inheritance, output scanning, forks vs. subagents |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Unverified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |