# Taskfiles

> Create, modify, and maintain Taskfiles following Task (https://taskfile.dev) best practices. Use when: (1) Creating new tasks or Taskfiles, (2) Modifying existing task definitions, (3) Adding new task includes, (4) Debugging task execution issues, (5) Questions about Taskfile syntax or patterns, (6) Running or understanding "task" commands, (7) Questions about available tasks or task namespaces. Triggers: "taskfile", "Taskfile.yaml", "task command", "task:", "create task", "add task", "task --list", "task tg:", "task inv:", "task wt:", ".taskfiles/", "how to run", "available tasks", "task syntax", "taskfile.dev" This skill covers the repository's specific conventions in .taskfiles/ and the root Taskfile.yaml.

- Skill: `ionfury/taskfiles` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add ionfury/taskfiles`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ionfury/taskfiles/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ionfury (https://skillmd.com/u/ionfury)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ionfury/taskfiles

---


# Taskfiles

## Repository Structure

```
Taskfile.yaml                    # Root: includes namespaced taskfiles
.taskfiles/
├── inventory/taskfile.yaml      # inv: IPMI host management
├── terragrunt/taskfile.yaml     # tg: Infrastructure operations
├── worktree/taskfile.yaml       # wt: Git worktree management
└── renovate/taskfile.yaml       # renovate: Config validation
```

## File Template

Always include schema and version:
```yaml
---
# yaml-language-server: $schema=https://taskfile.dev/schema.json
version: "3"

vars:
  MY_DIR: "{{.ROOT_DIR}}/path"

tasks:
  my-task:
    desc: Short description for --list output.
    cmds:
      - echo "hello"
```

## Patterns

### Include New Taskfiles
Add to root `Taskfile.yaml`:
```yaml
includes:
  namespace: .taskfiles/namespace
```

### Wildcard Tasks
Use for parameterized operations:
```yaml
plan-*:
  desc: Plans a specific terragrunt stack.
  vars:
    STACK: "{{index .MATCH 0}}"
  label: plan-{{.STACK}}
  cmds:
    - terragrunt plan --working-dir {{.INFRASTRUCTURE_DIR}}/stacks/{{.STACK}}
  preconditions:
    - which terragrunt
    - test -d "{{.INFRASTRUCTURE_DIR}}/stacks/{{.STACK}}"
```

### Dependencies
Run deps in parallel before cmds:
```yaml
apply-*:
  deps: [use, fmt]
  cmds:
    - terragrunt apply ...
```

### Internal Helper Tasks
```yaml
ipmi-command:
  internal: true
  silent: true
  requires:
    vars: [HOST, COMMAND]
  cmds:
    - ipmitool ... {{.COMMAND}}
```

### Preconditions
```yaml
preconditions:
  - which required-tool
  - test -d "{{.PATH}}"
  - sh: test "{{.VALUE}}" != ""
    msg: "VALUE cannot be empty"
```

### Source Tracking
```yaml
fmt:
  sources:
    - "{{.DIR}}/**/*.tf"
  generates:
    - "{{.DIR}}/**/*.tf"
  cmds:
    - tofu fmt -recursive
```

### Dynamic Variables and For Loops
```yaml
vars:
  VALID_HOSTS:
    sh: "cat {{.INVENTORY_FILE}} | yq -r '.hosts | keys[]'"

power-status:
  cmds:
    - for: { var: VALID_HOSTS }
      cmd: task inv:status-{{.ITEM}}
```

### CLI Arguments
```yaml
new:
  requires:
    vars: [CLI_ARGS]
  vars:
    NAME: "{{.CLI_ARGS}}"
  cmds:
    - git worktree add ... -b "{{.NAME}}"
```

Usage: `task wt:new -- feature-branch`

## References

- [references/task-catalog.md](references/task-catalog.md) - All available tasks by namespace
- [references/styleguide.md](references/styleguide.md) - Naming and formatting conventions
- [references/schema.md](references/schema.md) - Complete property reference
- [references/cli.md](references/cli.md) - CLI flags and options