Your coding agent has one default personality: capable generalist. Ask it to review an authentication flow and you get sensible, forgettable advice. Ask a security reviewer with a threat model and a checklist, and you get findings. That difference costs nothing but a markdown file, which is why agency-agents reached 149,312 stars.
The library is genuinely useful. It is also a folder of files on one machine, which becomes the limit the moment more than one person needs the roles to mean something. This article covers what you get, how to install only the part you want, and the difference between a role definition and an Agent a team can assign work to.
TL;DR
This is one of five deep dives from our roundup of open source tools that extend coding agents.
agency-agents is a collection of more than 300 agent role definitions across roughly 20 categories, MIT licensed, installable into Claude Code, Cursor, Codex, Gemini CLI, OpenCode, and about a dozen other tools with one command. Each file describes an identity, a working process, deliverables, and a definition of done. A role changes how an agent frames a task; it does not give the agent information it lacks, and it does not persist past the session. Install one division, edit the files to match your stack, and promote the ones you reach for weekly into saved configurations a team can assign.
What you are installing
Counted from the repository tree on September 1, 2026, there are 312 markdown files across 20 top-level category folders. The repository README still says “230+”, which is stale.
| Division | Files | Division | Files |
|---|---|---|---|
| engineering | 59 | testing | 9 |
| specialized | 58 | paid-media | 7 |
| marketing | 36 | project-management | 7 |
| game-development | 21 | academic | 6 |
| integrations | 18 | spatial-computing | 6 |
| strategy | 16 | support | 6 |
| gis | 13 | finance | 5 |
| security | 12 | product | 5 |
| design | 10 | healthcare | 3 |
| sales | 9 | examples | 6 |
The engineering division is where most teams start, and the specificity is higher than a prompt collection usually reaches. Alongside Frontend Developer and Backend Architect there is a Network Engineer scoped to Cisco IOS-XE and Juniper Junos, an Embedded Firmware Engineer for ESP32 and STM32 targets, an Incident Response Commander for post-mortems and on-call readiness, and a Codebase Onboarding Engineer written to explore a repository read-only and state facts rather than propose changes.
That last one shows the pattern working. A read-only role with an explicit no-edit mandate is a different tool from your default agent, and it costs one file.
Installing only what you need
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
./scripts/install.sh # interactive
./scripts/install.sh --tool claude-code --division engineering,security
./scripts/install.sh --tool cursor --agent frontend-developer
./scripts/install.sh --list teams
./scripts/install.sh --tool opencode --division engineering --dry-run
One warning the repository documents and most write-ups skip: OpenCode’s runtime registers roughly 119 agents and silently drops the rest. Installing a subset with --division keeps you under the limit, and the installer warns you when a selection would exceed it. Silent truncation is the worst failure mode available, because the role you wanted is missing and nothing says so.
Even without that bug, installing all 300 is a mistake. A roster you cannot remember is a roster you will not use. Install the division you work in, read five files, and delete the ones that do not match how your team operates.
Where a role definition stops
A role is a frame. It sets what the agent looks for, what format it produces, and what it treats as done. That is worth more than it sounds, because much of what makes agent output weak is not the model being wrong, it is the model optimising for the wrong shape of answer.
Two things a role cannot do.
It cannot supply information the model does not have. A Backend Architect role produces well-organised code against an interface it inferred. The role improved the structure. It did not make the result correct.
It cannot survive the session. You activate a role, it does a task, the terminal closes. Tomorrow you type the activation again. Nine of the divisions in this repository describe jobs that only exist inside an organisation, and the tool that installs them has no concept of one. There is no assignment, no record of what the security reviewer found last Tuesday, and no way for a colleague to see any of it.
From a role definition to an assignable Agent
A role definition is a prompt you retype. An Agent in Sharkly is a saved configuration: instructions, runtime, skills, repositories, and environment. That is the durable version of what a file in ~/.claude/agents/ is reaching for.
The pieces have one job each. The Agent defines how work should be handled. The Computer supplies the host and local resources. The Runtime performs the actual agent session, using the coding tool your team already installed. The Task remains the shared record.
Sharkly is not a replacement for Claude Code, Codex, or the roles in this repository. It adds the shared task, Computer, context, control, and review layer around them. Model usage continues through the subscriptions or API keys configured in those tools.
The division concept maps directly. A Crew is a reusable group of People and Agents coordinated by one leader Agent. Crews run leader-first: the leader reads the task context, decides which members to involve, and brings their results back into one Task, rather than every specialist starting at once. That is what agency-agents gestures at with its eight divisions and cannot execute, because a folder of files has no leader and no shared task to return to.
Execution, blockers, results, and follow-up discussion return to the task timeline. When someone asks what the security reviewer found, the answer is in the Task.
Use the repository as a library, not as a team
Use agency-agents directly when you are one person, working locally, and you want better framing on today’s work. Install a division, read the files, get value in twenty minutes.
Use saved Agents when the role has to be reused by more than one person, when the output needs review before it counts, or when someone will ask in three months what a role produced and why. The threshold is not team size. It is whether the role has to outlive the session.
The practical workflow is to treat the repository as source material. Take the file structure, which is the genuinely reusable part, replace the generic content with your stack and your definition of done, and promote anything you reach for twice a week into a saved configuration. The good files all share a shape: identity, mission, ordered process, deliverables with a format, and success criteria. A review role with a seven-step process produces consistent output across sessions. One without it produces whatever the model felt like that day.
Agents research, execute, test, and report. People set direction, grant authority, and accept the result.
Frequently asked questions
Does agency-agents work with tools other than Claude Code? Yes. A conversion script generates integration files per tool, and install.sh --tool targets one. Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Copilot, Windsurf, Aider, and Kimi Code are among the supported targets. There is also a desktop app for macOS, Linux, and Windows.
Should I install all 300 roles? No. On OpenCode you cannot, because roughly 119 register and the rest are dropped without warning. On other tools you can and will not use most of them. Install by division.
Do roles make an agent more capable? They make it better directed. Consistency and output format improve. Knowledge of facts the model never had does not change.
Is this the same as an agent framework? No. A framework gives you runtime orchestration in code. agency-agents gives you markdown files that change how an existing agent behaves. Different layer, no overlap.
How does this relate to Sharkly Skills? A Skill is a capability you attach to an Agent’s configuration, so it is reused with that Agent rather than reinstalled per machine. Role definitions from this repository are good raw material for writing them.
The short version
agency-agents is the best available version of one idea: an agent does better work when it knows what role it is playing. Install a division, read the files, edit them into something that matches your team.
Then be clear about the boundary. The roles do not know facts your model was never given, and they do not persist into anything a team can see or review. A roster is a good start. It is not an organisation. Sharkly holds the other half: the Task is the shared record, execution runs on Computers you connect through the runtimes you already pay for, and results return somewhere a person can review and accept them.
