Digital Strategy Review | 2026
Claude Code Top 10 Highlights 06 | Agent Definition is Not a Prompt, But a Runtime Spec
By Uncle Fruit · Reading Time / 8 Min
Editor’s Note
Many products claim to support “custom agents,” but what they actually provide is often just a system prompt. This article is worth a close read because Claude Code has pushed the concept of agent definition a step further, elevating it into a full-fledged runtime specification.
01
Agent Definition is Not a Prompt, But a Runtime Spec
When many products say they “support custom agents,” what they are actually giving you is:
• A name • A system prompt
Claude Code’s understanding of Agents is significantly deeper. Here, an agent definition is not just a simple prompt; it is more like a runtime specification.
The core implementation is concentrated in:
• src/tools/AgentTool/loadAgentsDir.ts
• src/tools/AgentTool/builtInAgents.ts
• src/tools/AgentTool/built-in/*
02
I. What Can a Claude Code Agent Definition Describe?
In Claude Code, an agent definition can include:
• agentType
• whenToUse
• tools
• disallowedTools
• skills
• mcpServers
• hooks
• model
• effort
• permissionMode
• maxTurns
• background
• initialPrompt
• memory
• isolation
• omitClaudeMd
This set of fields illustrates an important fact:
An Agent in Claude Code is not a “prompt persona,” but a “runtime object template.”
By elevating the persona to a specification, Claude Code allows built-in and custom agents to share the exact same execution path.
03
II. Why This Is Far Superior to Custom Prompts
1. It Controls Tool Boundaries
A standard prompt can only “suggest” that a model shouldn’t misuse tools. An agent definition, however, can truly prune the tool surface.
For example: • The Explore Agent is prohibited from editing. • The Plan Agent remains read-only. • The Verification Agent emphasizes verification over modification.
These are not behavioral suggestions; they are system boundaries.
2. It Controls Execution Modes
Agents aren’t just different in “speaking style”; they can also: • Execute in the background by default. • Enable memory. • Specify isolation. • Specify permission modes.
This means agent differentiation no longer stops at the prompt tone level but enters the system execution level.
3. It Controls Dependency Capabilities
Through fields like mcpServers, skills, and hooks, an agent definition can declare:
• Which capabilities it depends on at startup.
• Which additional mechanisms it requires at runtime.
This upgrades the Agent from a “persona template” to a “capability template.”
04
III. Why Claude Code Can Support Agents from Multiple Sources Simultaneously
Because it designed the agent definition as a unified configuration object, it naturally supports:
• Built-in agents • User agents • Project agents • Policy agents • Plugin agents
It even supports override priorities.
This is critical. Once you stop hardcoding agents and instead abstract them into a unified spec, the system can stably support:
• Personal customization • Project constraints • Organizational policies • Plugin extensions
This is true platform capability.
05
IV. Built-in Agents Demonstrate the Power of This Spec
Explore Agent
It is not a prompt that “knows how to search,” but a runtime role that is: • Read-only • Focused on rapid searching • Restricted from editing tools • Configurable with model strategies
Plan Agent
It is not a prompt that “knows how to plan,” but a runtime role that is: • Read-only • Focused on architectural analysis • Required to output critical files
Verification Agent
It even carries strong behavioral constraints: • Must run commands • Must paste output • Must provide a verdict • Prohibited from modifying the project directory
This is already very close to an “executable audit rule” rather than just a prompt.
06
V. Why I Call It a Runtime Spec
From a software engineering perspective, an agent definition in Claude Code is similar to:
• A container image’s runtime configuration • A Kubernetes workload spec • A CI job’s execution declaration
Because it determines: • Which model to use • What it can do • What it cannot do • The context in which it runs • Whether to persist memory • Whether to bring additional dependency capabilities
The prompt is just one item among many. This is why I believe this layer is particularly worth studying.
07
VI. What Is the Cost?
Of course, this design also increases system complexity.
1. Agents are no longer just text assets
You need to maintain a full set of runtime fields, not just a prompt file.
2. Requires more robust loading, validation, and override logic
The complexity of loadAgentsDir.ts in Claude Code is the price paid for this capability.
3. Must manage plugin and policy sources very carefully
Because agents now have real execution capabilities, override sequences and security boundaries must be crystal clear.
However, the trade-off for this complexity is that Agents truly evolve from “content assets” into “system assets.”
08
VII. Understanding the Highlight in One Diagram
09
VIII. Conclusion
The greatest strength of Claude Code’s Agent Definition is that it moves the “Agent” beyond role-playing in the world of prompts and into the realm of runtime engineering.
The significance of this step is immense:
• Persona boundaries are clearer. • Extension methods are more unified. • Plugins and policies are easier to integrate. • Agent behavior is easier to govern.
In summary:
In Claude Code, an Agent is a declaratively defined execution role, not a function call wearing a prompt disguise.