# Create Workflow > Create Jazz workflow automation files (WORKFLOW.md). Use this for scheduling Jazz agents to run recurring tasks. For OS-level scripts/commands, use create-system-routine. Use when this capability is needed. - Skill: `tomevault-io/create-workflow` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/create-workflow` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/create-workflow/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/create-workflow --- # Create Workflow Generate workflow automation files that schedule jazz agents to run recurring tasks. ## When to Use - User wants to automate a recurring task using a Jazz Agent - User asks to "create a workflow" or "schedule an agent" - User says "I want to check X every Y" (e.g., "check emails every hour") - User wants unattended agent execution **Note:** If the user wants to schedule a simple shell script or system command *without* using a Jazz Agent, use the `create-system-routine` skill instead. ## Gathering Information (Questionnaire) **Do not create the workflow file until you have enough information.** If the user's prompt is vague (e.g. "create a workflow", "I want to automate emails") or missing any of the items below, guide them through a short questionnaire instead of guessing. **You have enough info when you know:** 1. **Task**: What should the agent do? (Concrete, not vague.) 2. **Schedule**: When should it run? (So you can convert to cron.) 3. **Catch-up**: Should missed runs execute on startup? (If not specified, ask or choose a sensible default.) 4. **Auto-approve**: What risk level? (read-only / low-risk / high-risk / false—default to conservative.) 5. **Skills**: Which skills does the agent need? (e.g. email, calendar, deep-research.) 6. **Instructions**: Clear, safety-first prompt with explicit criteria and "when in doubt" rules. 7. **Location**: Where to save? (Local `./workflows//` or global `~/.jazz/workflows//`.) **How to run the questionnaire:** - Ask **one or a few questions at a time**; don't dump a long list. - Use the user's words to refine (e.g. "You said 'clean my inbox'—should that be archive only, or also delete? How old is 'old'?"). - After each answer, confirm what you have and ask only what's still missing. - Once you have all seven items above, proceed to create the WORKFLOW.md. ## Workflow 1. **Understand the task**: What should the agent do? When should it run? If unclear, ask. 2. **Determine schedule**: Convert user intent to cron format; if not stated, ask when they want it to run. 3. **Decide catch-up behavior**: Should missed runs execute on startup? Ask if not specified. 4. **Choose auto-approve policy**: Based on risk level of operations; default to conservative. 5. **Identify required skills**: What skills will the agent need? 6. **Write clear instructions**: Safety-first prompt with explicit guidelines. 7. **Create WORKFLOW.md**: Place in appropriate directory only after you have enough info from above. ## Workflow File Structure ```markdown --- name: workflow-name description: Brief one-line summary schedule: "0 8 * * *" autoApprove: read-only catchUpOnStartup: true maxCatchUpAge: 43200 agent: default skills: - skill-name --- # Workflow Title [Clear instructions for the agent, including safety guidelines] ``` ## Frontmatter Fields | Field | Required | Description | Example | | ------------------ | -------- | ----------------------------------------------- | ----------------------------------------------------- | | `name` | ✓ | Kebab-case identifier | `email-cleanup` | | `description` | ✓ | One-line summary | `Clean up old newsletters` | | `schedule` | | Cron expression | `0 * * * *` (hourly) | | `agent` | | Agent to use (optional, will prompt if omitted) | `research-agent` | | `autoApprove` | | Auto-approval policy | `read-only`, `low-risk`, `high-risk`, `true`, `false` | | `skills` | | Skills to load | `["email", "calendar"]` | | `catchUpOnStartup` | | Run missed workflows on startup | `true` | | `maxCatchUpAge` | | Max age (seconds) for catch-up runs | `43200` (12 hours) | ## Cron Schedule Guide Ask user when they want it to run, then convert to cron: | User Intent | Cron Expression | Description | | -------------------- | --------------- | ------------------------- | | Every hour | `0 * * * *` | At minute 0 of every hour | | Every morning at 8am | `0 8 * * *` | Daily at 8:00 AM | | Every 15 minutes | `*/15 * * * *` | Every 15 minutes | | Weekdays at 9am | `0 9 * * 1-5` | Mon-Fri at 9:00 AM | | Every Monday at 9am | `0 9 * * 1` | Weekly on Monday | | First of month | `0 0 1 * *` | Monthly at midnight | Cron format: `minute hour day-of-month month day-of-week` ## Auto-Approve Policy Choose based on what tools the workflow will use: | Policy | When to Use | Example Workflows | | ----------- | ------------------------------------- | ------------------------------------------------ | | `read-only` | Only reads/searches, no modifications | Weather check, news digest, monitoring | | `low-risk` | Modifies data but reversible | Email archiving, labeling, calendar events | | `high-risk` | Deletes, sends, executes commands | Email cleanup with deletion, automated responses | | `false` | Always ask for approval | Testing, development | **Default to the most restrictive policy that allows the workflow to function.** ## Safety Guidelines Always include safety rules in the workflow prompt: ```markdown **Safety Rules:** - When in doubt, DO NOTHING - Only perform actions you're 100% confident about - Leave uncertain items for manual review - [Add task-specific safety rules] ``` For workflows that modify or delete: - Emphasize conservative behavior - Specify exact criteria (e.g., "only archive newsletters older than 2 weeks") - Add "if unsure, skip it" instructions ## File Location Ask user where they want the workflow (or choose based on context): | Location | Use Case | Path | | ---------- | ----------------------------- | -------------------------------------- | | **Local** | Project-specific automation | `./workflows//WORKFLOW.md` | | **Global** | User-wide personal automation | `~/.jazz/workflows//WORKFLOW.md` | Built-in workflows are shipped with Jazz and shouldn't be modified. ## Complete Example User request: *"I want to clean up my email inbox every hour, archiving old newsletters"* **Questions to ask:** 1. ✓ What counts as "old"? (2 weeks) 2. ✓ Should it only archive or also delete? (archive only) 3. ✓ Any specific senders to target? (newsletters, promotional) 4. ✓ Where to save it? (global: `~/.jazz/workflows/`) **Generated workflow:** ```markdown --- name: email-cleanup description: Archive old newsletters and promotional emails schedule: "0 * * * *" autoApprove: low-risk skills: - email --- # Email Cleanup Review my inbox from the last hour and archive emails matching these criteria: **Criteria for archiving:** - Newsletters older than 2 weeks - Promotional emails older than 3 days - GitHub notifications already read **Safety Rules:** - When in doubt, DO NOTHING - Only archive emails you're 100% confident match the criteria - If an email might be important, leave it in inbox - Never delete, only archive **Output:** Log count of archived emails to console. ``` ## Skills Integration If the workflow needs specific capabilities, suggest relevant skills: | Task Type | Skills to Include | | ------------------- | ----------------------------- | | Email management | `email` | | Calendar tasks | `calendar` | | Research/analysis | `deep-research` | | Code/git operations | (none needed, built-in tools) | | Web searches | (none needed, built-in) | Include skills in frontmatter: ```yaml skills: - email - calendar ``` And reference in prompt: ```markdown Use the `email` skill to access my inbox efficiently. ``` ## After Creation Tell the user what to do next: ```bash # Test the workflow manually first jazz workflow run # Once confident, schedule it jazz workflow schedule # Monitor logs tail -f ~/.jazz/logs/.log # View run history jazz workflow history ``` ## Common Workflow Patterns ### Daily Research Digest ```markdown --- name: tech-digest description: Daily AI and tech news digest schedule: "0 8 * * *" autoApprove: true skills: - deep-research --- # Daily Tech Digest Research the most important AI and tech news from the last 24 hours. **Sources:** Twitter, Reddit, Hacker News, Hugging Face, TechCrunch **Output:** Save summary to `~/digests/YYYY/Month/DD.md` **Format:** Brief bullet points with source links ``` ### Morning Briefing ```markdown --- name: morning-briefing description: Weather, calendar, and news brief schedule: "0 7 * * 1-5" autoApprove: read-only --- # Morning Briefing Provide a concise morning brief: 1. Today's weather and outfit suggestion 2. Calendar events for today 3. Top 3 news headlines Keep it under 100 words - this is a quick glance. ``` ### GitHub Issue Triage ```markdown --- name: github-triage description: Label and prioritize new GitHub issues schedule: "0 9 * * 1-5" autoApprove: low-risk --- # GitHub Issue Triage Review new GitHub issues from the last 24 hours: 1. Add appropriate labels (bug, feature, documentation) 2. Set priority (P0-P3) based on severity 3. Add to project board if critical **Safety:** Only add labels and project assignments. Never close issues. ``` ### Weekly Standup Report ```markdown --- name: weekly-standup description: Generate weekly progress report schedule: "0 17 * * 5" autoApprove: read-only --- # Weekly Standup Report Generate a weekly summary: 1. Completed tasks (from GitHub, calendar, notes) 2. In-progress work 3. Blockers or challenges 4. Next week's priorities **Output:** Save to `~/standups/YYYY-WW.md` ``` ## Validation Checklist Before creating the file, verify: - ✓ Name is kebab-case, descriptive - ✓ Description is one clear sentence - ✓ Schedule is valid cron (5 fields) - ✓ Auto-approve matches task risk level - ✓ Safety rules are explicit and conservative - ✓ Skills are listed if needed - ✓ Output location is specified if workflow saves files - ✓ Instructions are clear enough for an AI agent ## Anti-Patterns - ❌ Vague instructions: "clean my inbox" → specify exactly what to clean - ❌ Overly aggressive auto-approve: Don't use `high-risk` unless necessary - ❌ Missing safety rules: Always include "when in doubt" guidelines - ❌ No schedule: If automating, include a schedule (or explain it's manual-only) - ❌ Wrong location: Project-specific workflows shouldn't be global - ❌ Too complex: Break into multiple simple workflows instead ## Testing Guidance Always recommend testing before scheduling: 1. **Manual run first**: `jazz workflow run ` to verify logic 2. **Check with `--auto-approve`**: Test the auto-approval behavior 3. **Monitor initial runs**: Watch logs for first few scheduled executions 4. **Iterate**: Adjust safety rules and criteria based on actual behavior ## Documentation After creating the workflow, optionally create a README in the workflow directory explaining: - What it does - When it runs - What to expect - How to customize Example: `workflows/email-cleanup/README.md` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lvndry) — claim your Tome and manage your conversions.