moai-cc-agents
Creating and Managing Sub-agents in Claude Code. Design agent personas, define proactive triggers, set tool permissions, structure agent files. Use when building specialized agents for code review, debugging, architecture, or domain-specific tasks.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for creating and managing specialized sub-agents within Claude Code. It enables developers to design custom agent personas, define proactive triggers for automated workflows, and implement strict tool permission patterns to ensure secure and efficient task delegation across complex software engineering projects.
Use Cases
- Automated Code Quality Audits: Designing a 'Code Reviewer' sub-agent that triggers automatically during PR analysis to check for SOLID principles and security vulnerabilities.
- Parallel Debugging and Diagnosis: Deploying a specialized 'Debugger' agent in an isolated context to analyze stack traces and test failures without interrupting the main development flow.
- Architectural Governance: Implementing an 'Architect' agent to validate system design changes and refactoring proposals against project-specific scalability and maintainability standards.
- Secure Tool Management: Applying the Principle of Least Privilege by creating sub-agents with restricted Bash command access (e.g., limiting tools to specific git or npm patterns) to minimize execution risk.
| name | moai-cc-agents |
|---|---|
| description | "Creating and Managing Sub-agents in Claude Code. Design agent personas, define proactive triggers, set tool permissions, structure agent files. Use when building specialized agents for code review, debugging, architecture, or domain-specific tasks." |
| allowed-tools | "Read, Write, Edit, Glob, Bash" |
Skill Metadata
| Field | Value |
|---|---|
| Version | 1.0.0 |
| Tier | Ops |
| Auto-load | When creating or managing sub-agents |
What It Does
Sub-agent 생성 및 관리를 위한 전체 가이드를 제공합니다. Agent persona 설계, proactive trigger 정의, tool 권한 설정, agent 파일 구조화 방법을 다룹니다.
When to Use
- Sub-agent를 새로 생성할 때
- 기존 agent의 권한이나 trigger 조건을 수정할 때
- Agent 간 협업 패턴을 설계할 때
- Tool access 최소화 원칙을 적용할 때
Creating and Managing Sub-agents
Sub-agents are specialized Claude instances with independent context, custom prompts, and restricted tool access. They handle deep analysis, parallel work, and autonomous tasks.
Agent File Structure
Location: .claude/agents/
---
name: agent-name
description: Use PROACTIVELY for [specific trigger conditions]
tools: Read, Write, Edit, Glob, Grep, Bash(git:*)
model: sonnet
---
# Agent Name — Specialist Role
Brief description of agent expertise.
## Core Mission
- Primary responsibility
- Scope boundaries
- Success criteria
## Proactive Triggers
- When to activate automatically
- Specific conditions for invocation
- Integration with workflow
## Workflow Steps
1. Input validation
2. Task execution
3. Output verification
4. Handoff to next agent (if applicable)
## Constraints
- What NOT to do
- Delegation rules
- Quality gates
Agent Persona Design Pattern
---
name: code-reviewer
description: Use PROACTIVELY for code review requests, PR analysis, or quality checks
tools: Read, Glob, Grep, Bash(git:*)
model: sonnet
---
# Code Reviewer — Quality Expert
Specialized in identifying code quality issues, security risks, and architecture concerns.
## Core Mission
- Review code for SOLID principles
- Identify code smells and anti-patterns
- Verify security best practices
- Suggest improvements with rationale
## Proactive Triggers
- When user mentions "review", "quality", "audit"
- After significant code changes
- Before PR merge
## Workflow Steps
1. **Analyze**: Read changed files, understand context
2. **Evaluate**: Check against TRUST 5 principles
3. **Report**: List findings with severity & fix suggestions
4. **Recommend**: Suggest refactoring or architectural improvements
## Constraints
- No direct edits (only suggestions)
- Focus on maintainability, not style
- Respect existing architecture decisions
High-Freedom: Agent Principles
Autonomy & Expertise
- Each agent owns 1 specialization (not 3+)
- Define clear "when to activate" triggers
- Agents should make decisions independently
Tool Access Minimization
- Grant only necessary tools per role
- Restrict Bash to specific commands:
Bash(git:*),Bash(python:*) - Never grant
Bash(*); always specify pattern
Handoff & Collaboration
- Agent A completes → hands off to Agent B
- Use clear "next agent" instructions
- No circular dependencies
Medium-Freedom: Common Agent Patterns
Pattern 1: Debugger Agent
name: debugger
description: Use PROACTIVELY for error diagnosis, test failures, exception analysis
tools: Read, Grep, Glob, Bash(pytest:*), Bash(git:*)
model: sonnet
Mission: Diagnose errors, provide fix-forward guidance
Triggers: error, failed, exception, debug
Output: Root cause + suggested fixes
Pattern 2: Architect Agent
name: architect
description: Use PROACTIVELY for system design, refactoring, scalability concerns
tools: Read, Glob, Grep, Bash(ls:*), Bash(find:*)
model: sonnet
Mission: Design systems, propose architectures
Triggers: architecture, refactor, design, scalability
Output: Design document + implementation roadmap
Pattern 3: Security Agent
name: security-auditor
description: Use PROACTIVELY for vulnerability assessment, OWASP checks, secrets detection
tools: Read, Glob, Grep
model: sonnet
Mission: Find security issues, verify OWASP compliance
Triggers: security, audit, vulnerability, secrets
Output: Risk assessment + remediation steps
Low-Freedom: Tool Permission Patterns
Principle of Least Privilege
# ❌ Too permissive
tools: Read, Write, Edit, Bash(*)
# ✅ Appropriate
tools: Read, Glob, Grep # Read-only analysis
# ✅ Appropriate
tools: Read, Edit, Bash(black:*), Bash(pytest:*) # Formatter + tests only
Bash Command Restrictions
# Allowed patterns:
Bash(git:*) # All git commands
Bash(npm run:*) # Only npm run scripts
Bash(python:*) # Python interpreter
Bash(pytest:*) # Pytest runner
# Denied patterns:
Bash(rm:*) # Dangerous deletion
Bash(sudo:*) # Privilege escalation
Bash(curl:*) # Arbitrary downloads
Agent Execution Modes
Mode 1: Inline (main context)
/role security
"Check this project for vulnerabilities"
# Runs in main session context
Mode 2: Sub-agent (isolated context)
/role security --agent
"Perform comprehensive security audit"
# Runs in independent context, can work in parallel
Mode 3: Parallel Multi-role
/multi-role security,performance,qa --agent
"Analyze security, performance, and quality"
# All roles run in parallel, results merged
Agent Registration & Discovery
# List available agents
/agents
# Create new agent interactively
/agents create
# View specific agent
/agents view security-auditor
# Edit agent
/agents edit security-auditor
# Delete agent
/agents delete security-auditor
Agent Validation Checklist
-
nameis kebab-case (e.g.,code-reviewer) -
descriptionincludes "Use PROACTIVELY for" -
toolslist only necessary tools - No
Bash(*)wildcard; specific patterns only -
modelishaikuorsonnet -
Proactive Triggerssection clearly defined - No overlapping responsibilities with other agents
- YAML frontmatter is valid
Best Practices
✅ DO:
- Design agents around specific expertise
- Use
--agentflag for large analyses - Combine multiple agents for complex tasks
- Name agents descriptively
❌ DON'T:
- Create overpowered agents with all tools
- Allow direct file modifications without approval
- Overlap agent responsibilities
- Use
Bash(*)without specific patterns
Reference: Claude Code Sub-agents documentation Version: 1.0.0