Skip to content

NetFabric/NetFabric.Numerics / .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.

## 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 → [writing-style.md](writing-style.md) |
| 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