Taskfile Authoring Reference

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/go-task/references/taskfile-authoring.md
Description	Not specified

Source Content

Taskfile Authoring Reference

Use this reference for go-task details that do not need to live in the trigger file.

Defaults

Every project should usually expose task dev, task prod, task setup, and task reset when those concepts exist. dev and prod may delegate to scripts/run.sh <mode>, which detects the stack and sets APP_ENV.

Configuration should live in .env, .env.local, top-level vars, and env. Load .env.local before .env with dotenv: ['.env.local', '.env'], and commit .env.example instead of secrets.

Use included Taskfiles when a tool family grows past a handful of tasks. Common includes are Taskfile.docker.yml, Taskfile.kubectl.yml, Taskfile.db.yml, and Taskfile.docs.yml. Mark project-specific includes optional: true when the root Taskfile should work without them.

Task Keys

Common top-level keys are version, includes, output, silent, method, run, set, shopt, vars, env, dotenv, and tasks.

Common task-level keys are desc, summary, aliases, cmds, deps, vars, env, dotenv, sources, generates, status, preconditions, requires, if, dir, silent, interactive, internal, prompt, platforms, run, method, failfast, ignore_error, watch, label, and prefix.

Command Forms

Use plain string commands for simple commands. Use object commands when a command needs silent, ignore_error, platforms, or if. Use task calls with task: and vars: for composition. Use defer: for cleanup that must run at task end.

deps run in parallel before cmds. For ordered steps, chain task: entries inside cmds. Use failfast: true when dependency failure should stop remaining parallel work.

Variables

Static vars can be strings, booleans, integers, arrays, or maps. Dynamic vars use sh:. Preserve variable type with ref: instead of stringifying through a template.

Variable precedence from highest to lowest is task-call vars, task vars, included-file vars, global vars, and environment.

Useful built-ins include {{.TASK}}, {{.CLI_ARGS}}, {{.CLI_ARGS_LIST}}, {{.MATCH}}, {{.ITEM}}, {{.CHECKSUM}}, {{.ROOT_DIR}}, {{.TASKFILE_DIR}}, and {{.USER_WORKING_DIR}}.

Inputs And Guards

Use requires.vars to fail fast on missing inputs. Use enum or enum.ref for constrained inputs such as environment names. Use preconditions with a msg for shell checks that must pass before execution.

Use if: on a task, command, or task call to skip behavior. Shell-form if: passes when the command exits zero. Template-form if: passes when the expression is true.

Use prompt: on destructive tasks such as reset, clean, prune, delete, and deploy-to-production operations.

Incremental Work

Declare sources and generates to skip unchanged work by checksum. Use method: timestamp when mtime comparison is better than checksum. Use status: for “already provisioned” logic that is not a file diff.

Includes

Short form:

includes:
  k8s: ./Taskfile.kubectl.yml

Long form:

includes:
  k8s:
    taskfile: ./Taskfile.kubectl.yml
    optional: true
    vars:
      NAMESPACE: default

Tasks are called as task k8s:pods.

Recipe: Go Service

version: '3'

vars:
  BINARY_NAME: app
  BIN_DIR: bin

tasks:
  default:
    desc: List available tasks
    cmds:
      - task --list
    silent: true

  build:
    desc: Build the Go binary
    sources:
      - '**/*.go'
      - go.mod
      - go.sum
    generates:
      - '{{.BIN_DIR}}/{{.BINARY_NAME}}'
    cmds:
      - mkdir -p {{.BIN_DIR}}
      - go build -o {{.BIN_DIR}}/{{.BINARY_NAME}} ./...

  test:
    desc: Run Go tests
    cmds:
      - go test ./...

  lint:
    desc: Run Go lint checks
    cmds:
      - golangci-lint run

Recipe: Node Project

version: '3'

tasks:
  dev:
    desc: Start the development server
    cmds:
      - pnpm dev

  lint:
    desc: Run lint checks
    cmds:
      - pnpm lint

  typecheck:
    desc: Run TypeScript checks
    cmds:
      - pnpm typecheck

  test:
    desc: Run tests
    cmds:
      - pnpm test

  build:
    desc: Build production assets
    cmds:
      - pnpm build

Colon Rule

YAML treats : inside an unquoted scalar as a map separator. Quote any value containing a colon:

tasks:
  build:
    desc: "Build: production image"
    cmds:
      - "echo Build: production"