Claude Code agents usually get attention for generating code snippets or automating coding tasks. This curated collection takes a different angle — it assembles over 30 specialized Claude Code sub-agents that act as architectural consultants. Instead of spitting out raw code, these agents provide decision frameworks, best practices, and nuanced guidance tailored to specific languages, frameworks, infrastructure, and LLM engineering roles.
a collection of domain-specific claude code agents focusing on architecture and best practices
The repo is organized as markdown files, each defining an agent specialized in a particular domain. You’ll find experts for programming languages like Python, Go, and Rust; framework specialists for React, Vue, Django, Spring Boot; and infrastructure agents covering AWS, Docker, Kubernetes, and Terraform. There’s also a notable focus on LLM engineering roles such as prompt engineering, retrieval-augmented generation, multi-agent systems, and fine-tuning.
Each agent is basically a markdown file with instructions, deployed within the Claude Code environment. They’re designed not as code generators but as architectural consultants that offer decision frameworks and ecosystem navigation. This flips the usual Claude Code paradigm, which often focuses on generating code snippets or automating tasks.
Under the hood, this architecture relies on Claude Code’s agent composition framework. Agents can be invoked automatically via a PROACTIVELY flag or manually by tagging them with @agent-name. This allows for dynamic invocation depending on the coding context or explicit user request.
modular markdown-based agent definitions with a guidance-first approach
What distinguishes this repo is its modular, markdown-driven approach to defining specialized AI agents. By representing agents as markdown files with curated instructions, the repo achieves a lightweight and extensible design. It avoids complex runtime dependencies or code bundling, making it easy to update or add new agents by simply adding or modifying markdown files.
This design favors clarity and separation of concerns — each agent focuses on delivering domain-specific architectural consulting rather than generating code. The tradeoff here is that this approach might limit interactive capabilities or dynamic behavior compared to agents implemented with code hooks or integrated plugins.
The code quality is surprisingly clean for a markdown-based collection: the instructions are well-organized, categorized into 12 domain folders, and follow consistent naming conventions. The README clearly documents usage patterns and installation steps, which lends itself well to practical adoption.
The reliance on manual copying of markdown files into the user’s Claude Code agents directory is a simple but effective deployment model. It trades off automated installation or plugin management for straightforward, transparent setup.
quick start: setting up and using the agents
Getting started requires cloning the repository and copying the markdown agent files into your Claude Code agents directory. Here’s the exact sequence:
# Clone the repo
git clone https://github.com/supatest-ai/awesome-claude-code-agents.git
cd awesome-claude-code-agents
# Copy all agent markdown files to Claude Code's agents folder
cp */*.md ~/.config/claude-code/agents/
# Verify the installed agents
claude-code agents list
Once installed, agents can be invoked automatically if marked with the PROACTIVELY flag, meaning Claude Code will use them contextually based on your current task. You can also explicitly invoke an agent by typing @agent-name in your message.
Agents are suggested contextually based on your files and tasks, so you get relevant architectural consulting without explicitly calling the agent every time.
verdict: useful for architects and developers seeking AI-guided architectural insight
This repo offers a practical and straightforward approach to composing AI agents focused on architectural guidance rather than code generation. It’s a solid fit for developers and architects looking for AI assistance in making technology and architecture decisions across multiple domains.
The markdown-based design keeps things simple and extensible, though it may lack the dynamic interactivity of code-driven agents. Installation is manual but well-documented.
If you want to integrate AI agents as architectural consultants into your Claude Code workflows, this repo is a good starting point. It’s less about automating code and more about augmenting your architectural decision-making with specialized expert agents.
→ GitHub Repo: supatest-ai/awesome-claude-code-sub-agents ⭐ 160