Taskfile Authoring

Write lean, composable, verification-first Taskfiles for go-task v3. Keep the surface small, the cache correct, and the composition transparent.

When To Use

Use this skill when:

• Writing a new Taskfile.yml from scratch.
• Adding tasks to an existing Taskfile (before, not after, the diff).
• Refactoring an overgrown Taskfile (too many tasks, duplicated cmds).
• Splitting work into included sub-Taskfiles (includes:).
• Wiring sources: / generates: / method: for build caching.

Do not use for:

• CI platform configs (.github/workflows/*.yml) — that is not go-task.
• Makefiles, just recipes, or npm scripts — different tooling, different semantics.
• Pure shell scripts with no task runner — use a scripts/ directory instead.
• Designing the command contract for a skill-local CLI — use skill-cli-authoring, then return here to wire build, smoke, ci, and verify.

Core Premise

Three properties keep a Taskfile healthy:

1. Lean surface: few top-level tasks, each with a clear desc:. If a contributor cannot read the task --list output and guess what to run, there are already too many.
2. Composable: included sub-Taskfiles with explicit {{.TASKFILE_DIR}} paths, so an overlay dropped into any repo Just Works.
3. Verification-first: one canonical ci task that CI runs verbatim, and one verify task that wraps ci plus any repo-specific extras (work checks, wiki lint, etc.). No branching logic in CI.

The Canonical Aggregate Surface (advisory)

Most repos benefit from this shape:

• fmt — format in place
• lint — static checks
• test — run tests
• build — produce artifact(s)
• ci — aggregate: depends on lint, test, build (plus smoke where applicable). This is what CI runs.
• verify — wraps ci and adds repo-specific gates (e.g. work/wiki checks).

This is advisory — see references/canonical-surface.md for rationale and per-stack task counts.

Build Cache: sources / status / preconditions

Three mechanisms, three different jobs:

• preconditions: — fail loudly if the environment is wrong (tool missing, file absent). Runs before the task body.
• status: — skip if "already up to date." You write the check. All commands must exit 0 for the task to be skipped. No automatic source tracking.
• sources: + generates: + method: — automatic fingerprinting. Use method: checksum (default, CI-safe). Never method: timestamp in CI — git clone resets mtimes, so the task always runs.

Full decision flow and per-use-case recipes in references/build-cache.md.

Composition (includes:)

Two composition modes:

• flatten: true — transparent overlay. Included tasks become top-level. Use when a convention pack ships a Taskfile fragment and callers should type task verify, not task conventions:verify.
• Explicit dir: with a namespace key — genuine sub-domain. Use for work:check, wiki:lint, docs:build — things that feel like separate areas of the repo.

Variable precedence is surprising: the included file's own vars: win over the includer's includes.ns.vars: (pattern: use {{.FOO | default "..."}} inside the included file to make values overridable). Full precedence table and path-resolution rules in references/composition.md.

Reference & Template Index

Boundaries

• Stack guidance (Go, uv) is advisory.
• The skill does not opinionate on CI platform (.github/workflows/*.yml).
• For skill-local CLIs, this skill owns Taskfile wiring only. Command grammar, safety classes, JSON contracts, and plan/apply semantics belong to skill-cli-authoring.