Tutorials & How-Tos
Writing Your First Custom ClawFlow
Step-by-step guide to authoring your first ClawFlows workflow. Structure, steps, state, error handling, and how to test it locally.
Step-by-step guide to authoring your first ClawFlows workflow. Structure, steps, state, error handling, and how to test it locally.
ClawFlows ships with 113 workflows, which sounds like a lot. And it is, for most people. But eventually you'll hit a routine that isn't covered — something idiosyncratic to your work, your home, or your hobbies — and you'll want to automate it. Writing your own workflow is the next step.
This tutorial walks through authoring your first custom workflow from scratch. The goal isn't to produce a production-ready masterpiece — it's to get you comfortable with the structure so the 114th workflow stops feeling intimidating.
You need:
The task is the important part. Don't pick something aspirational. Pick something you actually do, that actually annoys you, that involves 3-5 steps you could describe to a friend.
Good first-workflow candidates:
Bad first-workflow candidates:
Every ClawFlows workflow has roughly this structure:
You don't need all five on day one. A minimal workflow has metadata and steps. You can add the rest as your needs grow.
Before writing, read. Open the nikilster/clawflows repo and pick a simple workflow from a category you use. check-dependencies is a good one. morning-briefing is more complex but illustrates state passing.
Read the whole definition. You don't need to understand every detail, but you should see how steps are listed, how inputs are named, how state flows.
Create a new file in your workflows directory. Name it descriptively — my-morning-pull.workflow or whatever matches the task.
Copy the contents of a workflow that's structurally similar to what you want. Change the name and description in the metadata. Delete the steps you don't need. You're starting from a working template rather than a blank page, which is much less intimidating.
What does your workflow need from the user at invocation time? Common inputs:
For many workflows, no inputs are needed — the workflow runs with defaults and pulls everything it needs from the environment. That's fine. Start simple.
This is where you describe what the workflow does. Each step is typically a skill invocation with arguments.
For a "morning pull" workflow, the steps might be:
git-fetch on repo Agit-fetch on repo Bgit-fetch on repo Coutput-to-terminal with a summaryThat's a complete workflow. It's not fancy, but it's real, and it saves you from typing cd && git fetch three times every morning.
If a step is doing more than one thing, split it into multiple steps. This makes the workflow easier to debug and easier to modify later.
Never. Keep steps atomic. If you want composite behavior, write a skill that encapsulates it, and call the skill from a single step.
If any step produces output that a later step needs, you'll use the shared state object. The pattern is:
state.somethingstate.something as an argumentWe cover the state model in How Workflows Orchestrate Multiple Skills. For simple workflows, you might not need state at all.
For a first workflow, default error handling is fine — the workflow aborts on any failure. This is safe because it's obvious what happened.
Once you're comfortable, you can add per-step error policies:
continue-on-error for non-critical stepsretry for network-dependent stepsfallback for steps with alternative pathsDon't worry about this on day one.
Run the workflow manually. Watch what it does. Check the output. If anything's wrong, edit the definition and re-run.
ClawFlows supports a verbose mode that prints the state at each step. Use it while developing to see exactly what's happening.
Common first-workflow mistakes:
openclaw workflows sync)These are all quick to fix once you see the error.
Add a clear description to the metadata. Write one or two sentences about what the workflow does and when to run it. Future-you will thank present-you.
If you're publishing the workflow to a shared repo or the /workflows channel, add more detail — category, dependencies, installation notes, examples.
If your workflow should run automatically, wire it up to your scheduler of choice — cron, launchd, Windows Task Scheduler, or a workflow-native scheduling skill.
Many workflows are run manually by design (focus-mode, sleep-mode). Only schedule the ones that should run without your intervention.
The ClawFlows community welcomes contributions. If your workflow is general enough that others might use it, open a PR to nikilster/clawflows or submit it to the AI Skill Market workflows channel at aiskill.market/workflows.
Useful workflows that others might want:
ClawFlows workflows are typically YAML-like structured files. The exact syntax is documented in the repo README. It's designed to be human-readable even by non-programmers.
No — for workflows. Yes — if you need a new skill that doesn't exist yet. Most first workflows use existing skills and don't require any new code.
Verbose mode prints state at each step. You can also add explicit log steps wherever you want visibility. The runtime produces clear error messages for most failure modes.
Yes. Composition is supported and encouraged for complex routines. Keep each workflow small and compose them.
ClawFlows workflows run as processes, so a broken workflow just fails — it doesn't corrupt state or cascade into other workflows. Fix the definition and re-run.
Writing your own workflow is the point at which ClawFlows stops being a collection you installed and starts being a framework you use. Pick one 5-minute task this weekend, write a workflow for it, and run it tomorrow morning. That's how the automation habit starts.
Explore all 113 workflows at aiskill.market/workflows or submit your own.
Research a company before a job interview. Pull recent news, company info, interviewer profiles, and common questions for the role. Delivers a complete prep packet.
Research and plan a trip with flights, hotels, activities, and a day-by-day itinerary
Get ready for any upcoming event — what to wear, bring, know, and expect
Weekly date night ideas based on your budget, mood, and what's nearby