agency-agents: Agency Agents: The Repo Turning Markdown Into a Portable AI Department
A universal agent library for Claude Code, Cursor, Aider, Windsurf, and more, built to package expertise, enforce trade-offs, and ship personality as configuration.
- Agency Agents turns prompt writing into packaging, so one canonical markdown file can become tool-specific agents without changing the underlying identity.
- Its real innovation is not volume, but structure: frontmatter, mission, rules, and vibe make expertise portable and auditable.
- The repo behaves like software, with conversion scripts and linting that enforce quality instead of relying on copy-pasted editor settings.
- Its strongest claim is that AI customization can scale across teams only when personality is treated as a compiled artifact.
Most prompt libraries stop at clever wording. agency-agents tries to do something more durable: define a specialist once, then compile it into the dialects of different AI tools. That shift matters because the problem is no longer how to talk to one model. It is how to keep one expert consistent across a fragmented toolchain.
Why This Repo Feels Like an AI Operating System
The mental model here is simple and a little disruptive. You are not opening a chat and hoping for the best. You are activating a role with an opinionated identity, a mission, and rules that should survive tool boundaries.
This is exactly what the AI agent community needs! Impressive to see such a comprehensive framework for building AI agencies with specialized agents. Great work!
That is why the repo reads more like infrastructure than inspiration. It does not merely provide roles for a coding assistant. It packages expertise so the same editorial voice can show up in Claude Code, Cursor, Aider, Windsurf, and other surfaces without being rewritten by hand each time.
The Canonical Agent File
The source of truth is a Markdown file with YAML frontmatter and structured sections. That format does two things at once. It stays human-readable, and it gives the repo enough structure to transform the file into multiple downstream representations.
---
name: Software Architect
description: Designs systems that survive the team that built them
color: blue
emoji: 🏗️
---
# Identity
# Mission
# Critical Rules
# VibeThat structure makes the agent more than a prompt. It becomes legible, diffable, and reviewable. If the personality or constraints change, you are editing source code, not pasting a better paragraph into a settings dialog.
What convert.sh Actually Does
The repo’s signature move is transpilation. One agent definition is parsed and rewritten into formats that different AI tools expect. That lets the project keep a single canonical form while still meeting each ecosystem on its own terms.
That is the part many people miss. The repo is not a pile of clever prompts. It is a build pipeline. Once you see it that way, the shell scripts stop looking like utility code and start looking like the enforcement layer for a standard.
| Manual editor rules | agency-agents |
|---|---|
| Quick to start, easy to forget | Structured source file with a repeatable schema |
| Different rules in each tool | One canonical agent compiled into many formats |
| Quality depends on the author’s memory | Linting enforces minimum standards |
| Hard to reuse across a team | Portable enough to distribute and version |
| Maintenance means editing several places | Maintenance means editing one source |
Why Personality Is a Feature, Not Decoration
The repo’s most interesting design choice is that it treats tone as part of the interface. Fields like vibe are not ornamental. They are a way to steer the model toward a repeatable stance, not just a generic answer.
That matters because most AI assistants fail in the same quiet way. They become polite, broad, and forgettable. Agency Agents tries to make each specialist narrower, more judgmental, and more useful by making its constraints visible and reusable.
The Linter Is the Secret Quality Gate
If the schema is the source code, linting is the release gate. The repository enforces the presence of core sections and minimum substance so contributed agents do not collapse into a decorative name with no operational personality.
./scripts/lint-agents.sh
./scripts/convert.sh
./scripts/install.shThis is where the project starts to feel mature. It uses the same boring mechanisms that keep software healthy: validation, automation, and repeatable output. That is why it scales better than a shared folder full of clever one-off prompts.
Why This Beats Writing One-Off Rules in Your Editor
The trade-off is straightforward. Manual setup is faster today. A standardized library wins when you care about reuse, auditability, and team consistency.
| Dimension | Manual setup | agency-agents |
|---|---|---|
| Setup effort | Low | Moderate |
| Portability | Weak | Strong |
| Consistency | Depends on the author | Enforced by schema |
| Quality control | Ad hoc | Scripted and linted |
| Tool compatibility | Usually one tool at a time | Multiple tools from one source |
| Maintenance burden | Scattered | Centralized |
| Team reuse | Hard | Practical |
That is also why the project reaches beyond coding. Once you can define a good agent once and compile it everywhere, the idea naturally expands into marketing, sales, design, and community roles. The repo is really proposing a way to standardize expert behavior, not just code help.
The Bigger Bet
The long-term thesis is bigger than any single IDE. This repo treats AI work roles as something you can package, version, lint, and distribute. That is a very software-native answer to a very human problem: how to make expertise repeatable without making it bland.
If that bet holds, the future is not one assistant with endless taste. It is a library of specialists with clear boundaries, consistent behavior, and a build system that keeps them honest.
