Multi-Agent Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
Multi-Agent Orchestration is a core architectural feature of SkillKit that enables the coordination of multiple AI coding agents to work as a unified team. It allows developers to define complex workflows where different agents, such as Claude Code, Cursor, or GitHub Copilot, take on specialized roles—like leader or teammate—to complete structured development tasks.
This system leverages the project's cross-agent capabilities to assign tasks based on specific agent strengths or project requirements. By using structured handoff protocols and shared skill sets, the orchestration layer ensures that context is preserved as work moves between different AI entities.
Sources: packages/core/README.md:95-108, README.md:88-89, packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md:14-16
Architecture and Core Components
The orchestration system is built around three primary entities: the TeamOrchestrator, the TeamManager, and the TaskManager. These components manage the lifecycle of agent teams and the distribution of work through a structured task system.
Team Structure
A team consists of a defined leader and multiple teammates. The leader typically handles high-level coordination, while teammates are assigned specific responsibilities based on their capabilities (e.g., frontend development using React, or backend API construction).
The relationship between management components and the creation of coordinated agent units.
Sources: packages/core/README.md:95-121, packages/core/src/orchestrator/team.ts
Component Responsibilities
| Component | Description | Key Capabilities |
|---|---|---|
| TeamOrchestrator | High-level entry point for team creation. | Creating teams with leaders and specialized teammates. |
| TeamManager | Handles team identity and resource sharing. | Initializing teams, creating skill bundles, and remote sync. |
| TaskManager | Manages the unit of work (Task). | Task creation, assignment, and status tracking. |
| Agent CLI Config | Defines execution parameters for individual agents. | Command mapping, prompt arguments, and non-interactive flags. |
Sources: packages/core/README.md:95-121, packages/core/src/executor/agents.ts:14-27
Task Lifecycle and Assignment
Tasks are the primary unit of execution within the orchestration system. They include a title, description, and a technical specification. The TaskManager facilitates the assignment of these tasks to specific agent IDs within the team.
Task Assignment Flow
The flow begins with task definition and moves through assignment to an agent that possesses the required capabilities.
Logical flow of task creation and assignment within the Team Orchestrator.
Sources: packages/core/README.md:112-121, packages/core/src/orchestrator/task.ts
Handoff Protocols
Effective orchestration relies on the Handoff Protocols methodology to transfer context between agents. This prevents information loss when a leader passes a design to a teammate for implementation, or when switching between different IDE-based and CLI-based agents.
Essential Handoff Data
To ensure a recipient agent can continue work immediately, the handoff includes:
- Current Status: Progress percentage and active blockers.
- Context: Rationale for key decisions made during the previous phase.
- Technical Details: Architecture diagrams, key file paths, and dependencies.
- Next Steps: Immediate actions required to advance the task.
Sources: packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md:46-95
Execution Strategies
Agents within an orchestrated team are executed using different strategies depending on their environment (CLI vs. IDE).
| Strategy | Description | Supported Agents (Examples) |
|---|---|---|
| CLI | Real execution via terminal spawning. | Claude Code, Codex, Gemini CLI, Goose. |
| IDE | Manual referencing within an IDE environment. | Cursor, Windsurf, GitHub Copilot. |
| Manual | Fallback for agents without direct integration. | Universal Agent. |
Sequence of events during the execution of an assigned task using a CLI-based agent.
Sources: packages/core/src/executor/agents.ts:142-159, packages/core/src/executor/agents.ts:178-185, packages/core/README.md:108-115
Orchestration Implementation
The orchestration system uses the programmatic API to initialize team structures and manage shared resources like skill bundles.
// Example: Creating a team structure
const orchestrator = new TeamOrchestrator();
const team = await orchestrator.createTeam({
name: 'feature-dev',
leader: { id: 'architect', name: 'System Architect' },
teammates: [
{ id: 'frontend', name: 'Frontend Dev', capabilities: ['react'] },
{ id: 'backend', name: 'Backend Dev', capabilities: ['api'] },
],
});
// Assigning a task to a specialized teammate
const taskManager = new TaskManager();
const task = taskManager.createTask('Build login', 'Create login endpoint', spec);
await taskManager.assignTask(task.id, 'backend');
Sources: packages/core/README.md:95-121, packages/core/src/orchestrator/index.ts
The Multi-Agent Orchestration system enables a collaborative AI environment where specialized agents work together under a unified management layer. By combining structured task management with standardized handoff protocols, SkillKit allows for complex, multi-step development workflows that exceed the capabilities of a single AI agent.