Using Markdown Files as Workflow Engine for Claude Code in Kubernetes

A developer has implemented an unconventional workflow engine using plain English markdown files that Claude Code executes within Kubernetes. Instead of traditional pipeline definition tools like Dagster, Prefect, or Argo, they use markdown files named SKILL.md that contain simple instructions.

How It Works

The system runs Claude Code as a Kubernetes CronJob. The workflow logic is defined in markdown files written in plain English, with instructions like "scan Reddit, then classify, then create a PR." This approach allows non-technical team members, such as the developer's boss, to write pipeline logic directly.

Claude Code follows these markdown instructions and coordinates workflow steps by writing artifacts to disk. The developer reports running this system for more than a month with better stability than expected, though they note the debugging experience is rough and there's no guarantee of consistent behavior.

Practical Considerations

The developer suggests this approach works best for low-stakes pipelines where the tradeoff between simplicity and reliability is acceptable. They question whether this plain language instruction method would work for more difficult tasks or if it only succeeds because their use case is non-critical.

A full tutorial with a forkable example is available at everyrow.io/blog/claude-code-workflow-engine, providing a practical implementation reference for others interested in this approach.