Companion to the hands-on tutorial: Install and run an AI agency with msitarzewski/agency-agents on Cui.Guru. The tutorial shows how to use it; this post dissects how it works. Everything below is read from a fresh clone of the repo (last commit 2026-11-08), not from marketing copy.
msitarzewski/agency-agents (about 168k stars per the GitHub API on 2026-11-15, MIT) calls itself “a complete AI agency at your fingertips”. Strip the branding and it is three things: a library of specialist personas written as markdown files, a small shell toolchain that installs them into whatever coding agent you use, and a set of coordination playbooks called NEXUS that say who should do what, in which order, with which quality checks.
The interesting engineering is not the personas. It is how one flat data model feeds seventeen different tools, and how the playbooks make a pile of personas behave like a team.
1. The workflow in motion
The loop is: author a persona once, convert it, install it where your tool looks for agents, then activate the Agents Orchestrator and let it pull in specialists phase by phase.
2. What an “agent” is: a frontmatter contract
An agent is one markdown file with YAML frontmatter and a structured body. The repo has 283 such files across 18 divisions (engineering has 66, specialized 59 and game-development 21 in this checkout), each in a top-level directory listed in divisions.json. Here is the top of engineering/engineering-code-reviewer.md:
---
name: Code Reviewer
description: Expert code reviewer who provides constructive, actionable feedback ...
color: purple
emoji: 👁️
vibe: Reviews code like a mentor, not a gatekeeper. Every comment teaches something.
---
# Code Reviewer Agent
## 🧠 Your Identity & Memory
## 🎯 Your Core Mission
## 🔧 Critical Rules
scripts/lint-agents.sh turns that shape into a rule: the frontmatter must have name, description and color (errors), and the sections Identity, Core Mission and Critical Rules are recommended (warnings). A separate check-agent-originality.sh compares new agents against the whole roster using 8-word shingle overlap and fails at 40% similarity by default, so a find-and-replace re-skin of an existing agent is rejected.
divisions.json is the single catalog of divisions (label, icon, colour). Its own note says scripts/check-divisions.sh fails CI if the list disagrees with the directories on disk or with the AGENT_DIRS arrays in convert.sh and lint-agents.sh.
3. Architecture
One source, many tools
scripts/convert.sh is the heart of it. It sources scripts/lib.sh for shared frontmatter, slug and fence-parsing helpers, loops over the agent directories, and calls one convert_<tool> function per target. Claude Code and Copilot need no conversion (the installer copies the source file), so there are 15 converted targets in integrations/. The shell dispatch is explicit about the writes it makes: the header says the script never touches your config directories, and installing is a separate script.
The data model lives in lib.sh
get_field reads one frontmatter value with awk. Its comments explain the edge cases it was written for: quoted scalars lose their outer quotes, and a plain scalar that continues onto indented lines is folded into one line, because otherwise “three healthcare agents” had their descriptions silently truncated.
# scripts/lib.sh
# get_body <file> — file contents with the leading frontmatter block stripped.
get_body() {
awk 'BEGIN{fm=0} fm<2 && /^---$/{fm++; next} fm>=2{print}' "$1"
}
# slugify <string> — "Frontend Developer" -> "frontend-developer"
slugify() {
printf '%s' "$1" | tr '[:upper:]' '[:lower:]' \
| sed 's/[^a-z0-9]/-/g; s/--*/-/g; s/^-//; s/-$//'
}
Everything downstream keys off the slug derived from name:. The file’s own comment says agent_slug is the “single source of truth so convert + install always agree”.
Each converter is a thin projection
The simplest converter, Antigravity, keeps the body and rewrites the frontmatter to the standard Agent-Skills fields. The comment in the source notes it stays deterministic by not stamping a date:
# scripts/convert.sh (convert_antigravity)
slug="agency-$(slugify "$name")"
...
cat > "$outfile" <<HEREDOC
---
name: $(yaml_quote "$slug")
description: $(yaml_quote "$description")
---
${body}
HEREDOC
The OpenClaw converter is the cleverest. It splits one persona into three files. Sections whose ## header contains words like identity, communication, style, critical rules or learning and memory go to SOUL.md (who the agent is); everything else (mission, deliverables, workflow) goes to AGENTS.md (what it does); and IDENTITY.md is built from emoji and vibe. A fence-aware loop makes sure a ## line inside a code block is not mistaken for a section boundary, which the source credits to issue 849.
# scripts/convert.sh (convert_openclaw)
if [[ "$header_lower" =~ identity ]] ||
[[ "$header_lower" =~ learning.*memory ]] ||
[[ "$header_lower" =~ communication ]] ||
[[ "$header_lower" =~ style ]] ||
[[ "$header_lower" =~ critical.rule ]] ||
[[ "$header_lower" =~ rules.you.must.follow ]]; then
current_target="soul"
else
current_target="agents"
fi
That split is a design opinion made executable: persona and boundaries belong in the soul file, operating procedure belongs in the agents file. It also explains why the lint recommends exactly the Identity, Mission and Critical Rules headings.
Hermes gets a different treatment. Installing hundreds of agents as skills would bloat the tool surface, so convert.sh --tool hermes calls build-hermes-plugin.py to generate one plugin, agency-agents-router. Per its README, Hermes sees four tools (agency_agents_search, agency_agents_inspect, agency_agents_load, agency_agents_delegate) while the full roster sits on disk in data/agents.json and is searched lazily.
Selection happens by slug
The installer supports --tool, --division, --agent and --agents-file. All of them reduce to one predicate. The per-agent installers check it for each candidate file (roster and plugin targets such as Aider, Windsurf and Hermes handle selection separately):
# scripts/install.sh
slug_allowed() {
$SELECTION_ACTIVE || return 0
local s="${1#agency-}"
grep -qxF "$s" <<< "$_ALLOWED_SLUGS"
}
Some converted targets (the skill-style ones such as Antigravity) prefix slugs with agency- while source slugs do not, so the prefix is stripped before comparing. The installer also encodes a hard-won limit: the README warns OpenCode registers only about 119 agents and silently drops the rest (an upstream bug), so install.sh keeps a per-tool capacity and warns when a selection would exceed it.
4. The core design idea: coordination as documents, not code
A roster alone is a bag of personas. The strategy/ directory is what makes it a team, and it is plain markdown too.
NEXUS (“Network of EXperts, Unified in Strategy”) defines seven phases (Discover, Strategize, Scaffold, Build, Harden, Launch, Operate) with a quality gate between each, and three modes: NEXUS-Full (all agents, 12 to 24 weeks), NEXUS-Sprint (15 to 25 agents, 2 to 6 weeks) and NEXUS-Micro (5 to 10 agents, 1 to 5 days). strategy/runbooks.json provides machine-readable rosters for four scenarios (startup MVP, enterprise feature, marketing campaign, incident response), and the README shows how to feed one to install.sh --agents-file so a runbook’s team installs exactly as listed.
The mechanism in Phase 3 is the Dev-QA loop. The Phase 3 playbook gives it as pseudo-code:
FOR EACH task IN sprint_backlog (ordered by RICE score):
1. ASSIGN task to appropriate Developer Agent
2. Developer IMPLEMENTS task
3. Evidence Collector TESTS task
4. IF verdict == PASS: mark complete, move to next task
ELIF verdict == FAIL AND attempts < 3:
send QA feedback to Developer
Developer FIXES specific issues
return to step 3
ELIF attempts >= 3: ESCALATE to Agents Orchestrator
The same rule lives in the Agents Orchestrator persona itself (“If retries < 3: Loop back to dev with QA feedback; if retries >= 3: Escalate with detailed failure report”), so the playbook and the agent that executes it say the same thing. The master strategy’s Phase 3 quality gate lists measurable criteria, for example all tasks passing QA, P95 under 200 ms and LCP under 2.5 s, 95%+ brand consistency and zero open P0/P1 issues, each with a required evidence type.
Handoffs are standardised too. strategy/coordination/handoff-templates.md begins with the claim that consistent handoffs prevent context loss, “the #1 cause of multi-agent coordination failure”, and provides templates with metadata, current state, acceptance criteria and evidence expectations, plus separate PASS and FAIL QA verdict templates.
Finally, the Reality Checker persona is deliberately adversarial: its description says it defaults to “NEEDS WORK” and requires overwhelming proof for production readiness, and Phase 4 uses it as the gatekeeper. Pairing a builder-biased loop with a sceptic-by-default final gate is the quality design of the whole system.
5. Takeaways
- One flat file per agent is a strong data model. Frontmatter plus a conventional body is enough to drive linting, conversion, install and catalog tooling from the same source.
-
Fan out at build time, not run time. Generated
integrations/<tool>/output keeps each tool’s quirks in its own converter function. - Encode opinions in the converter. The OpenClaw soul/agents split makes the persona-versus-procedure distinction concrete.
- Offer lazy routing when the roster is huge. The Hermes plugin exposes four tools instead of hundreds of skills.
-
Put selection in one predicate.
slug_allowedlets divisions, single agents and runbook files share a single installer path. - Make orchestration reviewable. Phases, gates, retries and handoffs are markdown you can read, diff and edit, with measurable thresholds and a hard retry cap.
- Mind the caveats. More agents is not automatically better: the OpenCode cap and the Hermes lazy router both exist because large rosters hurt, so install the division you need.
Want a specialist-agent team like this wired into your own tooling? Get in touch.
Click to load Disqus comments