A while ago I asked myself: “Am I sleeping on custom agents?”
The answer turned out to be no, but I did learn about why you might want to use them.
Why do people create custom agents?
Developers and AI users have probably seen the phrase “You are an expert coder” or a similar one being thrown around for prompts.
It makes a lot of sense when thinking from a traditional workspace. You hire a bunch of people specialized in certain tasks: you need various types of programmers, designers, copywriters, marketeers, managers, etc.
But that line of thinking does not have much value with custom agents.
If your custom agent is basically a big prompt, then your custom agent should probably be a skill or a markdown document. There is no meaningful difference between instructions in the body of a custom agent vs a skill. It’s all just context. Just make sure that the agent is able to invoke the skill by not setting disable-model-invocation: true.
The actual use cases for custom agents
Custom agents are just markdown files, right? Well, mostly, but not really.
I was inclined to say that most of the value comes from the ability to parallel work where each subagent has its own context window, which lets you do a bunch of work in the subagent while only exposing the relevant conclusions to the main agent thread. But that is actually more of a point for subagents, not custom agents.
The real value from custom agents does not come from a large prompt inside that markdown file. It comes from the configuration around the custom agent.
Custom agents can be configured to only have access to specific tools it can call.
You can also specify the permission level. In Claude Code those permission options are: default, acceptEdits, auto, dontAsk, bypassPermissions, and plan.
And you can configure a predetermined set of skills the agent will inject into a subagents context window, which might be useful.
With custom agents you can also specify a specific model and reasoning level. This might be good for certain types of work. And if you’re using a cheaper model then it can save you some money too. Maybe you can even point it at a local LLM.
Good custom agent prompts are lean
Everything you put in a custom agent is something that is not reachable when the custom agent is not being used.
My recommendation for what you should do instead is to create a type of docs/ directory or a set of skills your custom agent can invoke.
One of the best parts about this is that it makes your project more coding agent provider agnostic. Skills are more easily transferred to other coding agents as well (by symlinks or copying) for when you want to switch between Claude, ChatGPT, Pi, OpenCode, or other agent harnesses.
When you should delete your custom agent
If you do not use any special configurable permissions, tools, or other settings, then you can probably delete your custom agent safely and move its instructions elsewhere.
When the value from your custom agent is mostly the prompt, then it could just as easily be a skill or another type of document in your project. This makes it reachable for any AI agent, not just the specific custom agent. And it also makes it more visible for the humans working on your project.
If your intent is to have a set of instructions only available in a custom agent, I would still consider using a skill instead.
Stop making this mistake with custom agents
Opening new agent threads and telling Claude “do this task using this specific custom agent,” then you might be losing out on main thread context that was lost in the subagent. This is because subagents do not share memory or chat history with the main agent.
Conclusion
When your custom agents are just a big prompt, then you probably do not need custom agents. If you know what you are doing, then you might be able to get a lot of value out of subagents. Most of that value comes from configuration options, not the custom agent prompt.