If you've been scrolling through X or GitHub lately, you've probably seen msitarzewski/agency-agents pop up in your feed. Whenever a repo starts trending like this, people usually hype it up like it's some brand new AI breakthrough, so to be clear upfront: it's not a new model, a runtime framework, or a standalone coding tool. It's literally just a public repository full of markdown files containing detailed system prompts.

That said, once you look past the hype, it's actually pretty useful—especially if you're tired of writing your own custom instructions from scratch or if your coding assistant keeps agreeing with every bad architectural idea you throw at it.

What's actually in the repo

Most prompt repositories on GitHub are filled with generic one-liners like "act as a senior engineer and write clean code." Those rarely change how an LLM behaves once you get past the first two messages.

agency-agents takes a different approach by organizing over a hundred multi-page markdown files into clear categories (engineering, testing, design, product, etc.). Instead of vague encouragement, each file outlines specific rules, edge cases to watch out for, formatting expectations, and explicit instructions on when the model should push back.

For example, if you're refactoring a messy script or designing a new data pipeline, you can load up the reality-checker.md or software-architect.md file. Instead of blindly generating boilerplate and telling you every idea is great, the model actually critiques your structure, points out potential bottlenecks, and forces you to simplify things before writing code.

How to set it up locally

Since everything in the repo is just plain text, there are no dependencies to install, no Docker containers to spin up, and no background daemons eating RAM. You just clone the repository somewhere permanent on your machine and point whatever tool you already use to the specific file you need.

1. Clone the repo locally

git clone https://github.com/msitarzewski/agency-agents.git ~/.local/share/agency-agents 

2. Pick a file and wire it into your tool

Depending on your workflow, you just symlink or copy the markdown file into your project directory:

  • Claude Code / CLI workflows: Symlink the file to CLAUDE.md in your project root so it loads automatically when you start a session (just make sure to add CLAUDE.md to your .gitignore if you're working on a shared repo):
 ln -s ~/.local/share/agency-agents/engineering/software-architect.md ./CLAUDE.md 
  • Cursor / Windsurf: Copy or symlink the .md file straight into your project's .cursor/rules/ directory.
  • Local models (Ollama / llama.cpp): If you run models locally in the terminal, you can pass the file contents directly into your system prompt flag:
 llama-cli -m your-model.gguf --system-prompt "$(cat ~/.local/share/agency-agents/testing/reality-checker.md)" -p "Review this code" 
  • Neovim / Editor plugins: If you use local AI plugins like Avante, CodeCompanion, or similar setups, you can simply point your custom system prompt path to whichever .md file fits the task you're working on.

(There's also a small Tauri app called agency-agents-app linked in the repo if you prefer clicking through a GUI to copy them into your editor configs, though symlinking in the terminal takes two seconds).

A practical way to use it without clutter

The easiest mistake to make with a repo this big is trying to combine multiple personas at once or keeping a heavy system prompt active all the time.

A better workflow is swapping them out depending on what phase of a project you're in. Use a planning or architecture persona when you're mapping out how components talk to each other, switch to a standard implementation prompt while writing the actual functions, and then swap in a testing or reality-checker file right before you commit to catch edge cases you missed. Because they're just symlinks, switching roles takes a single terminal command.

Worth keeping in mind

At the end of the day, it's still just prompt engineering. If you're running a smaller local model with a tight context window, loading a 2,000-word markdown file will eat up a noticeable chunk of your token budget before you even paste your code. It works best when you pick one focused role for the exact problem in front of you, or trim down the markdown files to keep only the rules relevant to your stack.

Curious if anyone else here keeps a local folder of system prompts like this, or if you've found better repos worth cloning.

About the Author

I write about artificial intelligence, software engineering, emerging developer tools, and the technologies shaping how modern products are built.

Interested in collaborating?

If you're a company or team working in AI or developer technology, I'd love to hear about what you're building. I'm always interested in discovering new projects and sharing technologies that I genuinely find useful with my readers.

You can reach me at maamrihayder@gmail.com.