How to Configure 186 Expert Personas for Your AI Agent Workspace

When working with a general-purpose AI agent, the model’s underlying capability is only the foundation. What truly determines output quality also includes the role definition, task boundaries, workflow, communication style, and how the agent interprets user needs.

If an agent always runs on a single generic persona, it can usually handle many kinds of tasks—but it often falls short in professionalism, stability, and execution consistency. Code review, market analysis, project management, and content planning all demand different thinking paths, evaluation criteria, and output formats. Rather than pasting a long prompt into every conversation, it makes far more sense to bake these rules into the agent’s workspace configuration.

There are already open-source expert persona collections that bundle 186 role templates for different work scenarios. These templates are not simplistic “you are an expert in X” prompts. They typically include role positioning, scope of responsibility, working methods, communication habits, delivery standards, and common task workflows. Configured properly, they can turn a general-purpose agent into a specialist with clear professional boundaries.

1. The Core Files in an Agent Workspace

In most agent workspace designs, the agent’s behavior and identity are described through several Markdown files. Three of them matter most.

AGENTS.md: Working Rules and Execution Boundaries

Think of AGENTS.md as the agent’s operating manual—it defines how the agent should get work done. It can cover:

• The basic workflow for handling tasks;
• Whether requirements need to be clarified first;
• The structure and format of outputs;
• Operating conventions for code, documents, or data;
• Which actions require user confirmation;
• How to self-check, review, and explain errors;
• What to do when the agent is uncertain.

For example, a technical-architecture persona might require the agent to analyze system boundaries first, identify key constraints next, and only then propose a layered design. A content-planning persona, by contrast, might require identifying the target audience first, then deciding on topic, structure, and tone.

In short, AGENTS.md defines how the agent works.

IDENTITY.md: Role Identity and Professional Positioning

IDENTITY.md explains who the agent is and in what capacity it collaborates with the user. It can describe:

• The expert name or role title;
• Primary areas of expertise;
• Who it serves;
• An abstract description of professional experience;
• The types of tasks it is suited for;
• Questions it should not handle;
• The collaboration relationship with the user.

The value of the identity file is establishing a stable sense of role. Analyzing the same business dataset, a data analyst will focus on metrics, trends, and anomalies, while a product consultant will care more about user needs, feature priorities, and business value. Different identities produce different analytical focus.

SOUL.md: Personality, Style, and Values

SOUL.md is the agent’s underlying personality setting—it determines how the agent thinks and communicates. Common settings include:

• Whether the language style is rigorous, concise, or Socratic;
• Whether it proactively points out risks;
• Whether it leads with conclusions;
• How it corrects inaccurate information;
• Whether it tends to offer multiple alternatives;
• How it phrases uncertain conclusions;
• Whether it emphasizes executability and implementation cost.

If AGENTS.md defines how to work and IDENTITY.md defines who the agent is, SOUL.md defines how it expresses itself and behaves. Only the three combined form a complete expert persona.

2. What 186 Personas Actually Means

To be clear: 186 personas does not mean 186 independently running models, nor does it mean stacking all 186 configurations into a single workspace.

It’s better understood as a selectable library of role configurations, where each persona corresponds to a specific professional direction, such as:

• Software development and code review;
• System architecture and technical planning;
• Data analysis and reporting;
• Project management and process design;
• Product requirements and user research;
• Market research and competitive analysis;
• Brand content and communication planning;
• Instructional design and knowledge organization;
• Workflow automation and efficiency optimization;
• Risk identification and decision support.

When a workspace has only one primary agent, you typically pick one persona as the active configuration. In other words, you cannot overlay all 186 personas onto the same set of AGENTS.md, IDENTITY.md, and SOUL.md files.

The reason is simple: personas can conflict with each other. One role may demand extremely terse answers while another requires full argumentation; one emphasizes rapid execution while another emphasizes careful confirmation. Merge them all, and the result usually isn’t an “all-capable expert” but an unstable hybrid with rules overriding one another.

3. Installing and Swapping Personas for a Single Agent

For a setup with one primary agent, the configuration process usually looks like this.

Step 1: Back Up Your Existing Workspace Files

Before changing any configuration, back up the current core files—at minimum:

AGENTS.md
IDENTITY.md
SOUL.md

Copy them to a dedicated backup directory, or add a date suffix to the filenames. This ensures you can restore the original configuration if the new persona doesn’t meet expectations.

Step 2: Choose a Persona That Matches Your Task Goals

Don’t pick a persona based on its name alone—judge it against your actual work objectives. For example:

• If you mainly write and maintain code, prioritize roles that emphasize engineering standards, testing awareness, and maintainability;
• If you mainly work with business data, choose roles that value metric definitions, data provenance, and the boundaries of conclusions;
• If you mainly produce content, focus on topic selection, audience, structure, and writing style;
• If you mainly coordinate projects, focus on task breakdown, dependencies, risks, and progress management.

The closer the persona is to your actual tasks, the more consistent the output tends to be.

Step 3: Copy the Three Core Files

Once you’ve chosen a persona, copy its three core files into the current workspace:

AGENTS.md
IDENTITY.md
SOUL.md

If files with the same names already exist, confirm before overwriting. Rather than deleting the old files outright, move them to the backup directory first, then place the new configuration in.

Step 4: Check for Internal Consistency

After installation, quickly review the three files for contradictory rules. Pay attention to:

• Whether role names are consistent;
• Whether the area of expertise matches;
• Whether output language and format conflict;
• Whether there are duplicated or opposing behavioral requirements;
• Whether rules meant for a different environment were carried into this workspace;
• Whether there are overpromises or unrealistic capability claims.

If a persona package is long, you can also tailor it to your needs. A persona is not an immutable program—you can keep the core positioning while adjusting the title, output format, communication tone, and approval rules.

Step 5: Restart the Agent Gateway or Service

Once workspace files change, a running agent service won’t necessarily reload the configuration automatically. After replacing files, you usually need to restart the gateway, session service, or the relevant process.

After restarting, validate with a simple task. Ask the agent to:

1. State its current identity and areas of expertise;
2. Complete a small task in the expected format;
3. Demonstrate how it handles uncertainty;
4. Show whether it respects the constraints in the configuration files.

If the output still reflects the old persona, check the file paths, file permissions, the service’s startup directory, and cache state in that order.

4. Configuring Personas in a Multi-Agent Setup

If your system uses a multi-agent architecture, the 186 personas become far more useful.

In a multi-agent configuration, each sub-agent typically has its own workspace. For example, the main workspace might handle everyday conversation, while separate sub-agents handle engineering, data, content, and project management. Workspace names are usually distinguished by role or instance, for example:

workspace-main
workspace-development
workspace-data
workspace-content

Each workspace independently maintains its own:

AGENTS.md
IDENTITY.md
SOUL.md

This means different sub-agents can run different expert personas:

• The main agent understands requirements, dispatches tasks, and consolidates results;
• The development agent handles code design, debugging, and technical documentation;
• The data agent handles metric analysis, data interpretation, and report generation;
• The content agent handles topic selection, writing, and editing;
• The project agent handles plan breakdown, progress tracking, and risk alerts.

This approach doesn’t blend multiple roles into one agent. Instead, it separates responsibilities into multiple cooperating specialist nodes. Each node has a clear boundary, and the main agent routes tasks and consolidates results based on task type.

5. Common Mistakes When Configuring Personas

1. Concatenating All Personas into One File

This is the most common error. Different expert roles can have conflicting goals and rules, and forcing them together undermines behavioral stability. The better approach: one workspace, one primary role—use multiple independent workspaces to host multiple roles in a multi-agent setup.

2. Replacing Only the Identity File

If you update IDENTITY.md but keep the original AGENTS.md and SOUL.md, the agent may claim to be a specialist while actually working the way the old role did. When installing a persona, replace all three core files together.

3. Ignoring Existing User Preferences and Tool Rules

Files like USER.md and TOOLS.md typically describe user preferences, available tools, environment constraints, and operating habits. Don’t casually overwrite these supporting files when swapping personas, or the agent may forget language preferences, path conventions, or tool usage rules.

4. Over-Reliance on Persona Configurations

Persona files improve task organization and output style, but they can’t replace real data, professional judgment, or human review. For production environment changes, financial decisions, private information, legal matters, or security-sensitive operations, you still need confirmation mechanisms and human review processes.

5. Skipping Version Management

Bring persona configurations under version control, and at minimum record:

• The expert role currently in use;
• When configuration files were modified;
• Why they were modified;
• The applicable task scope;
• Known limitations;
• Validation results.

This makes it much easier to diagnose issues in team collaboration or long-running deployments, and it makes mature configurations reusable across workspaces.

6. Going Further: From Persona Switching to Role Governance

If you want to run expert personas in production, consider building a role governance mechanism.

First, define clear input and output boundaries for each role. For example, the data agent may only analyze and interpret—it must not modify business data directly; the development agent may propose code changes, but high-risk operations must go through confirmation.

Second, design standard task templates for each role. Templates can specify input fields, processing steps, output formats, and acceptance criteria, reducing instability caused by free-form improvisation.

Third, establish a uniform handoff format across roles. For instance, requiring each sub-agent to output “conclusion, evidence, risks, items needing confirmation, and next-step recommendations” makes it much easier for the main agent to consolidate results from multiple experts.

Finally, regularly evaluate how each persona performs in practice. Track accuracy, stability, executability, communication overhead, and the number of human corrections, and keep refining the files.

Ultimately, the core value of 186 expert personas isn’t the number itself—it’s that they give agents reusable, switchable, and composable professional working methods. A single agent should pick one clear role, while a multi-agent setup can build a specialist team through independent workspaces. With proper file isolation, rule validation, version backups, and restart verification, a general-purpose agent can evolve from “something that can chat about anything” into “a professional assistant that reliably completes specific work.”