A CLI tool that lets developers define agent skills (using the Agent Skills SKILL.md format) and compose them into supervised workflows with enforced output contracts, approval gates, and outcome-based tracking (e.g., PR merged, tests generated)

Quick Start • Features • Examples • Contributing

What is this?

SkillFlow Orchestrator CLI is a lightweight offline tool that lets AI engineers define reusable agent skills, stitch them into auditable workflows, and execute those workflows with enforced contracts and approval gates. It stores skills, workflows, and execution logs in a single SQLite file, making it ideal for solo developers who need predictable, traceable results without external services.

Example usage:

$ skillflow register example.skill.md
Registered skill 'lint-code' with ID 1

Problem

Solo developers lack a lightweight way to enforce reliability and auditability in agent workflows, leading to inconsistent outputs and difficulty tying agent actions to billable outcomes.

Features

Feature	Description
Skill Registration	Parse Agent Skills SKILL.md files, validate required frontmatter, and persist skills as JSON blobs in SQLite with auto‑generated IDs.
Workflow Composition	Define workflows in YAML/JSON that reference registered skills, map inputs, set approval gates, and store the workflow definition for later execution.
Contract Validation	Verify that each step’s declared output contract matches the expected outcome (string equality for MVP) before execution.
Approval Gates	Pause workflow execution for user confirmation; abort the workflow if approval is denied and log the outcome.
Outcome Tracking	Record every step’s status, approval flag, and notes in an executions table; generate a JSON execution report after each run.
Offline Storage	All data (skills, workflows, logs) resides in a single SQLite file (~/.skillflow/skillflow.sqlite by default), requiring no external services.
CLI‑Driven	Built with click for intuitive commands: register, compose, run, log.
Execution Reporting	On workflow completion, produce a detailed JSON file ({workflow_id}_run.json) summarizing each step’s result.

Quick Start

1. Clone the repository:

   git clone https://github.com/m2ai-portfolio/skillflow-orchestrator-cli.git
   cd skillflow-orchestrator-cli

2. Install dependencies (Python 3.11+ required):

   pip install -e .

3. Verify the CLI is available:

   skillflow --help

   Expected output shows the available sub‑commands: register, compose, run, log.

Examples

Register a new skill

skillflow register example.skill.md

Output:

Registered skill 'lint-code' with ID 1

Compose a workflow that uses the skill

skillflow compose deploy.yaml

Output:

Composed workflow 'deploy-app' with ID 1

Run the workflow with approval

skillflow run 1

Interaction:

Approve step 1? [y/N]: y
Step 1: lint-code -> success (approved)
Workflow completed: SUCCESS

A file 1_run.json appears containing:

{
  "workflow_id": 1,
  "steps": [
    {
      "step_index": 0,
      "skill_name": "lint-code",
      "status": "success",
      "approved": true,
      "notes": null
    }
  ],
  "overall_status": "SUCCESS"
}

File Structure

SkillFlow Orchestrator CLI/
  skillflow/          # Core source code
    __init__.py
    cli.py             # Click command groups (register, compose, run, log)
    models.py          # Pydantic models for Skill, Workflow, ExecutionLog
    storage.py         # SQLite wrapper: init DB, CRUD operations
    skill_parser.py    # Parses SKILL.md frontmatter and steps
    workflow_engine.py # Validation, composition, contract checking
    runner.py          # Executes workflow steps, handles approvals
    utils.py           # Helper functions
  tests/               # Test suite
    __init__.py
    test_cli.py
    test_parser.py
    test_runner.py
  assets/              # Infographic and visual assets
    infographic.png
  screenshots/         # Example terminal outputs
    01-help-output.txt
    02-register-success.txt
    ...
  pyproject.toml       # Project metadata and dependencies
  requirements.txt     # Pip requirements (click, pyyaml, pydantic)
  README.md

Tech Stack

Technology	Purpose
Python 3.11+	Core language
click	CLI framework
pyyaml	YAML workflow definition parsing
pydantic	Data validation and settings management
sqlite3 (stdlib)	Embedded single‑file data store

Contributing

Fork the repository, make your changes, run the test suite, and submit a pull request. Please keep commits focused and include relevant tests.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio