Agency Agents — User Guide

1. Quick Start

Agency Agents is a curated library of 200+ AI agent prompt definitions organized by professional domain. Each agent is a standalone markdown file with YAML frontmatter and structured instructions that give an AI coding assistant a specialized persona, workflow rules, and deliverable templates.

Key features:

• 200+ agent definitions across 15 professional categories
• Compatible with 13 AI coding tools: Claude Code, Cursor, GitHub Copilot, Aider, Windsurf, OpenCode, Gemini CLI, Antigravity, OpenClaw, Kimi, Qwen, and more
• NEXUS strategy framework with 7-phase playbooks, runbooks, and coordination templates
• MCP memory integration for persistent agent context across sessions
• Chinese (zh-CN) localization for agent names and descriptions
• Shell installer that auto-detects your tools and copies agent files into place
• Multi-agent workflow examples for startup MVPs, marketing campaigns, incident response, and more

Prerequisites: Git and a compatible AI coding tool.

Install and activate:

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

Tip

install.sh auto-detects which supported AI tools are installed on your system and copies agent files to each tool's agent directory. You can also manually copy individual .md files into your tool's config path.

What to try next:

• Browse the agent catalog by category below
• Read strategy/QUICKSTART.md for a guided introduction to the agent ecosystem
• Try a multi-agent workflow from examples/

2. Installation

System Requirements

Installation Methods

Installer (recommended)

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

Manual copy

git clone https://github.com/msitarzewski/agency-agents.git
# Copy individual agent .md files to your tool's agent directory

Post-Install Verification

After running the installer, confirm agents are in place by listing your tool's agent directory. You should see .md files named after each agent role:

ls ~/.github/agents/ 2>/dev/null || ls ~/.cursor/agents/ 2>/dev/null

engineering-backend-architect.md
engineering-senior-developer.md
marketing-growth-hacker.md
...

Important

Agent files are plain markdown — no build step, no compilation, no runtime dependencies. They work immediately after copying into your tool's agent directory.

Supported AI Tool Integrations

Each supported tool has a dedicated README under integrations/ explaining tool-specific setup:

Tip

Check each integration's README for the exact directory path where agent files should be placed. Paths vary by tool — for example, GitHub Copilot uses ~/.github/agents/ while Cursor uses its own rules directory.

3. Configuration

Agent File Format

Every agent is a self-contained markdown file. The YAML frontmatter defines identity metadata; the body contains the full agent instructions.

---
name: Senior Developer
description: Premium implementation specialist - Masters Laravel/Livewire/FluxUI, advanced CSS
color: green
emoji: 💎
vibe: "Premium full-stack craftsperson — Laravel, Livewire, Three.js, advanced CSS."
tools: WebFetch, WebSearch, Read, Write, Edit
---

The body after the closing --- follows a consistent structure: identity/persona, core mission, critical rules, deliverables/templates, and domain-specific context. See the Admin Guide for the full anatomy.

Customizing Agents

Modify any agent file to suit your project:

1. Adjust the persona — edit the identity and personality sections to match your team's tone
2. Add project context — append project-specific rules, file paths, or coding standards
3. Restrict scope — remove capability sections that don't apply
4. Combine agents — merge sections from multiple agents for a hybrid specialist

Note

Modifications are local to your clone. To contribute changes upstream, see CONTRIBUTING.md (also available in Chinese at CONTRIBUTING_zh-CN.md).

Chinese Localization

The scripts/i18n/ directory provides Chinese (zh-CN) localization covering 150+ agent names and descriptions:

.\scripts\i18n\localize-agents-zh.ps1

This PowerShell script reads scripts/i18n/agent-names-zh.json and rewrites the name and description frontmatter fields in your installed agent files. Default targets: ~/.github/agents/ and ~/.copilot/agents/.

To target a custom directory:

.\scripts\i18n\localize-agents-zh.ps1 -TargetDirs @("C:\my\custom\agents")

Warning

The localization script modifies agent files in-place. Back up your agent directories before running if you want to preserve the English originals.

For full configuration reference, see the Admin Guide.

4. Core Usage

Agent Catalog by Category

Agents are organized into 15 professional domains. Each category is a directory containing specialized agents as .md files.

Engineering (29 agents)

The largest technical category, covering the full software development lifecycle:

Marketing (30 agents)

The most populated category, with both global and China-market-specific specialists:

Specialized (41 agents)

Industry-specific and cross-functional roles spanning legal, healthcare, finance, compliance, and more:

Game Development (20 agents)

Organized by engine with cross-engine specialists:

Other Categories

Note

The testing and scripts directories are classified as supplementary. Testing agents validate output quality; scripts handle installation, conversion, linting, and localization.

Using an Agent

The general workflow for any AI tool:

1. Choose an agent from the category matching your task
2. Read the agent file to understand its persona, rules, and deliverables
3. Load it into your AI tool — either via install.sh or manual copy to the tool's agent directory
4. Reference the agent using whatever activation method your tool supports (e.g., @agent-name in some tools, or loading as system prompt)
5. Interact naturally — the agent's instructions shape the AI's expertise, tone, and output format

Tip

Agents work best when loaded as persistent system prompts rather than one-off paste-ins. This lets the agent maintain its persona across your entire session.

The NEXUS Strategy Framework

The strategy/ directory provides a coordination layer for multi-agent workflows:

MCP Memory Integration

The integrations/mcp-memory/ directory adds persistent memory to any agent via the Model Context Protocol.

Required MCP memory server tools:

Setup:

./integrations/mcp-memory/setup.sh

The setup script checks for MCP client configs at ~/.config/claude/mcp.json, ~/.cursor/mcp.json, and .mcp.json, then guides you through connecting your preferred MCP-compatible memory server.

Important

The MCP memory integration is server-agnostic — you must install and configure your own MCP-compatible memory server separately. The setup script configures the client connection but does not install a server.

See integrations/mcp-memory/backend-architect-with-memory.md for a complete example of an agent definition with memory integration.

5. Common Tasks

Set Up a Multi-Agent Workflow for a Startup MVP

Goal: Use the NEXUS playbooks and multiple agents to take a product from idea to launch.

Steps:

1. Read strategy/EXECUTIVE-BRIEF.md for the ecosystem overview
2. Start with strategy/playbooks/phase-0-discovery.md to validate your idea
3. Progress through phases 1–6 sequentially, activating the relevant specialist agents at each phase (e.g., Backend Architect during Phase 3 Build, SRE during Phase 6 Operate)
4. Use strategy/coordination/handoff-templates.md for structured transitions between agents
5. Use strategy/coordination/agent-activation-prompts.md for ready-made activation prompts

Reference: See examples/workflow-startup-mvp.md and strategy/runbooks/scenario-startup-mvp.md for complete walkthroughs.

Coordinate an Incident Response

Goal: Manage a production incident with specialized agents.

Steps:

1. Load engineering/engineering-incident-response-commander.md as primary coordinator
2. Activate SRE, Backend Architect, and Security Engineer as supporting agents
3. Follow strategy/runbooks/scenario-incident-response.md
4. Use handoff templates for structured transitions between diagnostic and remediation phases

Launch a Multi-Channel Marketing Campaign

Goal: Plan and execute a campaign across platforms.

Steps:

1. Start with strategy/runbooks/scenario-marketing-campaign.md
2. Activate channel agents: TikTok Strategist, LinkedIn Content Creator, SEO Specialist
3. Use Content Creator for editorial calendar and cross-platform coordination
4. For China-market campaigns, combine China Market Localization Strategist with Douyin, Xiaohongshu, and WeChat agents

Build a Game with Multi-Agent Support

Goal: Set up agents for a game development project.

Steps:

1. Choose your engine directory: game-development/unity/, game-development/unreal-engine/, game-development/godot/, or game-development/roblox-studio/
2. Load engine-specific agents (e.g., Unity Architect, Unity Shader Graph Artist)
3. Add cross-engine agents: Game Designer, Level Designer, Narrative Designer, Technical Artist, Game Audio Engineer
4. For 3D asset pipeline work, add Blender Addon Engineer
5. Use Studio Producer and Studio Operations from project-management/ for production management

Deliver an Enterprise Feature

Goal: Follow a structured process for enterprise feature development.

Steps:

1. Follow strategy/runbooks/scenario-enterprise-feature.md
2. Load Product Manager for requirements and prioritization
3. Load Software Architect for system design
4. Load Senior Developer and Code Reviewer for implementation
5. Load the relevant Testing agents for quality assurance

Localize Agents to Chinese

Goal: Translate agent frontmatter for Chinese-speaking teams.

Prerequisites: PowerShell (Windows) or PowerShell Core (macOS/Linux).

Steps:

1. Install agents to your tool's agent directory first
2. Run the localization script:

   .\scripts\i18n\localize-agents-zh.ps1
   

3. Default targets: ~/.github/agents/ and ~/.copilot/agents/
4. Custom target:

   .\scripts\i18n\localize-agents-zh.ps1 -TargetDirs @("C:\my\custom\agents")
   

5. Reload your AI tool's window to pick up changes

Note

The localization covers 150+ agent name/description mappings in agent-names-zh.json. Agents not in the mapping file are left unchanged.

Add Memory to Any Agent

Goal: Give an agent persistent context across sessions using MCP.

Steps:

1. Run ./integrations/mcp-memory/setup.sh
2. Install and configure your chosen MCP-compatible memory server
3. Open the agent file you want to enhance
4. Add a Memory Integration section following the pattern in integrations/mcp-memory/backend-architect-with-memory.md
5. The pattern adds remember, recall, rollback, and search tool usage to the agent prompt

Use Workflow Examples

The examples/ directory provides complete multi-agent workflow demonstrations:

6. Troubleshooting

Agent persona is ignored or has no effect

Cause: The agent file is not loaded correctly into your AI tool's configuration, or the tool doesn't support system-prompt-level agent instructions.

Solution:

1. Verify the file is in the correct directory for your tool (check the integration README under integrations/<tool>/README.md)
2. Ensure the full file contents — both YAML frontmatter and the entire body — are loaded
3. Restart or reload your AI tool window after adding agent files
4. Confirm no higher-priority system prompt overrides the agent instructions

Prevention: Always follow the tool-specific integration guide.

install.sh doesn't detect my AI tool

Cause: The tool may not be installed in a standard location, or its config directory doesn't exist yet.

Solution:

1. Create the tool's agent directory manually (consult the integration README for the path)
2. Copy agent .md files manually into that directory
3. Re-run install.sh after creating the directory

Prevention: Install and run your AI tool at least once before running the installer, so its config directory exists.

Localization script reports "Skip (not found)"

Cause: The target agent directory doesn't exist because agents haven't been installed there yet.

Solution:

1. Install agents to the expected directory first
2. Or specify a custom target directory:

   .\scripts\i18n\localize-agents-zh.ps1 -TargetDirs @("path\to\your\agents")
   

Prevention: Install agents before running localization.

MCP memory setup doesn't find config

Cause: No MCP client configuration file exists at the checked paths (~/.config/claude/mcp.json, ~/.cursor/mcp.json, .mcp.json).

Solution:

1. Create the MCP config file for your tool manually
2. Add your memory server entry:

   {
     "mcpServers": {
       "memory": {
         "command": "your-mcp-memory-server",
         "args": []
       }
     }
   }
   

3. Re-run ./integrations/mcp-memory/setup.sh to verify

Prevention: Configure your MCP client before running the memory setup.

Warning

The MCP memory integration requires a running MCP-compatible memory server. The setup script only configures the client connection — it does not install or start a server.

Security: Hidden Unicode characters in agent files (GitHub Issue #478)

Cause: Unicode soft hyphens (U+00AD) were found in 2 agent files, creating a potential prompt injection vector.

Solution:

1. Check for hidden Unicode characters:

   grep -rP '\xC2\xAD' *.md
   

2. Remove any soft hyphens found
3. Review agent file contents for unexpected invisible characters

Prevention: Run scripts/lint-agents.sh periodically to catch formatting issues.

Caution

Agent files are consumed directly by LLMs as system prompts. Hidden Unicode characters can alter model behavior in unexpected ways — always audit agent files from untrusted sources.

Security: Hardcoded credentials in agent files (GitHub Issue #477)

Cause: The testing/testing-api-tester.md and testing/testing-performance-benchmarker.md agents contained example credentials.

Solution:

1. Replace any credential-like strings with obvious placeholders (YOUR_API_KEY_HERE)
2. Review agent files in testing/ for credential patterns

Prevention: Never put real API keys, passwords, or secrets in agent definition files.

7. FAQ

Q: What AI tools work with these agents?

Any AI tool that accepts markdown system prompts or custom instructions. The repo includes integration guides for 13 tools (Claude Code, Cursor, GitHub Copilot, Aider, Windsurf, OpenCode, Gemini CLI, Antigravity, OpenClaw, Kimi, Qwen, plus MCP Memory), but the agent files are standard markdown — any LLM-based assistant can use them.

Q: Can I use multiple agents at the same time?

Yes. The strategy/coordination/ directory provides handoff templates and activation prompts for multi-agent workflows. The examples/ directory contains complete demonstrations. The NEXUS framework supports Full (6-phase), Sprint, and single-agent workflow modes.

Q: How do I pick the right agent for my task?

Start with the category matching your domain, then read the description and vibe frontmatter fields. For a high-level map of the ecosystem, read strategy/EXECUTIVE-BRIEF.md. For your first session, follow strategy/QUICKSTART.md.

Q: Are agents locked to a specific programming language?

Most agents are language-agnostic. Some engineering agents specialize (e.g., Senior Developer focuses on Laravel/Livewire, Solidity Smart Contract Engineer on EVM), but their workflows and reasoning patterns apply broadly.

Q: How do I contribute a new agent?

Follow CONTRIBUTING.md (also available in Chinese at CONTRIBUTING_zh-CN.md). Use the naming convention category/category-role-name.md and include the standard YAML frontmatter fields (name, description, and optionally color, emoji, vibe, tools).

Q: Is there a runtime, API, or server component?

No. This is a content repository of static markdown files. There is no executable code beyond the helper scripts (install.sh, convert.sh, lint-agents.sh, and the i18n PowerShell script).

Q: What does the tools frontmatter field do?

It declares which tool capabilities the agent expects (e.g., WebFetch, WebSearch, Read, Write, Edit). This is informational for the AI tool — your tool must actually provide these capabilities for the agent to use them.

Q: What is the convert.sh script for?

scripts/convert.sh converts agent files between formats to support different AI tool conventions.

Q: What is the lint-agents.sh script for?

scripts/lint-agents.sh validates agent file formatting and consistency, checking for proper YAML frontmatter, naming conventions, and potential issues.