steps.sh
A human-readable workflow format for complex work involving humans and agents.
It describes what happens, in what order, and what each step produces.
Install the skills
Install the steps.sh skills so your AI assistant can write, validate, and convert workflows to steps.md:
npx github:supermix-dev/steps.shThis installs two Agent Skills into your project:
- steps-sh — Write and validate
steps.mdfiles from scratch - convert-to-steps — Convert existing workflow documents (SOPs, runbooks, process docs) into
steps.mdformat
Why this works for humans
- Makes the full workflow visible at a glance
- Makes dependencies and sequencing explicit
- Shows how individual work fits into the wider workflow
- Reduces last-minute surprises caused by missing dependencies
Because the format is constrained, documents stay short, consistent, and readable. People spend less time reading, writing, and updating documentation and more time designing the workflow itself.
Why this works for agents
- Provides clear inputs, outputs, and ownership per step
- Defines execution order without requiring a full DAG
- Allows agents to operate on individual steps without controlling the entire workflow
What problem this avoids
Workflows break down during execution due to unclear dependencies, implicit sequencing, missing handoffs, and late-discovered inputs.
steps.sh surfaces these issues while the workflow is being written — when they are cheaper and easier to fix.
Design intent
- Document how work happens, not how to perform individual tasks
- Make dependencies, sequencing, and handoffs explicit by default
- Serve as a shared execution plan for humans and agents
- Support parallel work and coordination without DAG complexity
- Surface ambiguity and missing dependencies at design time
- Allow workflows to evolve incrementally toward automation
Get started
Specification
The complete format specification for steps.md files.
Examples
Browse workflow examples using the steps.sh format.
Lint
Validate your steps.md files against the spec.
Visualize
Generate interactive flow diagrams from your workflows.
Mermaid
Export workflows as Mermaid flowcharts for docs and wikis.
GitHub
View the source, report issues, and contribute.