# 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:**

```bash
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

| Requirement | Details |
|---|---|
| Git | Any recent version |
| AI coding tool | Claude Code, Cursor, GitHub Copilot, or any tool that accepts markdown system prompts |
| Shell | Bash (for `install.sh` and `convert.sh`) |
| Disk space | < 5 MB |
| OS | Linux, macOS, Windows (WSL for shell scripts) |

### Installation Methods

=== "Installer (recommended)"
    ```bash
    git clone https://github.com/msitarzewski/agency-agents.git
    cd agency-agents
    ./scripts/install.sh
    ```

=== "Manual copy"
    ```bash
    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:

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

```text
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:

| AI Tool | Integration Guide | Agent Directory |
|---|---|---|
| Claude Code | `integrations/claude-code/README.md` | `.claude/` project config |
| Cursor | `integrations/cursor/README.md` | Cursor rules directory |
| GitHub Copilot | `integrations/github-copilot/README.md` | `~/.github/agents/` |
| Aider | `integrations/aider/README.md` | Aider conventions |
| Windsurf | `integrations/windsurf/README.md` | Windsurf config |
| OpenCode | `integrations/opencode/README.md` | OpenCode agent path |
| Gemini CLI | `integrations/gemini-cli/README.md` | Gemini CLI config |
| Antigravity | `integrations/antigravity/README.md` | Antigravity platform |
| OpenClaw | `integrations/openclaw/README.md` | OpenClaw setup |
| Kimi | `integrations/kimi/README.md` | Kimi AI config |
| Qwen | `integrations/qwen/README.md` | Qwen model config |

> [!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.

```yaml
---
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
---
```

| Field | Required | Purpose |
|---|---|---|
| `name` | Yes | Display name for the agent persona |
| `description` | Yes | 1–2 sentence summary of expertise and focus |
| `color` | No | Brand color — named (`green`, `blue`) or hex (`"#6B7280"`) |
| `emoji` | No | Visual identifier emoji character |
| `vibe` | No | One-line personality statement capturing the agent's approach |
| `tools` | No | Comma-separated capabilities the agent expects (e.g., `WebFetch, Read, Write`) |

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:

```powershell
.\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:

```powershell
.\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:

| Agent | File | Specialty |
|---|---|---|
| Senior Developer | `engineering-senior-developer.md` | Laravel, Livewire, advanced CSS, architecture |
| Backend Architect | `engineering-backend-architect.md` | API design, database architecture, scalability |
| Frontend Developer | `engineering-frontend-developer.md` | React/Vue/Angular, UI, performance optimization |
| AI Engineer | `engineering-ai-engineer.md` | ML model deployment, AI integration, data pipelines |
| DevOps Automator | `engineering-devops-automator.md` | CI/CD, infrastructure automation, cloud ops |
| Security Engineer | `engineering-security-engineer.md` | Threat modeling, security review, AppSec |
| Software Architect | `engineering-software-architect.md` | System design, DDD, architecture patterns |
| SRE | `engineering-sre.md` | SLOs, error budgets, observability, chaos engineering |
| Code Reviewer | `engineering-code-reviewer.md` | Constructive review, security, maintainability |
| Database Optimizer | `engineering-database-optimizer.md` | Schema design, query tuning, indexing (PostgreSQL/MySQL) |
| Git Workflow Master | `engineering-git-workflow-master.md` | Branch strategy, conventional commits, advanced Git |
| Rapid Prototyper | `engineering-rapid-prototyper.md` | Quick POC development, MVP iteration |
| Technical Writer | `engineering-technical-writer.md` | Developer docs, API references, tutorials |
| Incident Response Commander | `engineering-incident-response-commander.md` | Incident management, postmortems, on-call |
| Mobile App Builder | `engineering-mobile-app-builder.md` | iOS/Android, React Native, Flutter |
| CMS Developer | `engineering-cms-developer.md` | Content management system development |
| Data Engineer | `engineering-data-engineer.md` | Data pipelines, lakehouse, ETL/ELT |
| Embedded Firmware Engineer | `engineering-embedded-firmware-engineer.md` | Bare-metal, RTOS, ESP32/STM32/Nordic |
| Solidity Smart Contract Engineer | `engineering-solidity-smart-contract-engineer.md` | EVM contracts, gas optimization, DeFi |
| Threat Detection Engineer | `engineering-threat-detection-engineer.md` | SIEM rules, threat hunting, ATT&CK mapping |
| Codebase Onboarding Engineer | `engineering-codebase-onboarding-engineer.md` | New codebase ramp-up |
| Minimal Change Engineer | `engineering-minimal-change-engineer.md` | Smallest-possible diffs |
| Voice AI Integration Engineer | `engineering-voice-ai-integration-engineer.md` | Voice AI systems |
| Email Intelligence Engineer | `engineering-email-intelligence-engineer.md` | Email system intelligence |
| Filament Optimization Specialist | `engineering-filament-optimization-specialist.md` | Filament PHP optimization |
| Autonomous Optimization Architect | `engineering-autonomous-optimization-architect.md` | LLM routing, cost optimization, shadow testing |
| AI Data Remediation Engineer | `engineering-ai-data-remediation-engineer.md` | Self-healing data pipelines, offline SLM |
| Feishu Integration Developer | `engineering-feishu-integration-developer.md` | Feishu/Lark platform integration |
| WeChat Mini Program Developer | `engineering-wechat-mini-program-developer.md` | WeChat ecosystem, mini programs, payments |

#### Marketing (30 agents)

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

| Agent | Specialty |
|---|---|
| Growth Hacker | Rapid user acquisition, viral loops, conversion funnels |
| Content Creator | Multi-platform content strategy, editorial calendars |
| SEO Specialist | Technical SEO, content strategy, link building |
| Social Media Strategist | Cross-platform strategy, campaign planning |
| TikTok Strategist | Viral content, algorithm optimization, TikTok growth |
| Instagram Curator | Visual storytelling, community management |
| Twitter Engager | Real-time engagement, thought leadership |
| LinkedIn Content Creator | Professional branding, B2B content |
| Reddit Community Builder | Authentic engagement, value-driven marketing |
| Podcast Strategist | Podcast content strategy and operations |
| Book Co-Author | Thought leadership books, ghostwriting, publishing |
| App Store Optimizer | ASO, conversion rate optimization, app visibility |
| AI Citation Strategist | AEO/GEO, AI recommendation visibility, citation audit |
| Agentic Search Optimizer | AI search optimization |
| Video Optimization Specialist | Video content optimization |
| Carousel Growth Engine | TikTok/Instagram carousel creation and auto-posting |
| Xiaohongshu Specialist | 小红书 lifestyle content and growth |
| WeChat Official Account | 微信公众号 content marketing and fan engagement |
| Zhihu Strategist | 知乎 thought leadership and knowledge-driven engagement |
| Baidu SEO Specialist | 百度 optimization, China SEO, ICP compliance |
| Bilibili Content Strategist | B站 algorithm, danmaku culture, UP主 growth |
| Douyin Strategist | 抖音 short-video marketing and algorithm growth |
| Kuaishou Strategist | 快手 platform, 老铁 ecosystem, lower-tier market growth |
| Livestream Commerce Coach | Live-selling training, studio optimization |
| Private Domain Operator | 企业微信 private traffic and community operations |
| Short-Video Editing Coach | Post-production workflows, platform specs |
| China E-Commerce Operator | 淘宝/天猫/拼多多 and livestream e-commerce |
| Cross-Border E-Commerce | Amazon/Shopee/Lazada cross-border fulfillment |
| China Market Localization Strategist | China market entry strategy |
| Weibo Strategist | 微博 trending topics, hashtag marketing, fan engagement |

#### Specialized (41 agents)

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

| Agent | Specialty |
|---|---|
| Chief of Staff | Executive coordination, process ownership, decision routing |
| Agents Orchestrator | Multi-agent coordination and workflow management |
| Workflow Architect | Workflow discovery, process mapping, specification |
| MCP Builder | Model Context Protocol server and AI agent toolchain |
| Document Generator | PDF/PPTX/DOCX/XLSX code generation |
| Developer Advocate | Community building, developer experience, tech content |
| Salesforce Architect | Multi-cloud Salesforce design, Governor Limits |
| Blockchain Security Auditor | Smart contract audit and vulnerability analysis |
| Compliance Auditor | SOC2/ISO27001/HIPAA/PCI-DSS compliance guidance |
| Automation Governance Architect | Automation governance, n8n workflows, audit |
| LSP/Index Engineer | Language server protocol, code intelligence, semantic indexing |
| Healthcare Customer Service | Healthcare-specific support workflows |
| Healthcare Marketing Compliance | China medical advertising regulation compliance |
| Legal Document Review | Legal document analysis and review |
| Legal Client Intake | Client intake process automation |
| Legal Billing & Time Tracking | Legal billing operations |
| Recruitment Specialist | Talent acquisition, employer branding |
| HR Onboarding | Employee onboarding processes |
| Supply Chain Strategist | Supply chain management and procurement |
| Customer Service | General customer service operations |
| Hospitality Guest Services | Hospitality industry guest support |
| Retail Customer Returns | Retail return processing |
| Loan Officer Assistant | Lending process support |
| Real Estate Buyer/Seller | Real estate transaction support |
| Study Abroad Advisor | International education planning (US/UK/CA/AU) |
| Corporate Training Designer | Enterprise training and course development |
| Government Digital Presales | ToG digital transformation consulting |
| Model QA Specialist | ML audit, feature analysis, explainability |
| ZK Steward | Zettelkasten knowledge management |
| Cultural Intelligence Strategist | Global UX, diversity, cultural inclusion |
| Korean Business Navigator | Korean business culture and processes |
| French Consulting Market Navigator | ESN/SI ecosystem, French IT freelancing |
| Civil Engineer | Civil engineering specialist |
| And additional agents... | Identity graph, data consolidation, report distribution, sales data extraction, accounts payable, agentic identity & trust |

#### Game Development (20 agents)

Organized by engine with cross-engine specialists:

| Sub-category | Agents |
|---|---|
| **Cross-engine** | Game Designer, Level Designer, Narrative Designer, Technical Artist, Game Audio Engineer |
| **Unity** (4) | Unity Architect, Shader Graph Artist, Multiplayer Engineer, Editor Tool Developer |
| **Unreal Engine** (4) | Multiplayer Architect, Systems Engineer, Technical Artist, World Builder |
| **Godot** (3) | Gameplay Scripter, Multiplayer Engineer, Shader Developer |
| **Roblox Studio** (3) | Avatar Creator, Experience Designer, Systems Scripter |
| **Blender** (1) | Blender Addon Engineer |

#### Other Categories

| Category | Count | Focus |
|---|---|---|
| **Design** | 8 | UI/UX design, brand guardianship, visual storytelling, inclusive visuals, image prompts, whimsy |
| **Sales** | 8 | Outbound, discovery coaching, deal strategy, proposals, pipeline analysis, account strategy |
| **Paid Media** | 7 | PPC, programmatic buying, tracking/measurement, creative strategy, paid social, search query analysis |
| **Finance** | 5 | Bookkeeping/controller, financial analysis, FP&A, investment research, tax strategy |
| **Product** | 5 | Product management, sprint prioritization, behavioral nudge, feedback synthesis, trend research |
| **Project Management** | 6 | Studio producer, project shepherd, studio ops, experiment tracking, Jira workflows, senior PM |
| **Support** | 6 | Support response, analytics reporting, finance tracking, infrastructure, legal compliance, executive summaries |
| **Spatial Computing** | 6 | visionOS, WebXR immersive, macOS Metal, XR cockpit, XR interface architecture, terminal integration |
| **Academic** | 5 | Anthropology, geography, history, narratology, psychology |
| **Testing** | 8 | API testing, performance benchmarking, accessibility audit, evidence collection, reality checking, workflow optimization, tool evaluation, test results analysis |

> [!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:

| File | Purpose |
|---|---|
| `EXECUTIVE-BRIEF.md` | High-level overview of the agent ecosystem and pairings |
| `QUICKSTART.md` | Guided introduction and recommended first steps |
| `nexus-strategy.md` | The strategic coordination model |
| `playbooks/phase-0-discovery.md` | Phase 0: Discovery and idea validation |
| `playbooks/phase-1-strategy.md` | Phase 1: Strategy formulation |
| `playbooks/phase-2-foundation.md` | Phase 2: Technical foundation |
| `playbooks/phase-3-build.md` | Phase 3: Build and development |
| `playbooks/phase-4-hardening.md` | Phase 4: Hardening and QA |
| `playbooks/phase-5-launch.md` | Phase 5: Launch execution |
| `playbooks/phase-6-operate.md` | Phase 6: Operations and growth |
| `coordination/handoff-templates.md` | Structured agent-to-agent handoff patterns |
| `coordination/agent-activation-prompts.md` | Ready-made prompts to activate agents |
| `runbooks/scenario-startup-mvp.md` | Runbook for startup MVP development |
| `runbooks/scenario-incident-response.md` | Runbook for production incidents |
| `runbooks/scenario-marketing-campaign.md` | Runbook for marketing campaigns |
| `runbooks/scenario-enterprise-feature.md` | Runbook for enterprise feature delivery |

### MCP Memory Integration

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

**Required MCP memory server tools:**

| Tool | Purpose |
|---|---|
| `remember` | Store decisions, deliverables, and context |
| `recall` | Search memories by keyword or semantic similarity |
| `rollback` | Revert to a previous memory state |
| `search` | Find specific memories across sessions |

**Setup:**

```bash
./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:
   ```powershell
   .\scripts\i18n\localize-agents-zh.ps1
   ```
3. Default targets: `~/.github/agents/` and `~/.copilot/agents/`
4. Custom target:
   ```powershell
   .\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:

| Example | File | Description |
|---|---|---|
| Startup MVP | `examples/workflow-startup-mvp.md` | End-to-end startup product workflow |
| Landing Page | `examples/workflow-landing-page.md` | Landing page creation workflow |
| Book Chapter | `examples/workflow-book-chapter.md` | Book chapter writing workflow |
| With Memory | `examples/workflow-with-memory.md` | Workflow using MCP persistent memory |
| Nexus Spatial | `examples/nexus-spatial-discovery.md` | Advanced spatial discovery pattern |

---

## 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:
   ```powershell
   .\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:
   ```json
   {
     "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:
   ```bash
   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.

---

_Generated May 2026 from msitarzewski/agency-agents at 783f6a7. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._