Agency Agents — Administrator & Developer Guide

1. Architecture Overview

agency-agents is a content repository, not a software application. It contains no compiled code, no runtime services, no databases, and no network listeners. The repository distributes a curated library of markdown files — each describing a specialized AI agent persona with YAML frontmatter — plus a thin shell-script layer that copies those files into the agent directories of 13 supported AI coding tools.

The repository's value lives in four architectural layers:

1. Agent roster — 200+ opinionated role definitions across 15 business divisions, each with a consistent frontmatter contract and a persona body designed for direct LLM consumption
2. NEXUS orchestration framework (strategy/) — playbooks, runbooks, coordination templates, and activation prompts that chain multiple agents into structured multi-phase workflows
3. Integration layer (integrations/<tool>/) — per-tool installation guides, activation syntax, and format adapters for 13 AI coding tools
4. Utility scripts (scripts/) — install.sh, convert.sh, lint-agents.sh, and the i18n PowerShell localization pipeline

Repository Structure

agency-agents/
├── academic/                    # 5 agents — anthropology, geography, history, narratology, psychology
├── design/                      # 8 agents — UI/UX, brand, visual storytelling, inclusive visuals
├── engineering/                  # 29 agents — full SDLC coverage
├── examples/                    # 5 workflow examples + README
├── finance/                     # 5 agents — bookkeeping, FP&A, investment, tax
├── game-development/            # 5 cross-engine agents
│   ├── blender/                 # 1 agent — addon engineering
│   ├── godot/                   # 3 agents — gameplay, multiplayer, shaders
│   ├── roblox-studio/           # 3 agents — avatar, experience, systems
│   ├── unity/                   # 4 agents — architecture, shaders, multiplayer, editor tools
│   └── unreal-engine/           # 4 agents — multiplayer, systems, tech art, world building
├── integrations/                # README + 13 tool-specific integration dirs
│   ├── aider/
│   ├── antigravity/
│   ├── claude-code/
│   ├── cursor/
│   ├── gemini-cli/
│   ├── github-copilot/
│   ├── kimi/
│   ├── mcp-memory/              # README + setup.sh + backend-architect-with-memory.md
│   ├── openclaw/
│   ├── opencode/
│   ├── qwen/
│   └── windsurf/
├── marketing/                   # 30 agents — global + China-market specialists
├── paid-media/                  # 7 agents — PPC, programmatic, tracking, creative
├── product/                     # 5 agents — PM, sprint, nudge, feedback, trends
├── project-management/          # 6 agents — studio producer, shepherd, ops, Jira
├── sales/                       # 8 agents — outbound, discovery, deals, proposals, pipeline
├── scripts/
│   ├── convert.sh               # Format conversion between tool conventions
│   ├── install.sh               # Auto-detect tools and copy agents
│   ├── lint-agents.sh           # Validate formatting and consistency
│   └── i18n/
│       ├── README.md
│       ├── agent-names-zh.json  # 150+ English→Chinese name/description mappings
│       └── localize-agents-zh.ps1  # PowerShell localization script
├── spatial-computing/           # 6 agents — visionOS, WebXR, Metal, XR interaction
├── specialized/                 # 41 agents — industry-specific and cross-functional
├── strategy/
│   ├── EXECUTIVE-BRIEF.md       # Ecosystem overview and agent pairings
│   ├── QUICKSTART.md            # Guided first steps
│   ├── nexus-strategy.md        # Strategic coordination model
│   ├── coordination/
│   │   ├── agent-activation-prompts.md   # Ready-made activation prompts
│   │   └── handoff-templates.md          # Agent-to-agent handoff patterns
│   ├── playbooks/               # 7-phase lifecycle (phase-0 through phase-6)
│   └── runbooks/                # 4 scenario runbooks (MVP, incident, marketing, enterprise)
├── support/                     # 6 agents — response, analytics, finance, infra, legal, exec
├── testing/                     # 8 agents — API, performance, accessibility, evidence, workflow
├── CONTRIBUTING.md              # Contribution guidelines
├── CONTRIBUTING_zh-CN.md        # Chinese translation of contributing guidelines
├── LICENSE
├── README.md
└── SECURITY.md

Note

This is a content repository — the "source code" is markdown. The AST code extractor finds 0 functions, 0 classes, 0 CLI commands, 0 API endpoints, and 0 config keys because the meaningful content is prose agent instructions, not executable code.

Technology Stack

Data Flow

Agent .md files (canonical source)
         │
         ├──→ install.sh ──→ Copy to tool-specific agent directories
         │                    (~/.github/agents/, ~/.cursor/, .claude/, etc.)
         │
         ├──→ convert.sh ──→ Format adaptation for different tool conventions
         │
         ├──→ lint-agents.sh ──→ Validation and consistency checks
         │
         └──→ localize-agents-zh.ps1 ──→ In-place Chinese localization
              (reads agent-names-zh.json)

2. System Requirements

Note

There are no runtime dependencies, no package managers, no build tools, and no compiled artifacts. The repository is entirely self-contained markdown and shell scripts.

3. Configuration Reference

Agent Frontmatter Specification

Every agent .md file uses YAML frontmatter delimited by --- markers:

Example — full frontmatter:

---
name: Chief of Staff
description: Master coordinator for founders and executives — filters noise, owns processes, enforces consistency.
color: "#6B7280"
emoji: 🧭
vibe: "I don't own any function. I own the space between all of them."
---

Example — minimal frontmatter:

---
name: Growth Hacker
description: Expert growth strategist specializing in rapid user acquisition through data-driven experimentation.
---

Important

The color field accepts both named colors and hex codes. Hex codes must be quoted in YAML to avoid parsing errors (e.g., color: "#6B7280", not color: #6B7280).

Agent Body Structure

The body following the frontmatter closing --- follows a consistent pattern across all 200+ agents:

1. H1 Title — agent name with optional emoji prefix (e.g., # 🧭 Chief of Staff)
2. Identity & Memory — role definition, personality traits, memory management, experience background
3. Core Mission / Philosophy — primary objectives organized as H3/H4 subsections with emoji-prefixed headers and capability bullets
4. Critical Rules — hard behavioral constraints, numbered or emoji-prefixed, each with explanation and "This means:" implementation details
5. Deliverables / Templates — concrete output specifications, code examples in fenced blocks, template structures with placeholders
6. Domain Context — decision frameworks, success metrics, communication style, architecture templates (varies by agent type)

Agent Naming Convention

Files follow the pattern: {category}/{category}-{role-name}.md

Chinese Localization Mapping

scripts/i18n/agent-names-zh.json maps English agent names to Chinese equivalents:

{
  "Frontend Developer": {
    "name": "前端开发工程师",
    "description": "专注现代 Web 技术、React/Vue/Angular 框架、UI 实现与性能优化的前端专家"
  },
  "Backend Architect": {
    "name": "后端架构师",
    "description": "负责 API 设计、数据库架构与可扩展性的后端系统专家"
  }
}

The mapping covers 150+ agents. JSON keys match the name field in agent frontmatter exactly (case-sensitive). Agents whose name has no mapping entry are skipped by the localization script.

Localization Script Configuration

scripts/i18n/localize-agents-zh.ps1 accepts a -TargetDirs parameter:

The script processes each .md file in the target directories:

1. Reads the file as UTF-8
2. Parses the YAML frontmatter (between --- markers)
3. Extracts the name field
4. Looks up the name in agent-names-zh.json
5. If found, replaces name and description fields with Chinese translations
6. Writes the modified file back as UTF-8

Warning

The script modifies files in-place with no backup. It also does not touch the body of the agent file — only name and description frontmatter fields are replaced.

4. Deployment & Scaling

Distribution Model

This is a Git-based distribution. Users clone the repository and run the installer or manually copy agent files. There is no package registry, no container image, and no server deployment.

Distribution channels:

Installation Pipeline

scripts/install.sh handles automated deployment to local AI tool directories:

1. Detects which supported AI tools are installed by checking for their config directories
2. Copies agent .md files to each detected tool's agent directory
3. Reports results per tool

Format Conversion Pipeline

scripts/convert.sh converts agent files between format conventions required by different AI tools.

Adding a New Integration

To add support for a new AI tool:

1. Create integrations/<tool-name>/README.md with:
   • Tool-specific agent directory path
   • How to load/activate agents in that tool
   • Any format differences from the canonical markdown
2. Update scripts/install.sh to detect the new tool and copy agents to its directory
3. Update scripts/convert.sh if the tool requires format changes
4. Test with a representative set of agents

5. Operations

Linting and Quality Assurance

Run the lint script to validate all agent files:

./scripts/lint-agents.sh

Tip

Run linting after adding new agents, modifying frontmatter, or accepting pull requests to catch formatting inconsistencies.

Updating Agents

Agent updates are straightforward Git operations:

cd agency-agents
git pull origin main
./scripts/install.sh  # Re-deploy updated agents to tools

Agent Inventory Audit

To count agents by category:

for dir in academic design engineering finance game-development marketing \
           paid-media product project-management sales spatial-computing \
           specialized strategy support testing; do
  count=$(find "$dir" -name "*.md" -not -name "README.md" | wc -l)
  echo "$dir: $count agents"
done

Note

Some directories contain README files that are not agent definitions. Exclude README.md files when counting agents. Strategy files (playbooks, runbooks, coordination) are workflow documents, not agent personas.

Localization Operations

To verify localization coverage:

# Count agents in the zh mapping
python3 -c "import json; d=json.load(open('scripts/i18n/agent-names-zh.json')); print(f'{len(d)} agents mapped')"

To add a new agent to the Chinese localization:

1. Add an entry to scripts/i18n/agent-names-zh.json with the exact English name as key
2. Provide name (Chinese name) and description (Chinese description) values
3. Re-run the localization script on your target directories

6. Performance

Repository Size

Tip

The repository is lightweight by design. Clone and install operations complete in seconds. Agent files average 2–5 KB each.

7. Security

Security Policy

The repository includes a SECURITY.md file for responsible disclosure.

Known Security Issues

Two security issues are tracked in GitHub Issues:

Hidden Unicode Soft Hyphens (Issue #478)

Severity: Medium — prompt injection vector

Description: Unicode soft hyphens (U+00AD) were found in 2 agent files. These invisible characters could alter LLM behavior when agent files are loaded as system prompts.

Detection:

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

Mitigation:

• Remove all U+00AD characters from affected files
• Add Unicode validation to scripts/lint-agents.sh
• Review all agent files for unexpected invisible characters

Caution

Agent files are consumed directly by LLMs as system prompts. Hidden Unicode characters can cause prompt injection, behavior manipulation, or instruction bypass. Always audit agent files from external contributors.

Hardcoded Credentials (Issue #477)

Severity: Medium — credential exposure

Description: testing/testing-api-tester.md and testing/testing-performance-benchmarker.md contained example credentials that could be mistaken for real ones or accidentally used.

Mitigation:

• Replace all credential-like strings with obvious placeholders
• Add credential pattern detection to scripts/lint-agents.sh
• Document in CONTRIBUTING.md that example credentials must use placeholder format

Warning

Never commit real API keys, passwords, tokens, or secrets in agent definition files. These files are designed to be shared publicly and loaded into AI tools — any credentials in them will be exposed.

Security Considerations for Agent Files

8. Developer Internals

Category Taxonomy

The 15 categories follow a consistent organizational principle: each maps to a business function or professional domain.

NEXUS Strategy Framework Architecture

The strategy layer provides three workflow modes:

Phase lifecycle:

Phase 0: Discovery → Phase 1: Strategy → Phase 2: Foundation →
Phase 3: Build → Phase 4: Hardening → Phase 5: Launch → Phase 6: Operate

Coordination mechanisms:

• coordination/handoff-templates.md — structured context transfer between agents
• coordination/agent-activation-prompts.md — ready-made prompts to activate any agent in the roster

Scenario runbooks:

MCP Memory Integration Architecture

The MCP memory integration (integrations/mcp-memory/) is a pattern, not a runtime. It provides:

1. setup.sh — a diagnostic script that:

   • Checks for MCP client configs at three known paths (~/.config/claude/mcp.json, ~/.cursor/mcp.json, .mcp.json)
   • Prints guidance for installing an MCP-compatible memory server
   • Outputs the expected MCP config JSON structure
   • Does NOT install any server or modify any config files automatically

2. backend-architect-with-memory.md — a reference implementation showing how to weave memory tool usage (remember, recall, rollback, search) into an agent's prompt body

3. README.md — documentation of the memory integration pattern

The design is deliberately server-agnostic: any MCP-compatible memory server works. The integration only specifies the tool interface contract:

Note

The setup.sh script is read-only — it detects and reports but does not modify any files. All configuration changes must be done manually by the user.

Localization Pipeline Internals

The Chinese localization system has two components:

agent-names-zh.json (15,888 chars) — a flat JSON object mapping English agent names to Chinese translations. Each entry provides:

{
  "Agent English Name": {
    "name": "中文名称",
    "description": "中文描述"
  }
}

Coverage: 150+ agents mapped. The mapping includes alternate name forms for some agents (e.g., both "Academic Anthropologist" and "Anthropologist" map to "学术人类学家").

localize-agents-zh.ps1 — PowerShell script that performs in-place frontmatter rewriting:

1. Iterates .md files in target directories
2. Detects YAML frontmatter by checking for leading ---
3. Extracts name: field via regex (?m)^name:\s*(.+)$
4. Looks up the name in the JSON mapping
5. Replaces name: and description: lines via regex substitution
6. Writes back as UTF-8
7. Reports count of files updated per directory

Key implementation details:

• Uses [System.IO.File]::ReadAllText/WriteAllText for proper UTF-8 handling
• Only modifies frontmatter — body content is untouched
• Silently skips files without frontmatter or without a mapping entry
• Default target directories: $env:USERPROFILE\.github\agents and $env:USERPROFILE\.copilot\agents

Utility Scripts

Tip

The scripts/ directory is classified as LOW priority in the file triage because its contents are support tooling, not agent definitions. The testing/ directory is similarly LOW priority — those are testing-methodology agents, not test suites.

Agent Design Patterns

Across the 200+ agent definitions, several recurring patterns emerge:

Pattern: Persona-first instruction Every agent opens with identity establishment (role, personality, experience) before listing capabilities. This primes the LLM to adopt the persona before processing task-specific instructions.

Pattern: Critical rules as guardrails Agents include numbered "Critical Rules" or "Rules You Must Follow" sections with hard constraints. Each rule typically includes a "This means:" clause explaining implementation. This pattern prevents the LLM from drifting outside the agent's intended scope.

Pattern: Deliverable templates Agents include concrete output templates with placeholder sections, showing the exact structure of expected deliverables. This reduces format variation across sessions.

Pattern: Domain-specific code examples Technical agents embed real code examples (PHP, SQL, JavaScript, CSS, etc.) demonstrating the quality and style of output they should produce. These are not pseudo-code — they are functional snippets.

Pattern: Anti-patterns as negative constraints Many agents explicitly list what NOT to do (e.g., "No culture salad", "function before aesthetics"). Negative constraints are as important as positive instructions for LLM behavior shaping.

Pattern: Emoji-prefixed section headers H3 and H4 headers frequently use emoji prefixes for visual scanning (e.g., ### 🎯 Core Mission, ### ⚡ Critical Rules). This is a stylistic choice, not a functional requirement.

File Inventory Summary

Code Patterns and Conventions

Frontmatter consistency: All agents use the same YAML frontmatter field set. name and description are universal; color, emoji, vibe, and tools are optional.

Naming convention: Files use {category}-{role-name}.md with lowercase kebab-case. Category prefix matches the directory name.

Sub-categorization: game-development/ uses engine-specific subdirectories. strategy/ uses function-specific subdirectories (playbooks, runbooks, coordination). Other categories are flat.

Language: Agent body content is English. Chinese localization is applied only to frontmatter fields, not body text.

Line endings and encoding: Files are UTF-8. The .gitattributes file manages line ending normalization.

Known Issues and Improvement Opportunities

1. Unicode sanitization — No automated check for hidden Unicode characters (Issue #478). The lint script should detect non-ASCII invisible characters in agent files.

2. Credential patterns — No automated detection of credential-like strings in agent examples (Issue #477). A lint rule should flag patterns like sk_test_, Bearer, API key formats.

3. Localization coverage gaps — The zh-CN mapping covers ~150 of 200+ agents. New agents added without corresponding JSON entries will be skipped during localization.

4. Feature request: Interior Designer agent — Issue #491 requests an interior design specialist agent. Would belong in design/ or specialized/.

5. Monetization proposal — Issue #486 proposes a native monetization layer via Merxex. This is an architectural discussion about potentially adding commercial infrastructure to a content repository.

Contributing

The repository maintains contribution guidelines in two languages:

• CONTRIBUTING.md — English
• CONTRIBUTING_zh-CN.md — Chinese (zh-CN)

To add a new agent:

1. Choose the appropriate category directory
2. Create {category}/{category}-{role-name}.md
3. Include required frontmatter (name, description) and optional fields
4. Follow the body structure pattern: identity → mission → rules → deliverables
5. Run scripts/lint-agents.sh to validate
6. Add a zh-CN mapping entry to scripts/i18n/agent-names-zh.json if localization is desired
7. Submit a pull request

To add a new integration:

1. Create integrations/<tool-name>/README.md
2. Document the tool's agent directory path, activation method, and any format requirements
3. Update scripts/install.sh and scripts/convert.sh to support the new tool
4. Test with representative agents

To add a new strategy component:

1. Playbooks go in strategy/playbooks/phase-{N}-{name}.md
2. Runbooks go in strategy/runbooks/scenario-{name}.md
3. Coordination templates go in strategy/coordination/
4. Update cross-references in strategy/EXECUTIVE-BRIEF.md

Testing

The testing/ directory contains 8 testing-methodology agents (not test suites):

There are no automated test suites, unit tests, or CI pipelines in this repository. Quality assurance is manual: lint validation via scripts/lint-agents.sh and human review of agent effectiveness.

9. Integration Points

Supported AI Tools

MCP (Model Context Protocol)

The integrations/mcp-memory/ directory provides a generic MCP memory integration pattern. Any MCP-compatible memory server can be used. See the Architecture section above for implementation details.

External Dependencies

This repository has zero external dependencies. No package managers, no installed libraries, no network services. The only requirement is a shell (Bash for scripts, PowerShell for localization) and Git for version control.