Skip to content

NetFabric/intelligentium / .agents/skills/claude-code-custom-agents

claude-code-custom-agents

Verified

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

references/authoring-workflow.md

View on GitHub
# Authoring Workflow

## Quickstart

1. **Ask Claude to write it**: "Create a project code-improver subagent in `.claude/agents/` that scans files for readability/performance issues, read-only, using Sonnet." Claude writes the frontmatter (`name`, `description`, `tools`, `model`) and the body.
2. **Or hand-author** the file directly — see the [minimal example](../SKILL.md#minimal-example) and [frontmatter-reference.md](frontmatter-reference.md).
3. **Review** the generated file for scope creep — confirm `tools` is actually least-privilege, not just "whatever Claude defaulted to."
4. **Try it**: "Use the code-improver agent to suggest improvements in this project," or `@agent-code-improver`.

As of v2.1.198, `/agents` no longer opens an interactive creation wizard — running it just prints a reminder to ask Claude or edit `.claude/agents/` directly. The file format and locations are unchanged.

## Write the description and prompt body

Claude delegates on `description`. Name concrete tasks and trigger conditions; add "use proactively" or "use immediately after ..." only when the role should run eagerly. State exclusions and operating limits when nearby subagents overlap. A technology label such as "Python agent" is not enough to route reliably.

The body is the subagent's system prompt, not an extension of the parent conversation. Start with a one-sentence role, then provide concrete invocation steps, domain criteria, constraints, and the output format the parent can use directly. Restate any required project convention that Claude Code does not reliably inject; do not restate frontmatter fields.

## Choosing a scope

| Scope | Location | Use when |
| --- | --- | --- |
| Project | `.claude/agents/` | Specific to this codebase; check into version control so the team shares it |
| User | `~/.claude/agents/` | Personal, useful across every project on your machine |
| Managed | Org's managed-settings `.claude/agents/` | Org-wide deployment; overrides project/user with the same name |
| Session-only | `--agents '{...}'` CLI JSON | Quick testing/automation, never written to disk |
| Plugin | `<plugin>/agents/` | Distributed with a plugin; lowest priority, and plugin subagents ignore `hooks`/`mcpServers`/`permissionMode` |

Both `.claude/agents/` and `~/.claude/agents/` are scanned recursively — organize into subfolders like `agents/review/` freely; the path doesn't affect identity, only `name` does. Keep `name` unique across the whole tree in one scope: duplicate names in the same directory resolve by filesystem read order (undocumented), and `/doctor` flags and offers to fix them.

## Restart caveats

The file watcher covers directories that already existed when the session started. Two cases still need a restart:

- Creating the *first* agent file in a scope whose `agents/` directory didn't exist yet (e.g. first-ever `.claude/agents/`)
- Sessions started with `--disable-slash-commands` don't watch these directories at all

Otherwise, edits to an existing subagent file are picked up within seconds — the next delegation uses the updated definition, no restart needed.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Subagent never gets delegated to | `description` too vague, or missing "use proactively" for an eager-delegation role | Rewrite with concrete trigger phrases using `agent-markdown-best-practices` |
| New subagent invisible after creation | First agent file in a newly-created `agents/` directory | Restart Claude Code |
| "Agent would be spawned with zero tools" error | Every entry in `tools` is misspelled or names a tool unavailable to subagents | Check spelling against [Available tools](frontmatter-reference.md#available-tools) |
| Coordinator can't spawn a specific subagent | `Agent(...)` allowlist on the coordinator's `tools` omits that type | Add the type to the parenthesized list, or use bare `Agent` |
| Two subagents with the same `name` in one directory, only one works | Name collision, undocumented resolution order | Run `/doctor` to find and rename/remove the duplicate |
| Subagent frontmatter hooks never fire | Project folder not yet trusted (workspace-trust dialog) | Accept the workspace trust prompt for that folder |
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall