supatest-ai/awesome-claude-code-sub-agents: Expert Consultant Agents

supatest-ai/awesome-claude-code-sub-agents: Expert Consultant Agents for Architectural Decisions

Developers increasingly rely on AI coding assistants, but most tools optimize for code generation rather than the harder problem: making the right architectural choices before writing a single line. supatest-ai/awesome-claude-code-sub-agents addresses this gap with a collection of specialized Claude Code agents designed as expert consultants that provide architectural guidance, decision frameworks, and best practices.

What is supatest-ai/awesome-claude-code-sub-agents?

supatest-ai/awesome-claude-code-sub-agents is an open-source repository (165 stars, 27 forks, MIT License) maintained by supatest-ai that provides a structured collection of Claude Code subagents. These aren't code-generation prompts—they're domain-specific consultants invoked through Claude Code's agent system to help developers make informed technology choices.

The repository's core thesis: AI assistance is most valuable at decision points where experience gaps cost projects weeks of refactoring. Each agent focuses on a specific domain—programming languages, frameworks, DevOps^{↗ Bright Coding Blog}, LLM engineering, industry compliance—and provides structured guidance on when to use what, why certain patterns apply, and how to avoid common pitfalls.

The project is actively maintained (last commit: 2025-09-19) and follows a guidance-first philosophy explicitly contrasted with traditional code-generation approaches. Rather than outputting "Here's React^{↗ Bright Coding Blog} code," the React Architect agent answers "When to choose React vs Vue vs Angular based on team size, performance requirements, and ecosystem constraints."

This distinction matters because Claude Code, Anthropic's CLI coding tool, supports extensible agents that can be invoked automatically (via PROACTIVELY in descriptions), manually with @agent-name, or contextually based on files being edited. The repository provides ready-made agents across 12 categories with installation and usage documentation.

Key Features

Structured Agent Taxonomy: The repository organizes 30+ agents across 12 categories: Languages (10 agents), Frameworks (5), Development Workflows (12), Architecture (3), Testing (2), Performance (1), Data Science (1), LLM Engineering (6), AI/ML (1), DevOps (4), Industries (2), and Templates (2). This coverage spans from Python^{↗ Bright Coding Blog} ecosystem decisions to HIPAA compliance guidance.

Guidance-First Design Philosophy: Every agent follows explicit design principles: decision frameworks over implementations, architectural focus over syntax, production-ready patterns, and ecosystem navigation. The README documents this as an "80/20 Guidance/Code" ratio, with agents running 300-800 lines of focused content.

Claude Code Native Integration: Agents use the official Claude Code subagent format with YAML frontmatter specifying name, description (with PROACTIVELY for auto-invocation), and tools (Read, Write, Edit, Bash, Grep, Glob, MultiEdit). This ensures compatibility with Claude Code's agent discovery and invocation mechanisms.

Three Invocation Modes: The repository documents automatic invocation for context-aware agents, manual @agent-name invocation for specific expertise, and file-based contextual suggestions—giving developers flexibility in how they engage consultant agents.

Template System for Custom Agents: Two templates (basic and advanced) plus an agent development guide enable teams to create domain-specific consultants for internal technologies or proprietary frameworks.

Research-Based Sizing: The documented 300-800 line target per agent reflects analysis of successful Claude Code agent repositories, balancing comprehensiveness with model context window efficiency.

Use Cases

Technology Selection for Greenfield Projects: A team evaluating backend frameworks can invoke the Python Expert, Go Expert, or Java Expert to receive structured decision matrices comparing Django vs FastAPI vs Flask, or Spring Boot vs alternatives, with explicit trade-offs around concurrency models, ecosystem maturity, and hiring pool.

LLM Application Architecture: The LLM Engineering category addresses a rapidly evolving domain where best practices crystallize slowly. The RAG Architecture Expert provides vector database selection guidance; the LLMOps Engineer covers production deployment patterns; the Multi-Agent Systems Architect handles orchestration complexity—critical for teams building on [INTERNAL_LINK: retrieval-augmented generation systems] without established playbooks.

Compliance-Bound Industry Development: The FinTech Security Expert and Healthcare HIPAA Expert agents embed regulatory knowledge (PCI DSS, KYC/AML, HL7 FHIR) directly into the development workflow, reducing the risk of architectural decisions that require later compliance remediation.

Code Review Automation: The Code Review Master agent provides comprehensive review focusing on security, performance, and maintainability—useful for teams without dedicated senior reviewers or for pre-review automated checks.

DevOps Infrastructure Decisions: The Kubernetes Expert, Terraform Infrastructure Expert, and AWS^{↗ Bright Coding Blog} Cloud Architect agents help teams navigate the complexity of modern infrastructure without requiring every developer to become a platform engineer.

Installation & Setup

The repository provides explicit installation steps:

Prerequisite: Install Claude Code following the official installation guide.

Step 1: Clone the repository

git clone https://github.com/supatest-ai/awesome-claude-code-agents.git
cd awesome-claude-code-agents

Note: The clone URL in the README uses awesome-claude-code-agents rather than the repository's actual name awesome-claude-code-sub-agents. The repository's GitHub URL is https://github.com/supatest-ai/awesome-claude-code-sub-agents.

Step 2: Copy agent files to Claude Code's agents directory

cp */*.md ~/.config/claude-code/agents/

This copies all .md agent files from category subdirectories into Claude Code's agent configuration directory. The */* pattern matches files within the immediate subdirectories (languages/, frameworks/, etc.).

Step 3: Verify installation

claude-code agents list

This command lists all available agents, confirming successful installation.

Invocation methods:

• Automatic: Agents with PROACTIVELY in their description trigger based on context
• Manual: Type @agent-name in any Claude Code message
• Contextual: Claude Code suggests agents based on current files and tasks

Real Code Examples

The repository's documented agent format follows this YAML frontmatter structure:

---
name: agent-name
description: Brief description with PROACTIVELY keyword for auto-invocation
tools: Read, Write, Edit, Bash, Grep, Glob, MultiEdit
---

This is the required format for all Claude Code subagents. The name field uses kebab-case for unique identification. The description field's PROACTIVELY keyword determines automatic invocation behavior—critical for agents that should respond to context without explicit user requests. The tools list declares which Claude Code capabilities the agent can access, with the standard set being Read, Write, Edit, Bash, Grep, Glob, and MultiEdit.

The repository structure itself serves as documentation for agent organization:

awesome-claude-code-agents/
├── languages/
│   ├── python-expert.md
│   ├── javascript↗ Bright Coding Blog-typescript-expert.md
│   └── ...
├── llm-engineering/
│   ├── rag-architecture-expert.md
│   ├── llmops-engineer.md
│   └── multi-agent-systems-architect.md
└── templates/
    ├── basic-agent-template.md
    └── advanced-agent-template.md

This hierarchical organization enables both discovery and selective installation. A team working exclusively on LLM applications could copy only llm-engineering/*.md and templates/*.md, reducing agent noise.

The README provides one explicit invocation pattern for manual agent use:

@agent-name

Used within Claude Code's interactive interface, this prefixes a message to route it to the specified agent rather than the default assistant context.

Note: The README does not contain extensive code examples of agent internals or output samples. The above reflects the complete documented interface. For agent content examples, users must inspect individual .md files after installation.

Advanced Usage & Best Practices

Selective Agent Installation: Rather than copying all agents, audit the repository structure and install only categories relevant to your current stack. This reduces Claude Code's agent discovery overhead and prevents irrelevant contextual suggestions.

Custom Agent Development: Use the provided templates as starting points for organization-specific expertise—internal design systems, proprietary SDKs, or compliance requirements not covered by existing agents. The [INTERNAL_LINK: agent development guide] in docs/agent-development-guide.md documents patterns for effective consultant agents.

PROACTIVELY Keyword Strategy: Reserve PROACTIVELY for agents where automatic invocation genuinely improves workflow—language experts when editing .py files, framework specialists when modifying component structures. Overuse creates notification fatigue and degrades the experience.

Agent Composition: Complex architectural decisions often span categories. The README notes that agents "will be suggested based on the files you're working with," implying Claude Code can surface multiple relevant consultants. Explicitly invoke complementary agents (@microservices-architect then @kubernetes-expert) for cross-domain decisions.

Version Management: The repository receives updates (last commit 2025-09-19). Track upstream changes for agents in active use, particularly rapidly evolving domains like LLM Engineering where best practices shift quarterly.

Comparison with Alternatives

The key differentiator is architectural consultation versus code generation. Teams choosing supatest-ai/awesome-claude-code-sub-agents specifically want structured decision support before implementation, not faster typing. This is most valuable for senior engineers making technology choices and mid-level developers building experience in unfamiliar domains.

FAQ

What license covers these agents? MIT License. Free for commercial and personal use with attribution.

Do I need a paid Claude Code subscription? The README doesn't specify pricing. Claude Code itself requires Anthropic API access; verify current pricing on Anthropic's site.

Can I use these with Claude Desktop or API directly? No—these are Claude Code subagents, requiring the CLI tool. The YAML format and ~/.config/claude-code/agents/ path are specific to this tool.

How current are the technology recommendations? Last repository commit was 2025-09-19. Individual agent freshness depends on community contributions. Critical decisions should be cross-referenced with current documentation.

What's the difference between basic and advanced templates? The README lists both but doesn't detail differences. Inspect templates/basic-agent-template.md and templates/advanced-agent-template.md after installation.

Can I contribute new agents? Yes—see CONTRIBUTING.md for guidelines. The repository welcomes additions across all categories.

Why "sub-agents" in the repository name but "agents" in the README? The repository is awesome-claude-code-sub-agents while README references awesome-claude-code-agents in clone URLs. This inconsistency exists in the source documentation.

Conclusion

supatest-ai/awesome-claude-code-sub-agents fills a specific, valuable niche: structured architectural consultation within the developer workflow. For teams already using Claude Code, these 30+ specialized agents provide domain expertise at decision points where mistakes are expensive and experience is scarce.

The project is best suited for: senior engineers validating technology choices, teams entering unfamiliar domains (particularly LLM engineering), organizations with compliance requirements needing embedded expertise, and Claude Code users wanting to extend the tool beyond default capabilities.

The 165-star adoption suggests early traction among developers who've experienced the gap between "AI writes code" and "AI helps me choose correctly." The open-source MIT license and active contribution guidelines indicate sustainable community growth.

If your workflow involves Claude Code and you regularly face architectural decisions—framework selection, infrastructure patterns, compliance architecture—this repository provides immediately usable consultants. Install the relevant agents, verify with claude-code agents list, and invoke expertise where you need it.

Explore the collection: https://github.com/supatest-ai/awesome-claude-code-sub-agents