Windmill Development Skill

A Claude Code skill that guides you through building scripts, flows, and apps on Windmill.dev - the open-source workflow engine and developer platform.

How it works

When you're working on Windmill projects, the skill automatically activates. Instead of you hunting through documentation, Claude already knows the patterns.

Ask to create a Python script, and it knows you need a main function with type annotations. Ask to build a flow, and it generates proper OpenFlow YAML with input transforms. Need to set up a database connection? It walks you through creating typed resources.

The skill covers the full development lifecycle: writing scripts in TypeScript/Python/Go/Bash, composing them into flows, building apps with the low-code UI builder, managing resources and secrets, and syncing everything through the CLI.

It also knows both Windmill MCP servers - the official one for running scripts, and the extended rothnic/windmill-mcp for full API access. When you have MCP configured, Claude can create, update, and execute your Windmill workspace directly.

Installation

Claude Code (Copy to Project)

Copy the skill directory to your project:

mkdir -p .claude/skills
cp -r path/to/windmill-development .claude/skills/

Claude Code (Symlink for Multiple Projects)

Link from a central location:

mkdir -p .claude/skills
ln -s ~/skills/windmill-development .claude/skills/windmill-development

Verify Installation

The skill activates automatically when you mention Windmill, scripts, flows, or related topics. Test it:

You: "How do I create a Windmill script that fetches data from an API?"

Claude: [Provides typed main function, dependency management, resource usage...]

The Core Workflow

1. Script Development - Write scripts with proper main functions, type annotations for auto-generated UIs, and dependency management that just works.

2. Flow Composition - Chain scripts into workflows using OpenFlow YAML. Loops, branches, error handlers, retries - all documented with examples.

3. App Building - Create custom UIs with drag-and-drop components. Connect runnables to fetch data, wire outputs between components.

4. Resource Management - Set up typed connections to databases, APIs, and services. Use $res: and $var: syntax for secure credential handling.

5. CLI Sync - Push and pull between local development and Windmill workspaces. Git-based staging/production workflows with proper CI/CD.

6. MCP Integration - Execute scripts, manage resources, and automate your workspace directly through Claude when MCP is configured.

What's Inside

Skills Library

.claude/skills/windmill-development/
├── SKILL.md           (707 lines)
├── REFERENCE.md       (802 lines)
└── scripts/
    ├── validate-script-structure.sh
    └── validate-flow-yaml.sh

SKILL.md - Core development guide

• Script patterns for TypeScript, Python, Go, Bash
• Flow YAML structure with module types
• App components and runnables
• CLI commands for sync, push, pull
• MCP server comparison and configuration
• Best practices and error handling

REFERENCE.md - Detailed technical reference

• Complete Python/TypeScript client API
• Full OpenFlow specification
• All module types (rawscript, script, forloop, branchone, branchall)
• Resource type schemas
• Script metadata YAML structure
• Environment variables
• Git sync with GitHub Actions
• 60+ MCP tools documented with parameters
• Troubleshooting guide

Validation Scripts - Zero-token deterministic checks

• validate-script-structure.sh - Verify script files have main function, metadata, lockfile
• validate-flow-yaml.sh - Check flow YAML has required fields

MCP Support

The skill documents both available MCP servers:

Server	Tools	Best For
Official Windmill MCP	~15	Running scripts, checking jobs
rothnic/windmill-mcp	500+	Full development workflow

With rothnic/windmill-mcp, Claude can:

• Create and update scripts, flows, and apps
• Set up resources and variables
• Manage schedules and folders
• Execute and monitor jobs
• Handle user/group permissions

Philosophy

• Type Everything - Type annotations generate UIs and catch errors early
• Scripts Are Building Blocks - Keep scripts focused, compose them in flows
• Resources Over Hardcoding - Never embed credentials, always use typed resources
• Git Sync for Production - Separate staging/production, deploy through CI
• Local Development - Edit in your IDE, sync with wmill, test with VS Code extension

Contributing

To improve the skill:

1. Fork this repository
2. Edit SKILL.md for common patterns or REFERENCE.md for technical details
3. Keep SKILL.md under 800 lines (use progressive disclosure)
4. Test that examples are accurate
5. Submit a PR

Updating

Pull the latest version:

cd .claude/skills/windmill-development
git pull origin main

Research Sources

This skill was built from official Windmill documentation:

• Windmill Docs
• Script Editor
• Flow Architecture
• OpenFlow Spec
• CLI Reference
• MCP Integration
• Local Development

License

MIT License - see LICENSE file for details

Support

• Issues: https://github.com/kfriede/Windmill-Skill/issues
• Windmill Docs: https://www.windmill.dev/docs
• Windmill Hub: https://hub.windmill.dev/