AgentSkillsCN

Taskfile Best Practices & Guidelines

Taskfile 最佳实践与指南

SKILL.md
--- frontmatter
priority: high
description: "Taskfile Best Practices & Guidelines"

priority: high

Taskfile Best Practices & Guidelines

Modular Design Principles:

  • •Each language gets its own task file in .task/languages/
  • •Workflows (build, test, lint, e2e) are orchestrated internally in .task/workflows/
  • •Configuration separated into .task/config/ (vars.yml, platforms.yml)
  • •Tool tasks in .task/tools/ (version-sync, pdfium, pre-commit, docs, smoke)
  • •Main Taskfile.yml is minimal - just includes and top-level entry points

Creating New Task Files:

  1. •Create .task/languages/{language}.yml for language-specific tasks
  2. •Include in main Taskfile.yml: {language}: taskfile: .task/languages/{language}.yml
  3. •Use namespace pattern: task {language}:build, task {language}:test
  4. •Support BUILD_PROFILE for dev/release/ci variants
  5. •Include both .dev and .release variants of build/test tasks

Variable Management:

  • •Global variables in .task/config/vars.yml (BUILD_PROFILE, VERSION, paths, OS/ARCH)
  • •Platform-specific in .task/config/platforms.yml (EXE_EXT, LIB_EXT, NUM_CPUS)
  • •Language-specific vars in language files (e.g., PYTHON_VERSION, RUST_LOG)
  • •Avoid hardcoding paths; use {{.ROOT}}, {{.CRATES_DIR}}, {{.PACKAGES_DIR}}, {{.TARGET_DIR}}
  • •Use {{.BUILD_PROFILE}} to determine debug vs. release builds
  • •Use {{.OS}}, {{.ARCH}}, {{.EXE_EXT}}, {{.LIB_EXT}} for cross-platform support

Task Naming Convention:

  • •Language tasks: task {language}:{action} (e.g., rust:build, python:test, node:lint)
  • •Workflow tasks: task {workflow}:{scope} (e.g., build:all, test:all:fast, lint:check)
  • •Tool tasks: task {tool}:{action} (e.g., version:sync, pdfium:install)
  • •Variants: :dev, :release, :ci, :fast, :check

Task Description Standards:

  • •Write task desc field for every task (used in task --list)
  • •Be descriptive: "Build Rust core in release mode" not just "Build Rust"
  • •Include BUILD_PROFILE if relevant: "Lint Python (uses ruff, mypy)"

Cross-Platform Considerations:

  • •Test commands on Windows, Linux, macOS before committing
  • •Use Taskfile path conventions (forward slashes converted automatically)
  • •Set platforms: [linux, darwin] or platforms: [windows] if OS-specific
  • •Use ENV variables for library paths: LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (macOS)

Error Handling:

  • •Always set requires: ["task"] or ensure task is available
  • •Use ignore_error: true sparingly; prefer explicit error handling
  • •Run pre-flight checks (e.g., version checks) in setup tasks
  • •Clear error messages for dependencies (e.g., "Install Rust via rustup")

Caching & Performance:

  • •Leverage {{.NUM_CPUS}} for parallel builds: cargo build -j {{.NUM_CPUS}}
  • •Cache dependencies between CI runs (Cargo.lock, npm-lock.yaml, etc.)
  • •Use :fast variants for quick validation; full tests in separate task
  • •Reuse tasks: task rust:build instead of duplicating build commands

Documentation & Discovery:

  • •Run task --list to see all available tasks (requires good desc fields)
  • •Run task {language}: to list all tasks in a namespace
  • •Update README when adding new major workflows
  • •Link to task files from docs when documenting CLI usage