asana

Organize Asana projects and tasks, configure custom fields and rules, and automate scoped updates through its API.

SKILL.md

GitHub

Asana Work Tracking AI Skill Guide

Overview & Engine Architecture

Asana organizes work as tasks inside projects (list, board, timeline, or calendar views). Sections group stages; custom fields capture structured metadata; rules automate assignments and moves. The API supports webhooks and CRUD for tasks/projects. Agents keep projects lean, use custom fields instead of title prefixes, and avoid rules that comment on every keystroke.

Workspaces / Teams
   -> Projects (sections / columns)
       -> Tasks + subtasks
       -> Custom fields / dependencies / assignees
Rules / API / webhooks -> automate moves and syncs

When to use this skill

  • Setting up team projects and intake templates
  • Designing rules for triage without noise
  • Syncing engineering tickets or CRM events into Asana
  • Cleaning overloaded multi-homed task graphs

Operational directives

  1. Prefer one home project per task; multi-home only when two teams truly share ownership.
  2. Put status in sections or a single Status custom field - not competing free-text conventions.
  3. Rules: filter triggers tightly; never create task-create loops across projects.
  4. Subtasks are for checklist work, not a shadow project hierarchy.
  5. Store personal access tokens securely; prefer service accounts for bots.

API sketch

curl -s -X POST "https://app.asana.com/api/1.0/tasks" \
  -H "Authorization: Bearer $ASANA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Ship webhook idempotency",
      "projects": ["PROJECT_GID"],
      "assignee": "USER_GID",
      "notes": "Acceptance: retries do not double-write"
    }
  }'

Project hygiene

Smell Better approach
20+ sections Collapse to backlog / doing / blocked / done
Rules that @mention on every edit Notify only on assignee change or due-date slip
Giant comment threads as specs Link to Confluence/Notion doc; keep task actionable
Duplicate custom fields across projects Workspace-level field library where possible

Best practices

  • Name tasks as outcomes ("Publish v2 pricing page"), not vague verbs ("Pricing").
  • Use due dates sparingly; overload makes them meaningless.
  • Templates for recurring launches beat copy-paste archaeology.
  • Webhooks should verify authenticity and process idempotently by event/task GID.

Limitations

  • Asana plans gate advanced rules, portfolios, and admin controls.
  • API rate limits and pagination require careful bulk sync design.
  • Goals/Portfolios features differ from core task APIs.

Related skills

  • @trello - simpler board-centric tracking
  • @jira - engineering-heavy issue workflows
  • @zapier - no-code Asana automations