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
Foreword
Many products claim to support custom Agents, but what they actually provide is often just a system prompt. This article is worth a close look because Claude Code has pushed the Agent definition a step further, turning it directly into a 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 Actually 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 role to a specification, Claude Code allows built-in and custom Agents to share the 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 not misuse tools. An Agent definition, however, can truly prune the tool surface.
For example:
• The Explore Agent forbids 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 are not just different in “speaking style”; they can also:
• Execute in the background by default.
• Enable memory.
• Specify isolation.
• Specify permission modes.
This means the differences between Agents no longer stop at the prompt tone level but enter the system execution layer.
3. It Controls Dependency Capabilities
Through fields like mcpServers, skills, and hooks, an Agent definition can declare:
• Which capabilities to depend on at startup.
• Which additional mechanisms are required at runtime.
This upgrades the Agent from a “personality 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 also 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 search
• Restricted from editing tools
• Configurable in model strategy
Plan Agent
It is not a prompt that “knows how to plan,” but a runtime role that is:
• Read-only
• Geared toward 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
• Forbidden 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 K8s workload spec
• A CI job’s execution declaration
Because it determines:
• Which model to use
• What it can do
• What it cannot do
• In what context it runs
• Whether to persist memory
• Whether to carry additional dependency capabilities
The prompt is just one item among them.
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 precisely the cost of this approach.
3. Plugin and policy sources must be managed very carefully
Because Agents now have real execution capabilities, override order and security boundaries must be clear.
However, the trade-off for this complexity is that Agents truly evolve from “content assets” into “system assets.”
08
VII. Understanding This Highlight in One Diagram
09
VIII. Conclusion
The greatest strength of Claude Code’s Agent Definition is that it stops “Agents” from being mere role-playing characters in the world of prompts and brings them into the runtime engineering system.
The significance of this step is profound:
• Role 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.