Introduction
# Asana
This skill provides a dependency-free Node.js CLI that calls the Asana REST API (v1) using a **Personal Access Token (PAT)**.
- Script: `{baseDir}/scripts/asana.mjs` - Auth: `ASANA_PAT` (preferred) or `ASANA_TOKEN` - Output: **JSON only** (stdout), suitable for agents and automation
## Setup
1. Create an Asana PAT in your Asana account (Developer Console is **not** required for PAT usage). 2. Provide the token to OpenClaw/Clawdbot as `ASANA_PAT`.
### Common injection patterns
- Shell env (local testing):
`export ASANA_PAT="..."`
- OpenClaw config (recommended): set `skills.entries.asana.apiKey` (or `env.ASANA_PAT`) so the secret is injected only for the agent run.
### Configure via OpenClaw CLI (recommended)
This is the safest way to set the PAT because it keeps secrets out of prompts and ad-hoc shell history.
**Recommended (apiKey → ASANA_PAT):**
```bash openclaw config set skills.entries.asana.enabled true openclaw config set skills.entries.asana.apiKey "ASANA_PAT_HERE" ```
`skills.entries.asana.apiKey` is a convenience field: for skills that declare `metadata.openclaw.primaryEnv`, OpenClaw injects `apiKey` into that env var for the agent run (this skill’s primary env is `ASANA_PAT`).
**Alternative (explicit env):**
```bash openclaw config set skills.entries.asana.enabled true openclaw config set skills.entries.asana.env.ASANA_PAT "ASANA_PAT_HERE" ```
**Verify what is stored:**
```bash openclaw config get skills.entries.asana openclaw config get skills.entries.asana.enabled openclaw config get skills.entries.asana.apiKey ```
**Remove a stored token:**
```bash openclaw config unset skills.entries.asana.apiKey # or openclaw config unset skills.entries.asana.env.ASANA_PAT ```
#### Important: sandboxed runs
When a session is sandboxed, skill processes run inside Docker and do **not** inherit the host environment. In that case, `skills.entries.*.env/apiKey` applies to host runs only.
Set Docker env via:
- `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`) - or bake the env into your sandbox image
## First calls (sanity + discovery)
- Who am I:
`node {baseDir}/scripts/asana.mjs me`
- List workspaces:
`node {baseDir}/scripts/asana.mjs workspaces`
- (Recommended) Set a default workspace once:
`node {baseDir}/scripts/asana.mjs set-default-workspace --workspace <workspace_gid>`
## ID resolution
When the user provides names (project/task/user), resolve to GIDs using one of:
- `typeahead --workspace <gid> --resource_type project|task|user --query "..."` (fast, best default) - `projects --workspace <gid> --all` (enumerate) - `users --workspace <gid> --all` (enumerate)
Avoid guessing a GID when multiple matches exist.
## Core: tasks
### List tasks assigned to a user (personal productivity)
`node {baseDir}/scripts/asana.mjs tasks-assigned --assignee me --workspace <workspace_gid> --all`
### List tasks in a project
`node {baseDir}/scripts/asana.mjs tasks-in-project --project <project_gid> --all`
### Search tasks (Advanced Search API)
Canonical primitive: `search-tasks` (supports many filters; preferred over adding narrow “search helper” commands).
One-liner example (search within a project):
`node {baseDir}/scripts/asana.mjs search-tasks --workspace <gid> --project <project_gid> --text "..." --all`
Useful filters: - `--assignee me|<gid|email>` (maps to `assignee.any`) - `--completed true|false` - `--created_at.after <iso>` / `--modified_at.after <iso>` - `--due_on.before YYYY-MM-DD` / `--due_at.before <iso>` - `--is_blocked true|false` / `--is_blocking true|false`
### Create / update / complete
- Create:
`node {baseDir}/scripts/asana.mjs create-task --workspace <gid> --name "..." --projects <project_gid> --assignee me`
- Update:
`node {baseDir}/scripts/asana.mjs update-task <task_gid> --name "..." --due_on 2026-02-01`
- Complete:
`node {baseDir}/scripts/asana.mjs complete-task <task_gid>`
## Project manager workflows
This skill supports the workflows commonly expected from a PM in Asana:
- Keep a **project brief** up to date (`upsert-project-brief`) - Write **status updates** (`create-status-update`) - Work with **timelines** (start/due dates) and shift schedules safely - Use **custom fields** as first-class metadata - Interpret **blockers** and dependency graphs (`project-blockers`, `dependencies`, `dependents`)
### Project brief
- Read:
`node {baseDir}/scripts/asana.mjs project-brief <project_gid>`
- Upsert (create or update):
`node {baseDir}/scripts/asana.mjs upsert-project-brief <project_gid> --title "Project brief" --html_text "<body>...</body>"`
### Status updates
- Create:
`node {baseDir}/scripts/asana.mjs create-status-update --parent <project_gid> --status_type on_track --text "Weekly update..."`
- List:
`node {baseDir}/scripts/asana.mjs status-updates --parent <project_gid> --all`
### Sections and moving tasks
- List sections:
`node {baseDir}/scripts/asana.mjs sections --project <project_gid> --all`
- Create section:
`node {baseDir}/scripts/asana.mjs create-section --project <project_gid> --name "Blocked"`
#### Add a task to a project
Command: `add-task-to-project`
Calls `POST /tasks/{task_gid}/addProject` and supports optional section placement and ordering.
Examples:
`node {baseDir}/scripts/asana.mjs add-task-to-project <task_gid> --project <project_gid>`
With section + ordering:
`node {baseDir}/scripts/asana.mjs add-task-to-project <task_gid> --project <project_gid> --section <section_gid> --insert_before null --insert_after null`
(`--section`, `--insert_before`, and `--insert_after` are optional; when provided they are passed through in the request body.)
#### Remove a task from a project
Command: `remove-task-from-project`
Calls `POST /tasks/{task_gid}/removeProject`.
Example:
`node {baseDir}/scripts/asana.mjs remove-task-from-project <task_gid> --project <project_gid>`
## Custom fields
Custom fields are critical for reliable PM automation.
- List a project’s custom fields:
`node {baseDir}/scripts/asana.mjs project-custom-fields <project_gid> --all`
- Read a custom field definition:
`node {baseDir}/scripts/asana.mjs custom-field <custom_field_gid>`
- Set task custom fields on create/update:
`node {baseDir}/scripts/asana.mjs update-task <task_gid> --custom_fields '{"<custom_field_gid>":"<value>"}'`
Notes: - For enums, the value is typically the enum option GID. - For numbers, send a JSON number.
## Rich text, mentions, and reliability
Asana rich text fields are **XML-valid HTML fragments** wrapped in a `<body>` root element. The API rejects invalid XML or unsupported tags.
Key points: - Use `html_notes` for task descriptions. - Use `html_text` for comments/stories and status updates. - Avoid unsupported tags like `<p>` and `<br>`; prefer literal newlines (`\n`) and `<hr/>` separators. - For mentions/links, use `<a data-asana-gid="..."></a>` (or a self-closing `<a .../>`).
### Mention notifications
Creating a mention link does **not** guarantee notification delivery if the user is not already assigned or following.
For reliable pings, do one of: - Assign the user first, then post the comment, OR - Add the user as a follower, wait a few seconds, then post the comment
This skill supports the “add follower + wait” pattern:
`node {baseDir}/scripts/asana.mjs comment <task_gid> --html_text "<body>Hi <a data-asana-gid=\"<user_gid>\"/>...</body>" --ensure_followers <user_gid> --wait_ms 2500`
Plain text comments (`--text`) do **not** create real @-mentions via the API; they remain plain text.
## Attachments, uploads, and inline images
- Upload a file attachment to a task:
`node {baseDir}/scripts/asana.mjs upload-attachment --parent <task_gid> --file /path/to/file.png`
- Embed an existing image attachment inline (tasks + project briefs only):
`node {baseDir}/scripts/asana.mjs append-inline-image --attachment <attachment_gid> --task <task_gid>`
## Activity feed / “inbox-like” workflows
Asana does not provide a single universal “inbox” API for all notifications. The closest stable primitive is the **Events** endpoint scoped to a specific resource (project, task, etc.).
Use: - `events --resource <gid>` to pull incremental changes on a project (or a user's "My Tasks" project) - The command stores a sync token locally so subsequent runs fetch only changes
## Timeline shifting
- Shift one task (optionally include subtasks):
`node {baseDir}/scripts/asana.mjs shift-task-dates <task_gid> --delta_days 7 --dry_run true`
- Shift an entire project’s tasks:
`node {baseDir}/scripts/asana.mjs shift-project-tasks --project <project_gid> --delta_days -3 --dry_run true --all`
Run with `--dry_run true` first, then re-run with `--dry_run false`.
## Out of scope
- Portfolios (premium) are intentionally omitted. - “Bot personality” is not embedded here; configure behavior in your agent prompt.