Agent Definitions and Personas

One-Line Summary: An agent definition is the file that declares a sub-agent's identity (system prompt + tools + model + termination) and makes it reusable across sessions; the persona is the part of that file that captures voice, role, and decision-making style — together they turn ad-hoc role prompts into versioned, composable artifacts.

Prerequisites: Sub-agents as primitives, role-based specialization

What Is an Agent Definition?

A role prompt baked into a single conversation is unmodular: it is gone when the conversation ends, it cannot be reused in another project, and it cannot be improved by anyone other than the original author. An agent definition — a markdown file with frontmatter declaring tools and a system prompt as the body — is the durable, shareable, version-controllable form of that role.

In Claude Code:

---
name: security-reviewer
description: Reviews code for security vulnerabilities; defers style and correctness to other reviewers
tools: [Read, Grep, Bash]
model: claude-opus-4-7
---
 
You are a security reviewer. For each file, identify:
1. Injection vulnerabilities (SQL, command, prompt)
2. Authentication/authorization gaps
3. Secret leakage
4. Unsafe deserialization
...

That file is a complete sub-agent. It can be invoked by name (Task(subagent_type="security-reviewer")), shipped in a plugin, copied to another project, or evolved over time.

The persona is the editorial layer of the system prompt — voice, level of caution, escalation behavior. A good persona makes the sub-agent's output recognizable and predictable. A bad persona makes the sub-agent feel like a vague label.

How They Work

Most harnesses use the same shape:

• Frontmatter declares mechanics: name, description, tools, model, sometimes max_steps.
• Body is the system prompt: defines persona, scope, decision rules, output format.

When invoked, the harness:

1. Spawns a fresh agent loop.
2. Sets system prompt to the body.
3. Configures tool access per the frontmatter.
4. Runs until the agent terminates or hits a budget.

Ruflo extends the format with metadata for swarm membership, trust scores, and federation eligibility. CrewAI uses YAML instead of markdown but the shape is similar.

Why It Matters

Agent definitions are how a team accumulates institutional knowledge. The first time you write a security reviewer prompt, you tweak it for an hour. The second time the team needs one, they should grab the definition file, not redo the work. Over a few months, a project accumulates a library of well-tuned definitions that act like internal "team members" — staff-security-engineer.md, migrations-specialist.md, release-coordinator.md.

The second-order effect: definitions become a cross-team artifact. The 100+ agent definitions ruflo ships are a public reference for what good agent personas look like. Reading them is one of the highest-leverage learning activities for harness builders.

Key Technical Details

• Description matters more than you think: It is what the parent agent reads when deciding whether to spawn this sub-agent. Vague descriptions ("helps with code") lead to wrong selection; sharp descriptions ("reviews TypeScript code for race conditions in async/await") lead to correct selection.
• Tool list should be minimal: Sub-agents are most reliable when their tool surface is small enough to memorize. If a definition declares 20 tools, it likely should be split.
• Persona discipline: Avoid "helpful assistant" generic personas. The point of a definition is specialization.
• Output contract: Best definitions specify the format of the final message ("Return a JSON object with findings: [{file, line, severity, message}]").
• Termination criterion: Without one, sub-agents over-explore. A good definition includes "stop when you have identified at least one finding or determined there are none."
• Versioning via git: Agent definitions evolve. Treat them like any other code artifact — review changes, write tests against expected outputs.

How Harnesses & Frameworks Implement This

Connections to Other Concepts

• sub-agents-as-primitives.md — The runtime side.
• role-based-orchestration.md — How definitions compose into a topology.
• permission-and-tool-scoping-primitives.md — The tools field is a security decision.
• plugin-and-marketplace-systems.md — How definitions ship.
• ../../ai-agent-concepts/05-multi-agent-systems/role-based-specialization.md — Foundational coverage.

Further Reading

• ruvnet, ruflo agents — Read 5–10 of these to internalize the form.
• Anthropic, Claude Code sub-agent definitions documentation.