Workflow System
Relevant source files
The following files were used as context for generating this wiki page:
The Workflow System in SkillKit is a specialized orchestration framework designed to compose and execute multiple Skills through structured sequences called "waves." It enables developers to define complex automation logic by combining individual atomic units of work into a cohesive execution plan.
The system handles the parsing of YAML-based workflow definitions, manages execution states, and provides mechanisms for both parallel and sequential task processing. It serves as the high-level coordinator within the SkillKit ecosystem, ensuring that environment variables, pre/post hooks, and conditional logic are applied correctly across a project.
Sources: packages/core/src/workflow/types.ts, packages/core/src/workflow/parser.ts
Core Architecture and Data Models
The system is built around a hierarchical data structure where a single Workflow contains multiple WorkflowWave objects, which in turn contain WorkflowSkill references.
Workflow Structure
A Workflow is the top-level entity defined in .yaml files. It includes metadata, environment configurations, and the execution waves.
| Field | Type | Description |
|---|---|---|
name | string | Unique identifier for the workflow. |
waves | WorkflowWave[] | Ordered list of execution stages. |
env | Record<string, string> | Environment variables for the execution context. |
preHooks/postHooks | string[] | Hooks to run before or after the workflow. |
Sources: packages/core/src/workflow/types.ts:35-55
Wave and Skill Orchestration
Each wave determines how its contained skills are executed. The parallel boolean flag controls whether skills within that wave run concurrently or sequentially.
The diagram shows the hierarchical relationship between a Workflow, its Waves, and the individual Skills within those waves.
Sources: packages/core/src/workflow/types.ts:20-33
Workflow Parsing and Management
The Workflow Parser is responsible for translating YAML files into the canonical Workflow object. It handles file I/O within the .skillkit/workflows directory and ensures that definitions adhere to the required schema.
Key Parser Functions
| Function | Description |
|---|---|
parseWorkflow(content) | Converts YAML string to a Workflow object; validates required fields like name and waves. |
loadWorkflowByName(path, name) | Searches the project's workflow directory for a specific file matching the name. |
validateWorkflow(workflow) | Performs a deep check to ensure waves and skills have non-empty identifiers. |
createWorkflowTemplate(name) | Generates a boilerplate workflow with "Setup" and "Main" waves. |
Sources: packages/core/src/workflow/parser.ts:15-163
Workflow File System Logic
Workflows are stored with the .yaml extension in a dedicated directory. The system uses a specific naming convention to ensure identifiers are filesystem-safe.
Sources: packages/core/src/workflow/types.ts:114-115, packages/core/src/workflow/parser.ts:112-115
Execution and State Tracking
The system tracks the lifecycle of a workflow execution through a dedicated WorkflowExecution state. This state includes real-time status updates for every wave and individual skill.
Execution Statuses
The system utilizes a specific set of statuses to track progress: pending, running, paused, completed, failed, and cancelled.
Sources: packages/core/src/workflow/types.ts:57-60
Execution State Model
The ER diagram illustrates the relationship between the overall execution state, the status of specific waves, and the results of individual skill executions.
Sources: packages/core/src/workflow/types.ts:62-112
CLI Integration
The Workflow System is exposed through the SkillKit CLI, allowing users to create and manage workflows directly from the terminal.
Workflow Commands
The WorkflowCreateCommand allows for the generation of new templates, while the RunCommand (and PlanCommand) handles the orchestration logic by utilizing an execution engine.
- Create:
$0 workflow create <name>- Generates a new template in.skillkit/workflows/. - Run:
$0 run <skill-ref>- Executes a skill, often as part of a larger plan or workflow, with optional dry-run and verification modes. - Plan:
$0 plan execute <file>- Manages structured development plans that utilize similar task-based orchestration.
Sources: packages/cli/src/commands/workflow/create.ts:11-64, packages/cli/src/commands/run.ts:25-50, packages/cli/src/commands/plan.ts:35-65
Execution Progress Monitoring
The CLI utilizes an execution engine that emits events such as task_start, task_complete, checkpoint, and verification. These are caught by a progress listener to provide real-time feedback (e.g., via spinners).
Sources: packages/cli/src/commands/run.ts:95-145
Skill Translation and Cross-Agent Support
While workflows orchestrate skills, the skills themselves are often translated for different AI agents (e.g., Claude Code, Cursor, Windsurf). The Skill Translator ensures that the content loaded by the workflow system is compatible with the target agent's specific requirements.
This sequence shows how the workflow system interacts with the translator to ensure skills are formatted correctly for the specific AI environment being used.
Sources: packages/core/src/skill-translator.ts:175-230, packages/core/src/skill-translator.ts:355-400
Summary
The Workflow System provides the structural backbone for SkillKit's automation capabilities. By defining waves of parallel or sequential skills, it enables complex multi-step processes to be executed with robust state tracking and cross-agent compatibility. It bridges the gap between atomic skill definitions and project-wide implementation goals through a structured YAML-based orchestration layer.