The Problem

Teams that want to adopt AI‑augmented workflows must locate, customize, and maintain dozens of prompt‑driven “agents”. Without a curated source they spend time copying snippets, reconciling style, and wiring each agent to their preferred development tool.

What This Does

The repository ships a ready‑made roster of 338 agent definition files (e.g., engineering/engineering-frontend-developer.md, marketing/marketing-reddit-community-builder.md). Each markdown file declares the agent’s personality, mission, and concrete deliverables. The scripts folder contains the only executable glue:

  • scripts/install.sh – primary entry point; copies selected markdown agents into the target tool’s agent directory (Claude Code, Cursor, etc.).
  • scripts/convert.sh – generates integration adapters for the supported IDEs/CLI tools (see integrations/ readmes).
  • scripts/check‑runbooks.sh, scripts/check‑divisions.sh – CI helpers that validate agent metadata.

The GitHub Actions workflow files (.github/workflows/*.yml) invoke the check scripts on every push, ensuring the roster stays syntactically sound.

How It Is Wired

Execution starts with the install command:

./scripts/install.sh [--tool <tool>] [--division <folder>]
  1. install.sh parses arguments, determines the destination (~/.claude/agents/ for Claude Code, analogous dirs for other tools).
  2. It calls scripts/convert.sh to materialize any tool‑specific wrapper files under integrations/.
  3. For each selected division (e.g., engineering/), the script loops over *.md files and copies them to the destination.
  4. No external services are contacted; the process touches only the local filesystem.

The check scripts (check‑runbooks.sh, check‑divisions.sh) are invoked by the CI workflows (.github/workflows/check‑runbooks.yml, check‑divisions.yml). They read the same markdown files, verify required front‑matter fields, and fail the workflow on violations. The import graph shows only two internal modules (scripts/build-hermes-plugin, scripts/check-hermes-plugin) with zero import edges, meaning each script is self‑contained and has no hidden runtime dependencies.

How To Use It

# Clone the repo (use the exact URL as requested)
git clone https://github.com/moses-y/agency-agents
cd agency-agents

# Install all agents for Claude Code (default)
./scripts/install.sh --tool claude-code

# Install only the marketing agents
./scripts/install.sh --division marketing --tool claude-code

# Verify the roster locally (runs the same checks CI does)
./scripts/check-runbooks.sh

If you prefer a graphical install, download the companion desktop app from the README links; the CLI workflow above is the exact process the app automates.

Real‑World Use

A product team can bootstrap their sprint planning by copying product/product‑manager.md and product/product‑feedback‑synthesizer.md into their Claude Code workspace. The agents then generate backlog items, prioritize them, and draft user stories—all with the same prompts the team would have written manually.

Code Health & Issues

  • Medium – Least‑privilege token – .github/workflows/check-divisions.yml declares no permissions for GITHUB_TOKEN. Add permissions: { contents: read } at the top of the workflow.
  • Low – Missing job timeout – Same workflow lacks timeout-minutes. Specify a reasonable bound (e.g., timeout-minutes: 30) for each job.
  • Medium – Deep nesting – scripts/check-runbooks.sh reaches 7‑level indentation, making the flow hard to follow. Refactor with early returns or helper functions.
  • Medium – Duplicated blocks – scripts/convert.sh, scripts/install.sh, scripts/lint‑agents.sh share a 6‑line snippet repeated 10 times. Extract to a shared helper script.
  • Medium – Broad exception handling – scripts/build-hermes-plugin.py catches generic except; replace with specific exception types.
  • Medium – Oversized file – scripts/install.sh is 1,063 lines; split by responsibility (argument parsing, conversion, copying).
  • Medium – High branching density – scripts/check‑agent‑originality.sh and two others contain >30 branch points in <120 lines; consider table‑driven dispatch.

All findings are derived from deterministic static analysis; no additional issues were inferred.

The Bottom Line

The repo delivers a comprehensive, ready‑to‑use catalog of AI agents and a minimal CLI that reliably installs them into supported developer tools. It is well‑structured for reference but suffers from script‑level technical debt (deep nesting, duplication, oversized files) and a CI permission oversight. Teams that need a quick, curated set of prompt agents will find it valuable; developers planning to extend or maintain the tooling should first refactor the scripts to reduce cognitive load.