team-builder

팀 빌더

필요할 때 에이전트 팀을 찾아보고 조합할 수 있는 대화형 메뉴입니다. 평면 구조와 도메인 하위 디렉터리 구조를 모두 지원합니다.

사용 시점

• 여러 에이전트 페르소나(markdown 파일)가 있고 작업에 사용할 에이전트를 골라야 할 때
• 서로 다른 도메인에서 임시 팀을 조합하고 싶을 때(예: 보안 + SEO + 아키텍처)
• 어떤 에이전트가 있는지 먼저 둘러본 뒤 결정하고 싶을 때

사전 조건

에이전트 파일은 페르소나 프롬프트(정체성, 규칙, 워크플로, 산출물)를 담은 markdown 파일이어야 합니다. 첫 번째 # Heading은 에이전트 이름으로, 첫 번째 문단은 설명으로 사용합니다.

평면 구조와 하위 디렉터리 구조를 모두 지원합니다.

하위 디렉터리 구조: 폴더 이름에서 도메인을 추론합니다.

agents/
├── engineering/
│   ├── security-engineer.md
│   └── software-architect.md
├── marketing/
│   └── seo-specialist.md
└── sales/
    └── discovery-coach.md

평면 구조: 공통 파일명 접두사에서 도메인을 추론합니다. 두 개 이상 파일이 같은 접두사를 공유할 때만 도메인으로 인정합니다. 접두사가 고유한 파일은 "General"로 분류합니다. 알고리즘은 첫 번째 - 기준으로 나누므로, product-management 같은 다단어 도메인은 하위 디렉터리 구조를 쓰는 것이 좋습니다.

agents/
├── engineering-security-engineer.md
├── engineering-software-architect.md
├── marketing-seo-specialist.md
├── marketing-content-strategist.md
├── sales-discovery-coach.md
└── sales-outbound-strategist.md

설정

에이전트는 두 가지 방식으로 탐색하며, 결과는 에이전트 이름 기준으로 병합 및 중복 제거합니다.

1. claude agents 명령(기본) — claude agents를 실행해 CLI가 알고 있는 모든 에이전트 목록을 가져옵니다. 여기에는 사용자 에이전트, 플러그인 에이전트(예: everything-claude-code:architect), 내장 에이전트가 포함됩니다. 경로 설정 없이도 ECC 마켓플레이스 설치본을 자동 포함합니다.
2. 파일 글롭(대체, 에이전트 내용 읽기용) — 에이전트 markdown 파일은 다음 경로에서 읽습니다.
   • ./agents/**/*.md + ./agents/*.md — 프로젝트 로컬 에이전트
   • ~/.claude/agents/**/*.md + ~/.claude/agents/*.md — 전역 사용자 에이전트

이름이 충돌하면 앞선 소스가 우선합니다. 우선순위는 사용자 에이전트 > 플러그인 에이전트 > 내장 에이전트입니다. 사용자가 지정하면 사용자 정의 경로도 사용할 수 있습니다.

동작 방식

1단계: 사용 가능한 에이전트 탐색

claude agents를 실행해 전체 에이전트 목록을 가져오고 각 줄을 파싱합니다.

• 플러그인 에이전트는 plugin-name: 접두사를 가집니다. 예: everything-claude-code:security-reviewer. : 뒤를 에이전트 이름으로, 플러그인 이름을 도메인으로 사용합니다.
• 사용자 에이전트는 접두사가 없습니다. ~/.claude/agents/ 또는 ./agents/의 해당 markdown 파일을 읽어 이름과 설명을 추출합니다.
• 내장 에이전트(예: Explore, Plan)는 사용자가 명시적으로 포함하라고 하지 않으면 건너뜁니다.

markdown 파일에서 읽은 사용자 에이전트는 다음 규칙을 따릅니다.

• 하위 디렉터리 구조: 부모 폴더 이름에서 도메인을 추출합니다.
• 평면 구조: 첫 번째 - 앞의 텍스트를 파일명 접두사로 모읍니다. 같은 접두사가 2개 이상 있을 때만 도메인으로 인정합니다. 예를 들어 engineering-security-engineer.md, engineering-software-architect.md는 모두 engineering으로 시작하므로 Engineering 도메인으로 묶습니다. 접두사가 고유한 파일(예: code-reviewer.md, tdd-guide.md)은 "General"에 넣습니다.
• 첫 번째 # Heading에서 에이전트 이름을 추출합니다. 헤딩이 없으면 파일명에서 .md를 제거하고 하이픈을 공백으로 바꾼 뒤 제목형으로 변환합니다.
• 헤딩 다음 첫 번째 문단에서 한 줄 요약을 추출합니다.

claude agents 실행과 파일 경로 탐색 후에도 에이전트를 찾지 못하면, "No agents found. Run \claude agents` to verify your setup."`라고 안내하고 중단합니다.

2단계: 도메인 메뉴 표시

Available agent domains:
1. Engineering — Software Architect, Security Engineer
2. Marketing — SEO Specialist
3. Sales — Discovery Coach, Outbound Strategist

Pick domains or name specific agents (e.g., "1,3" or "security + seo"):

• 에이전트가 없는 도메인(빈 디렉터리)은 건너뜁니다.
• 도메인별 에이전트 수를 표시합니다.

3단계: 선택 처리

유연한 입력을 허용합니다.

• 숫자: "1,3"은 Engineering과 Sales의 모든 에이전트를 선택
• 이름: "security + seo"는 탐색된 에이전트에 퍼지 매칭
• "all from engineering"은 해당 도메인의 모든 에이전트를 선택

5개를 초과해 선택되면 이름순으로 나열한 뒤 범위를 줄이도록 안내합니다. 예: "You selected N agents (max 5). Pick which to keep, or say 'first 5' to use the first five alphabetically."

선택을 확인합니다.

Selected: Security Engineer + SEO Specialist
What should they work on? (describe the task):

4단계: 에이전트를 병렬 실행

1. Read each selected agent's markdown file
2. Prompt for the task description if not already provided
3. Spawn all agents in parallel using the Agent tool:
   • subagent_type: "general-purpose"
   • prompt: "{agent file content}\n\nTask: {task description}"
   • Each agent runs independently — no inter-agent communication needed
4. If an agent fails (error, timeout, or empty output), note the failure inline (e.g., "Security Engineer: failed — [reason]") and continue with results from agents that succeeded

5단계: 결과 종합

모든 출력을 수집해 통합 보고서로 제시합니다.

• 에이전트별 결과 묶음
• 종합 섹션에는 다음을 포함합니다.
  • 에이전트 간 공통 합의
  • 권고안 사이의 충돌이나 긴장 관계
  • 권장 다음 단계

에이전트가 1개만 선택됐다면 종합 섹션을 생략하고 결과를 바로 제시합니다.

규칙

• 동적 탐색만 사용. 에이전트 목록을 하드코딩하지 않습니다. 디렉터리에 새 파일이 생기면 메뉴에 자동 반영됩니다.
• 팀당 최대 5개 에이전트. 5개를 넘기면 효율은 떨어지고 토큰 사용량만 늘어납니다. 선택 단계에서 강제합니다.
• 병렬 실행. 모든 에이전트는 동시에 실행합니다. Agent 도구의 병렬 호출 패턴을 사용합니다.
• 병렬 Agent 호출을 사용하고 TeamCreate는 쓰지 않음. 이 스킬은 독립적인 작업을 위해 병렬 Agent 호출을 사용합니다. 에이전트끼리 토론하거나 서로 응답해야 할 때만 TeamCreate가 필요합니다.

예시

User: team builder

Claude:
Available agent domains:
1. Engineering (2) — Software Architect, Security Engineer
2. Marketing (1) — SEO Specialist
3. Sales (4) — Discovery Coach, Outbound Strategist, Proposal Strategist, Sales Engineer
4. Support (1) — Executive Summary

Pick domains or name specific agents:

User: security + seo

Claude:
Selected: Security Engineer + SEO Specialist
What should they work on?

User: Review my Next.js e-commerce site before launch

[두 에이전트가 병렬로 실행되고, 각자 전문 분야를 코드베이스에 적용]

Claude:
## Security Engineer Findings
- [findings...]

## SEO Specialist Findings
- [findings...]

## Synthesis
Both agents agree on: [...]
Tension: Security recommends CSP that blocks inline styles, SEO needs inline schema markup. Resolution: [...]
Next steps: [...]