home / skills / windmill-labs / windmill / write-script-go

write-script-go skill

safe

/system_prompts/auto-generated/skills/write-script-go

This skill helps you write Go scripts for Windmill workflows, returning JSON-serializable results and proper error handling.

npx playbooks add skill windmill-labs/windmill --skill write-script-go

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.3 KB

---
name: write-script-go
description: MUST use when writing Go scripts.
---

## CLI Commands

Place scripts in a folder. After writing, run:
- `wmill script generate-metadata` - Generate .script.yaml and .lock files
- `wmill sync push` - Deploy to Windmill

Use `wmill resource-type list --schema` to discover available resource types.

# Go

## Structure

The file package must be `inner` and export a function called `main`:

```go
package inner

func main(param1 string, param2 int) (map[string]interface{}, error) {
    return map[string]interface{}{
        "result": param1,
        "count":  param2,
    }, nil
}
```

**Important:**
- Package must be `inner`
- Return type must be `({return_type}, error)`
- Function name is `main` (lowercase)

## Return Types

The return type can be any Go type that can be serialized to JSON:

```go
package inner

type Result struct {
    Name  string `json:"name"`
    Count int    `json:"count"`
}

func main(name string, count int) (Result, error) {
    return Result{
        Name:  name,
        Count: count,
    }, nil
}
```

## Error Handling

Return errors as the second return value:

```go
package inner

import "errors"

func main(value int) (string, error) {
    if value < 0 {
        return "", errors.New("value must be positive")
    }
    return "success", nil
}
```

Overview

This skill guides writing Go scripts that run inside the platform and become webhooks, workflows, or UI actions. It enforces the required package, function signature, and JSON-serializable return types so scripts integrate reliably. Follow the CLI steps to generate metadata and deploy scripts to the platform.

How this skill works

It inspects Go source files to ensure the package is named inner and that a function called main exists with a (T, error) return signature. It validates that return types are JSON-serializable and that errors are returned as the second value. After coding, it helps generate .script.yaml/.lock metadata and push the script to the platform using the CLI.

When to use it

Writing new Go-based scripts for workflows or webhooks
Converting script logic into a deployable platform action
Ensuring Go functions meet the platform's packaging and signature rules
Testing serialization compatibility of returned data before deployment
Deploying scripts to self-hosted or cloud instances via the CLI

Best practices

Use package name inner exactly; other names will not be accepted
Name the exported function main (lowercase) and return (value, error) consistently
Return only types that serialize to JSON (primitives, structs with json tags, maps, slices)
Perform input validation and return descriptive errors as the second return value
Run wmill script generate-metadata and wmill sync push after changes to update metadata and deploy

Example use cases

Simple data transform: accept parameters, return a JSON-serializable struct for downstream steps
Database lookup: query Postgres, return a map or struct with results and handle DB errors
Webhook handler: parse input, perform action, return status object or error
Automation task: execute business logic, expose count/status in returned JSON for dashboards

FAQ

What must my Go package be named?

Package must be named inner exactly.

How should my function be declared?

Export a function named main that returns (T, error), where T is any JSON-serializable type.