Agent Orchestrator
개요
에코시스템의 모든 에이전트를 조율하는 메타 스킬입니다. 스킬 자동 스캔, 능력 기반 매칭, 다중 스킬 워크플로 조정 및 레지스트리 관리를 수행합니다.
이 스킬을 사용해야 하는 경우
- 이 도메인에 대한 전문적인 도움이 필요할 때
이 스킬을 사용하지 말아야 하는 경우
- 작업이 agent orchestrator와 관련이 없는 경우
- 더 간단하고 구체적인 도구가 요청을 처리할 수 있는 경우
- 사용자가 도메인 전문 지식 없이 일반적인 도움이 필요한 경우
작동 방식
모든 스킬 에코시스템을 위한 중앙 결정 및 조정 계층으로 기능하는 메타 스킬입니다. 자동 스캔을 수행하고, 관련 에이전트를 식별하며, 복잡한 작업을 위해 여러 스킬을 조정합니다.
원칙: 수동 개입 제로
- 요청을 처리하기 전에 항상 스캔합니다.
- 새 스킬은 하위 폴더에
SKILL.md를 생성하면 자동 감지 및 포함됩니다. - 제거된 스킬은 레지스트리에서 자동 제외됩니다.
- 새 스킬 등록에 수동 명령이 필요하지 않습니다.
필수 워크플로 (모든 요청)
사용자 요청을 처리하기 전에 다음 단계를 실행하십시오. 스크립트는 자동으로 상대 경로를 사용하므로 어떤 디렉토리에서든 작동합니다.
1단계: 자동 탐색 (스캔)
python agent-orchestrator/scripts/scan_registry.py
MD5 해시 캐싱을 통해 초고속(<100ms)으로 작동합니다. 변경된 파일만 다시 처리합니다. 발견된 모든 스킬의 요약을 JSON으로 반환합니다.
2단계: 스킬 매칭
python agent-orchestrator/scripts/match_skills.py "<사용자 요청>"
관련성 순으로 정렬된 스킬을 JSON으로 반환합니다. 결과를 해석하십시오:
| 결과 | 조치 |
|---|---|
matched: 0 | 관련 스킬 없음. 스킬 없이 정상적으로 작동. |
matched: 1 | 하나의 관련 스킬. 해당 SKILL.md를 로드하고 따르기. |
matched: 2+ | 여러 스킬. 3단계 (조정) 실행. |
3단계: 조정 (matched >= 2인 경우)
python agent-orchestrator/scripts/orchestrate.py --skills skill1,skill2 --query "<요청>"
패턴, 단계 순서 및 스킬 간 데이터 흐름이 포함된 실행 계획을 반환합니다.
빠른 실행 (단축키)
간단한 쿼리의 경우 1단계와 2단계를 순차적으로 결합할 수 있습니다:
python agent-orchestrator/scripts/scan_registry.py && python agent-orchestrator/scripts/match_skills.py "<요청>"
스킬 레지스트리
레지스트리는 다음 위치에 있습니다:
agent-orchestrator/data/registry.json
검색 위치
스캐너는 SKILL.md를 다음 위치에서 찾습니다:
.claude/skills/*/(Claude Code에 등록된 스킬)*/(최상위 수준의 독립형 스킬)*/*(하위 폴더의 스킬, 최대 깊이 3)
스킬별 메타데이터
레지스트리의 각 항목에는 다음이 포함됩니다:
| 필드 | 설명 |
|---|---|
| name | 스킬 이름 (YAML frontmatter에서) |
| description | 전체 설명 (트리거 포함) |
| location | 디렉토리의 절대 경로 |
| skill_md | SKILL.md의 절대 경로 |
| registered | .claude/skills/에 있는지 여부 (true/false) |
| capabilities | 능력 태그 (자동 추출 + 명시적) |
| triggers | 설명에서 추출된 활성화 키워드 |
| language | 주 언어 (python/nodejs/bash/none) |
| status | active / incomplete / missing |
레지스트리 명령어
## 빠른 스캔 (해시 캐시 사용)
python agent-orchestrator/scripts/scan_registry.py
## 상세 상태 표
python agent-orchestrator/scripts/scan_registry.py --status
## 전체 재스캔 (캐시 무시)
python agent-orchestrator/scripts/scan_registry.py --force
매칭 알고리즘
각 요청에 대해 매처는 다음 기준을 사용하여 스킬에 점수를 부여합니다:
| 기준 | 점수 | 예시 |
|---|---|---|
| 쿼리에 스킬 이름 포함 | +15 | "use web-scraper" -> web-scraper |
| 정확한 키워드 트리거 일치 | +10 | "scrape" -> web-scraper |
| 능력 범주 일치 | +5 | data-extraction -> web-scraper |
| 단어 중복 | +1 | 설명에 포함된 쿼리 단어 |
| 프로젝트 부스트 | +20 | 활성 프로젝트에 할당된 스킬 |
최소 임계값: 5점. 이 미만의 스킬은 무시됩니다.
프로젝트 매칭
python agent-orchestrator/scripts/match_skills.py --project my-project "query here"
프로젝트에 할당된 스킬은 자동으로 +20 부스트를 받습니다.
조정 패턴
여러 스킬이 관련된 경우 오케스트레이터는 패턴을 분류합니다:
1. 순차적 파이프라인
스킬이 체인을 형성하여 한 스킬의 출력이 다음 스킬의 입력이 됩니다.
적용 시기: "생산자" 스킬(data-extraction, government-data)과 "소비자" 스킬(messaging, social-media)이 혼합된 경우.
예시: web-scraper가 가격 수집 -> whatsapp-cloud-api가 알림 전송
user_query -> web-scraper -> whatsapp-cloud-api -> result
2. 병렬 실행
스킬이 요청의 서로 다른 측면을 독립적으로 처리합니다.
적용 시기: 모든 스킬의 역할이 동일한 경우 (모두 생산자 또는 모두 소비자).
예시: Instagram 게시 + WhatsApp 알림 전송 (둘 다 동일한 콘텐츠 수신)
user_query -> [instagram, whatsapp-cloud-api] -> aggregated_result
3. 주 + 보조
하나의 주요 스킬이 주도하고 다른 스킬은 지원 데이터를 제공합니다.
적용 시기: 한 스킬의 점수가 다른 스킬보다 훨씬 높은 경우 (>= 2배).
예시: whatsapp-cloud-api가 메시지 전송 (주) + web-scraper가 데이터 제공 (보조)
user_query -> whatsapp-cloud-api (primary) + web-scraper (support) -> result
자세한 내용은 References/Orchestration-Patterns.md 참조
프로젝트 관리
스킬을 프로젝트에 할당하면 관련성 부스트와 지속적인 컨텍스트를 얻을 수 있습니다.
프로젝트 파일
agent-orchestrator/data/projects.json
작업
프로젝트 생성:
projects.json에 항목 추가:
{
"name": "project-name",
"created_at": "2026-02-25T12:00:00",
"skills": ["web-scraper", "whatsapp-cloud-api"],
"description": "Project description"
}
프로젝트에 스킬 추가: 프로젝트의 skills 배열 업데이트.
프로젝트에서 스킬 제거: skills 배열에서 제거.
프로젝트 스킬 조회: projects.json을 읽고 할당된 스킬 나열.
새 스킬 추가
에코시스템에 새 스킬을 추가하려면:
skills root아래 아무 곳에나 폴더를 만듭니다.- YAML frontmatter와 함께
SKILL.md를 만듭니다:
---
name: my-new-skill
description: "Description with activation keywords..."
---
## Skill Documentation
- 완료! 자동 탐색이 다음 요청 시 자동으로 감지합니다.
선택적으로, Claude Code의 기본 탐색을 위해:
4. SKILL.md를 .claude/skills/<name>/SKILL.md로 복사합니다.
명시적 능력 태그 (선택 사항)
더 정확한 매칭을 위해 frontmatter에 추가:
capabilities: [data-extraction, web-automation]
모든 스킬 상태 확인
python agent-orchestrator/scripts/scan_registry.py --status
상태 해석
| 상태 | 의미 |
|---|---|
| active | name + description이 있는 SKILL.md가 존재함 |
| incomplete | SKILL.md는 있지만 name 또는 description이 없음 |
| missing | 디렉토리는 있지만 SKILL.md가 없음 |
현재 에코시스템 스킬
| 스킬 | 능력 | 상태 |
|---|---|---|
| web-scraper | data-extraction, web-automation | active |
| junta-leiloeiros | government-data, data-extraction | active |
| whatsapp-cloud-api | messaging, api-integration | active |
| social-media, api-integration | partial |
이 표는 scan_registry.py --status를 통해 자동으로 업데이트됩니다.
모범 사례
- 프로젝트 및 요구 사항에 대한 명확하고 구체적인 컨텍스트를 제공하세요.
- 프로덕션 코드에 적용하기 전에 모든 제안을 검토하세요.
- 포괄적인 분석을 위해 다른 보완 스킬과 결합하세요.
일반적인 실수
- 도메인 전문 지식 범위를 벗어난 작업에 이 스킬을 사용하는 경우.
- 자신의 특정 컨텍스트를 이해하지 않고 권장 사항을 적용하는 경우.
- 정확한 분석을 위해 충분한 프로젝트 컨텍스트를 제공하지 않는 경우.
관련 스킬
multi-advisor- 향상된 분석을 위한 보완 스킬.task-intelligence- 향상된 분석을 위한 보완 스킬.
한계
- 이 스킬은 위에서 설명한 범위와 작업이 명확하게 일치하는 경우에만 사용하세요.
- 출력물을 환경별 검증, 테스트 또는 전문가 검토를 대체하는 것으로 취급하지 마세요.
- 필요한 입력, 권한, 안전 경계 또는 성공 기준이 누락된 경우 멈추고 명확히 요청하세요.