Agency Agents Beginner’s Guide: Turn Claude Code into a Dream Team with 100+ AI Expert Personas

We all know that writing prompts is a craft. The same Claude model can produce wildly different results when you ask it to “write me a React component” versus “from the perspective of a senior frontend engineer, follow the WCAG 2.1 AA guidelines, and write an accessible virtualized table using TypeScript + React 18.”

Agency Agents exists specifically to solve this pain point. It pre-arranges 16 departments and 100+ AI expert role personas (Frontend Developer, Backend Architect, Security Auditor, Reddit Community Ninja …), along with their setup, workflows, deliverables, and success metrics—so you just activate the relevant role, and the AI automatically switches into “professional mode.”

What’s even better: the repository comes with convert.sh and install.sh. With one click, you can sync the exact same role definitions to 10+ tools—Claude Code, OpenClaw, Cursor, OpenCode, Codex, Gemini CLI, and more—without having to maintain multiple configurations.

In this article, we’ll run it from scratch together, and demonstrate how to activate a role in OpenClaw to complete real requirements.

Project Overview

msitarzewski/agency-agents started as a discussion in a Reddit post—“If you could hire a team of AI employees, what positions would you want?” After months of iteration, it has evolved into a fairly complete library of AI agent roles.:

• 16 departments: engineering, design, marketing, finance, security, sales, testing… covering almost all roles a software company typically needs
• 100+ roles: from Frontend Developer and Backend Architect to roles like Whimsy Injector and Reality Checker—characters with personality “temperature”
• Measurable deliverables: every role specifies success metrics, deliverables, and critical rules—not vague prompts
• Multi-tool compatibility: the same Markdown source file can be converted into formats like Claude Code subagent, OpenClaw workspace, Cursor rules, OpenCode agent, Codex TOML, and more

The biggest difference from a normal prompt template is that here each role has a fully personalized setup (tone, style, memory mechanism) + a business workflow (mission / workflow / deliverables), making it more like a “job description.”

Difficulty / Time / What You’ll Get

• Difficulty: ⭐⭐ (just use the command line—no coding barrier)
• Time: 15–30 minutes (first install + activate a role + complete a real use case)
• Outcome: turn Claude Code / OpenClaw into a multi-role AI team that can be “scheduled on demand,” while keeping professional personas stable over the long run

Target Audience

• Developers who want to boost productivity with AI, but find writing prompts too tedious
• Frontend / Backend / Full-stack / Security / Testing engineers with 1–5 years of experience
• Practitioners already using AI programming tools like Claude Code, Cursor, OpenClaw, Codex, etc.
• Technical leads who want to roll out an “AI collaboration standard” within a team

Core Dependencies and Environment

Complete Project Directory Tree

agency-agents/
├── academic/                       # Academic research directions
├── design/                         # UI/UX design
├── engineering/                    # Engineering (the largest department, 30+ roles)
├── finance/                        # Finance
├── game-development/               # Game development
├── gis/                            # Geographic information
├── marketing/                      # Marketing
├── paid-media/                     # Paid media
├── product/                        # Product
├── project-management/           # Project management
├── sales/                          # Sales
├── security/                       # Security
├── spatial-computing/            # Spatial computing
├── specialized/                    # Specialized experts
├── strategy/                       # Strategy
├── support/                        # Customer support
├── testing/                        # Testing
├── integrations/                   # Multi-tool integration outputs
│   ├── openclaw/                   # OpenClaw workspace (SOUL.md + AGENTS.md + IDENTITY.md)
│   ├── opencode/                   # OpenCode agent (.md + YAML frontmatter)
│   ├── claude-code/                # Claude Code subagent
│   ├── cursor/                     # Cursor rule (.mdc)
│   ├── codex/                      # Codex custom agent (TOML)
│   ├── gemini-cli/                 # Gemini CLI subagent
│   ├── github-copilot/             # GitHub Copilot
│   ├── aider/                      # Aider CONVENTIONS.md
│   ├── windsurf/                   # Windsurf .windsurfrules
│   ├── kimi/                       # Kimi Code CLI
│   ├── qwen/                       # Qwen Code SubAgent
│   └── mcp-memory/                 # MCP long-term memory
├── scripts/
│   ├── convert.sh                  # Role definitions → tool format converter
│   ├── install.sh                  # One-click install to local
│   ├── lib.sh                      # Shared functions
│   └── lint-agents.sh              # Lint role definitions
├── README.md
└── CONTRIBUTING.md

Step-by-Step

Below, we’ll use OpenClaw as the example to demonstrate the full workflow. For other tools, you only need to replace --tool with the corresponding name.

Step 1: Clone the repository

git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

If your network is restricted, you can fork to Gitee / your own GitHub first, then clone:

git clone https://github.com/<your-fork>/agency-agents.git
cd agency-agents

Step 2: See installable departments and roles

install.sh provides a handy “list” mode:

./scripts/install.sh --list teams

You’ll see output like this:

engineering          33 agents
design               12 agents
marketing            18 agents
security              9 agents
testing              11 agents
...

If you only want to install a few departments (e.g., engineering + security), filter using --division later.

Step 3: Generate OpenClaw-format integration files

convert.sh splits the source Markdown into the three files OpenClaw expects: SOUL.md (persona) + AGENTS.md (workflow) + IDENTITY.md (identity):

./scripts/convert.sh --tool openclaw

After a successful run, under integrations/openclaw/ you’ll see 100+ subdirectories:

ls integrations/openclaw/ | head -20
# agency-frontend-developer
# agency-backend-architect
# agency-security-auditor
# agency-reddit-community-ninja
# agency-whimsy-injector
# ...

Each subdirectory looks like this:

agency-frontend-developer/
├── SOUL.md        # Persona: identity, memory, tone, style
├── AGENTS.md      # Business workflow: mission, deliverables, workflow
└── IDENTITY.md    # Identity card: emoji + name + vibe

Step 4: One-click install to OpenClaw

# Install everything (about 100+ roles)
./scripts/install.sh --tool openclaw

# Recommended: pick departments to install (avoid loading too many at once)
./scripts/install.sh --tool openclaw --division engineering,security

The scripts automatically copy the workspace into ~/.openclaw/agency-agents/ and register it with the OpenClaw gateway.

Step 5: Restart the OpenClaw gateway to activate new roles

openclaw gateway restart

Step 6: Activate Frontend Developer in OpenClaw

openclaw chat --agent agency-frontend-developer

Or in the config file, change the default agent to agency-frontend-developer, and OpenClaw will enter that role automatically each time you start.

Step 7: Run a real requirement

We’ll ask the freshly activated Frontend Developer to write an accessible virtualized table component:

openclaw chat --agent agency-frontend-developer <<'EOF'
Write a DataTable component using React 18 + TypeScript, with these requirements:
1. Use @tanstack/react-virtual for virtualized scrolling
2. Meet the WCAG 2.1 AA accessibility standards
3. Support custom rendering for cells
4. Make row click handlers configurable
5. Provide complete runnable code
EOF

You’ll notice the output code style is extremely consistent—because the role definition already “locks in” constraints like “WCAG 2.1 AA,” “memo wrapping,” and “Core Web Vitals optimizations.” We don’t have to repeat these requirements in prompts every time.

Step 8: Cross-tool demonstration (optional)

With the same role definition, converting to Cursor is just one line:

./scripts/convert.sh --tool cursor
./scripts/install.sh --tool cursor --agent frontend-developer,backend-architect

Common Troubleshooting

Q1: install.sh reports permission denied

Usually it means install.sh doesn’t have execute permissions. For macOS / Linux users:

chmod +x scripts/install.sh scripts/convert.sh scripts/lib.sh
./scripts/install.sh --tool openclaw

Windows users: if you’re seeing this error in Git Bash, first confirm the repository was downloaded via git clone (don’t unzip a ZIP archive), and run the scripts using Git Bash.

Q2: OpenClaw shows “agent not found” or “not registered”

In 99% of cases, after installing roles you didn’t restart the gateway:

openclaw gateway restart
openclaw agent list | grep frontend-developer
# Output indicates registration succeeded

If it still doesn’t work, check whether ~/.openclaw/agency-agents/ really contains the file agency-frontend-developer/SOUL.md:

ls ~/.openclaw/agency-agents/agency-frontend-developer/
# You should see SOUL.md  AGENTS.md  IDENTITY.md

Q3: OpenCode installs too many roles, but only shows the first 119

This is a known bug in OpenCode upstream (issue #27988)—at runtime it only registers about 119 subagents, and any extras get silently discarded.

Solution: split installation using --division so the total roles stay within 119:

./scripts/install.sh --tool opencode --division engineering
./scripts/install.sh --tool opencode --division marketing --out ~/.opencode-extra/

When the script detects the count exceeds the threshold, it will emit a warning. You can also do a dry run first:

./scripts/install.sh --tool opencode --division engineering --dry-run

Q4: Role frontmatter missing required fields causes convert to skip

convert.sh skips source files that don’t include the name field. If you forked a role yourself but don’t see it under integrations/openclaw/:

# 1. Check source file frontmatter
head -10 engineering/your-custom-agent.md

# 2. At minimum, include:
#    ---
#    name: Your Agent Name
#    description: One-line description
#    ---

# 3. Re-convert
./scripts/convert.sh --tool openclaw

Q5: Windows: bash script line ending errors

If you copied scripts from a ZIP archive on Windows, the files may have CRLF line endings, and bash will error with something like \r: command not found:

# Option A: use git clone instead of downloading the ZIP
git clone https://github.com/msitarzewski/agency-agents.git

# Option B: convert line endings manually (Git Bash)
dos2unix scripts/*.sh

Q6: Persona conflicts between roles / context bleeding

If you activate Frontend Developer and then Security Auditor within the same session, you may notice the tone from the previous role lingering in the context. This is because most CLI tools inject agents at the “system prompt” level, and switching agents doesn’t automatically clear the conversation history.

Solution:

# Switch agent after starting a new session
openclaw chat --new-session --agent agency-security-auditor

Or enable “switching agents archives old sessions automatically” in your OpenClaw configuration.

Further Reading / Advanced Directions

1. Custom role templates

engineering/engineering-frontend-developer.md is a great template. Try forking it and renaming to something like engineering-frontend-developer-chinese.md:

---
name: Frontend Engineer (Chinese Version)
description: A frontend engineer specialized in React/Vue, UI implementation, and performance optimization; output Chinese comments
color: cyan
emoji: 🖥️
vibe: Output in Chinese, follow ByteDance frontend conventions
---

# Frontend Engineer (Chinese Version)

You are a **frontend engineer**, focused on modern web technologies……

## 🧠 Your identity and memory
- Role: expert in modern web applications and UI implementation
- Personality: detail-oriented, performance-sensitive, user-first
- Memory: remember common UI patterns and accessibility best practices

Then run ./scripts/convert.sh --tool openclaw, and the new role will appear under integrations/openclaw/.

2. Add long-term memory to roles using MCP-Memory

Under integrations/mcp-memory/, there’s a set of MCP memory server configurations. After activation, roles can preserve preferences across sessions (for example: “this team prefers pnpm over npm”). See mcp-memory/README.md in the repository for configuration details.

3. Multi-agent collaboration workflows

Single-agent performance is already impressive, but what’s even more exciting is orchestrating them into collaboration chains. For example:

Requirement → [Product Manager] splits tasks
             → [Frontend Developer] + [Backend Architect] implement in parallel
             → [Code Reviewer] auto reviews
             → [QA Test Engineer] runs tests
             → [Technical Writer] generates PR descriptions

OpenClaw’s built-in “workflow” feature can chain these roles together—see the OpenClaw official documentation.

4. Reduce calling costs

As mentioned earlier, the expert roles in Agency Agents are backed by top-tier models, and the long-term cost isn’t low. If you want to run the same models at official half price, you can directly integrate Defapi (the “Core Dependencies” section above has detailed information)—no code changes required.

---

This article is written based on the current main branch of msitarzewski/agency-agents (commit date up to 2026-06-13). The repository may later add departments or adjust script interfaces; it’s recommended to run git pull before you start to sync the latest version.