Skip to content
FLAVIO COPES
flaviocopes.com
2026

A hands-on guide to The Agency, a collection of AI agents

How to install and use The Agency (agency-agents), a collection of specialized AI agents for Claude Code, Cursor, and other coding tools

~~~

If you use Claude Code or Cursor, you know that a generic “act as a senior developer” prompt only gets you so far.

The Agency is a free, open source collection of AI agents that does better. Each agent is a specialist, with its own personality, its own rules, and a clear idea of the work it produces.

In this post I’ll show you how to install it, use an agent, look at how an agent is built, and write your own.

What is The Agency?

The Agency is a GitHub repository with 232 AI agents, grouped into 16 divisions.

Each agent is just a Markdown file. The file says who the agent is, what it’s good at, the rules it follows, and what its output should look like.

A few of the agents you get:

And many more, from marketing to game development to GIS.

The idea is simple. Instead of one assistant that knows a little about everything, you get a team of specialists and call the right one for each job.

Why a specialist beats a generic prompt

When you tell an AI “you are a code reviewer”, you give it a role and not much else.

An agent file gives it a lot more: a role, a personality, a checklist, what to prioritize, and examples of good output.

You feel the difference in the results. The agent doesn’t just answer. It answers like someone who does this for a living.

Don’t overthink it at the start. Install it, point one agent at a real task, and you’ll see.

Prerequisites

You need two things:

The agents are plain text files, so there’s nothing to compile or run.

Getting the repository

Clone the repository:

git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

The agents are grouped into folders by division. Have a look:

ls

You’ll see folders like engineering, design, marketing, and security. Each one holds the agent files for that division.

Open one to see what an agent looks like:

cat engineering/engineering-code-reviewer.md

We’ll come back to this file. First, let’s install the agents so we can use them.

Installing for Claude Code

The repository ships an install script. To install every agent for Claude Code:

./scripts/install.sh --tool claude-code

This copies the agent files into ~/.claude/agents/, the folder Claude Code reads agents from.

Tip: if the script isn’t executable, run chmod +x scripts/install.sh first.

If you only want one division, copy the files yourself. For example, just the engineering agents:

cp engineering/*.md ~/.claude/agents/

Both do the same thing. The script is just handier when you want more than one folder.

Using your first agent

Open Claude Code in any project and ask it to use an agent by name:

Use the Frontend Developer agent to build a responsive pricing card component in React.

Claude Code loads the Frontend Developer agent and answers in character: performance-focused, accessibility-aware, using modern patterns.

Try the same request with and without the agent. With it, you’ll see things like Core Web Vitals, ARIA labels, and responsive design come up on their own. Those are the agent’s rules at work.

Here’s another one I use a lot:

Use the Code Reviewer agent to review the changes in my last commit.

Instead of a vague “looks good”, you get structured feedback, with issues marked as blockers, suggestions, or nits.

What’s inside an agent file

Let’s open one up. Every agent is a Markdown file with two parts: a frontmatter block at the top, and the agent’s instructions below it.

Here’s the top of the Frontend Developer agent:

---
name: Frontend Developer
description: Expert frontend developer specializing in modern web technologies, React/Vue/Angular frameworks, UI implementation, and performance optimization
color: cyan
emoji: 🖥️
vibe: Builds responsive, accessible web apps with pixel-perfect precision.
---

The frontmatter is the metadata. name is how you call the agent. description tells the tool when this agent is a good fit. The rest is flavor.

Below the frontmatter is the actual content. It usually follows the same shape:

Here’s a slice of the Code Reviewer’s rules:

## 🔧 Critical Rules

1. **Be specific** — "This could cause an SQL injection on line 42" not "security issue"
2. **Explain why** — Don't just say what to change, explain the reasoning
3. **Suggest, don't demand** — "Consider using X because Y" not "Change this to X"
4. **Prioritize** — Mark issues as 🔴 blocker, 🟡 suggestion, 💭 nit
5. **Praise good code** — Call out clever solutions and clean patterns

See how concrete this is. The rules don’t say “be helpful”. They say exactly how to phrase feedback. That’s why the output reads like a real reviewer.

Every one of the 232 agents is a variation of this same format.

Using it with Cursor

The Agency isn’t only for Claude Code. The same agents work in Cursor, Copilot, and many other tools.

The agents are stored in Claude Code’s format. For other tools, you run a conversion step first, then install.

For Cursor, go to your project folder and run:

cd /your/project
/path/to/agency-agents/scripts/install.sh --tool cursor

This writes .mdc rule files into .cursor/rules/ in your project, and Cursor picks them up automatically.

Then reference an agent in your prompt:

Use the @security-engineer rules to review this code.

Using it with other tools

The Agency also supports GitHub Copilot, Gemini CLI, OpenCode, Aider, Windsurf, Codex, and more.

For these, generate the integration files first:

./scripts/convert.sh

Then run the installer with no arguments to get an interactive wizard:

./scripts/install.sh

The wizard scans your machine, sees which tools you have, and shows a checklist. You pick what you want, and it installs the agents in the right format and place for each tool.

To skip the wizard, target a tool directly:

./scripts/install.sh --tool gemini-cli
./scripts/install.sh --tool codex
./scripts/install.sh --tool aider

Installing only the teams you need

232 agents is a lot. You rarely need all of them, and some tools cap how many they’ll load.

You can install just the divisions you care about:

./scripts/install.sh --tool claude-code --division engineering,security

Or pick individual agents:

./scripts/install.sh --tool cursor --agent frontend-developer,ui-designer

To see every team and how many agents it has:

./scripts/install.sh --list teams

My advice: start small. Install one or two divisions you’ll actually use. You can add more later.

A real example: shipping a small feature

Say we’re adding a “save for later” feature to an app. Here’s how I’d use the agents, one step at a time.

First, design the data side with the Backend Architect:

Use the Backend Architect agent to design an API and database schema
for a "save for later" feature on a products app.

You get endpoints, a schema, and notes on scaling.

Then build the UI with the Frontend Developer:

Use the Frontend Developer agent to build the "save for later" button
and saved items list in React.

You get accessible, responsive components.

Then check the database side with the Database Optimizer:

Use the Database Optimizer agent to review the schema and suggest indexes.

And before you commit, run the Code Reviewer:

Use the Code Reviewer agent to review all the changes.

Each step gets a specialist with its own checklist. That’s more thorough than asking one generic assistant to “build this feature”.

Letting one agent run the others

For bigger tasks, The Agency includes an Agents Orchestrator. Its whole job is to coordinate the other agents.

Instead of calling agents one by one, you describe the goal:

Use the Agents Orchestrator agent to plan and coordinate building
a complete user authentication system.

It breaks the work down and decides which specialists to bring in at each step. Handy when a task touches many areas and you don’t want to manage the handoffs.

The examples/ folder has full multi-agent walkthroughs, where several agents work on one product brief together. They’re worth a read.

Writing your own agent

Agents are just Markdown files, so you can write your own.

Let’s build a small one: an agent that writes good Git commit messages.

Create a new file in the engineering folder:

touch engineering/engineering-commit-writer.md

Add the frontmatter:

---
name: Commit Writer
description: Writes clear, conventional Git commit messages that explain the why, not just the what
color: green
emoji: ✍️
vibe: Turns a messy diff into a commit message you'll thank yourself for later.
---

Then the body. Keep it focused, following the same shape as the built-in agents:

# Commit Writer Agent

You are **Commit Writer**, an expert at writing clear Git commit messages.

## Your Core Mission

Turn a set of changes into a commit message that a teammate will
understand in six months.

## Critical Rules

1. Use the conventional commits format: `type: short summary`
2. Keep the summary under 50 characters
3. Explain the *why* in the body, not just the *what*
4. One commit message per request, no options to choose from

It helps to show the agent what good output looks like, so add a sample message to the file:

fix: prevent crash when cart is empty

The checkout button assumed at least one item.
Added a guard so an empty cart shows a message instead.

Save it, then install it:

cp engineering/engineering-commit-writer.md ~/.claude/agents/

Now use it like any other agent:

Use the Commit Writer agent to write a commit message for my staged changes.

That’s the whole loop. Write a Markdown file, drop it in the agents folder, call it by name.

Notice the body doesn’t need to be long. A clear mission and a few sharp rules are enough to change how the AI behaves.

Regenerating after changes

One thing to remember. If you use a tool other than Claude Code, the agents get converted into that tool’s format.

So when you add or edit an agent, regenerate the integration files:

./scripts/convert.sh

Then install again for your tool. If you only changed agents for Claude Code, you can skip this, since Claude Code reads the original files directly.

You can also regenerate one tool at a time:

./scripts/convert.sh --tool cursor

One gotcha with OpenCode

If you use OpenCode, know that it only loads a limited number of agents and quietly drops the rest. Install all 232 at once and you’ll hit that cap.

The fix is the advice from before: install a subset with --division. The installer warns you when a selection would go over the limit.

It’s a good reason to be picky anyway. You don’t need every agent, and a small set is easier to work with.

Make it yours

What I like about The Agency is that there’s no magic. Every agent is a file you can open, read, and change.

So tweak the rules to match how you work, and write new agents for the tasks you do all the time.

It’s on GitHub, MIT licensed, and free to use.

Tagged: Tools · All topics
~~~

Related posts about tools: