# asana-api

Adopt this skill: https://proskills.md/skills/other/anthropics-claude-tag-plugins-asana-skills-asana-api

Page: https://proskills.md/skills/other/anthropics-claude-tag-plugins-asana-skills-asana-api
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: asana/skills/asana-api/SKILL.md
size: 8034
upstream: https://github.com/anthropics/claude-tag-plugins/blob/main/asana/skills/asana-api/SKILL.md

````text
---
name: asana-api
description: Read and manage Asana tasks, projects, sections, comments, and workspaces. Use this whenever the user wants to list or search tasks, create or update a task, complete a task, comment on a task, move tasks between projects or sections, look up a project or workspace, or ask "what's on my Asana list" — even if they don't say "API". Also use it for any app.asana.com URL or an Asana task/project gid. Always start from this skill when interacting with this service — its bundled scripts and recipes are the fastest path.
---

Asana's REST API is rooted at `https://app.asana.com/api/1.0`. Three things are true of every call:
every object is identified by a string **`gid`** (global id), every response wraps its payload in a
top-level `data` key, and write bodies wrap their fields in `data` too. Most reads return a
**compact** record (`gid`, `name`, `resource_type`) — ask for more with `opt_fields`.

Resources nest predictably: a **workspace** (an *organization* if it has one) holds **projects** and
**users**; a **project** holds **sections** and **tasks**; a **task** carries comments and activity
as **stories**, plus subtasks, tags, attachments, and custom fields.

## Request setup

Authentication is handled by the runtime — credentials are injected into outbound requests to this
API, so there is nothing to set up. Do not try to create, mint, refresh, or validate tokens or keys.
Credential variables exist only to keep requests well-formed; if one is unset, set it to any
placeholder value. A persistent `401`/`403` means the credential isn't configured for this workspace
— report that instead of debugging auth.

Requests use a bearer token. The base URL is fixed (not per-instance), but workspace/project/task
gids are real and part of the path:

```bash
export ASANA_TOKEN="placeholder"                 # injected by the runtime; any value works
export ASANA_BASE="https://app.asana.com/api/1.0"
```

Define a helper once per session:

```bash
asana() { curl -sS -H "Authorization: Bearer ${ASANA_TOKEN}" \
  -H "Accept: application/json" -H "Content-Type: application/json" "$@"; }
```

**Sanity check** — confirm the token works and find your workspace gids:

```bash
asana "${ASANA_BASE}/users/me?opt_fields=name,email,workspaces.name" \
  | jq '.data | {gid, name, email, workspaces: [.workspaces[]? | {gid, name}]}'
# 200 with your user + workspaces → wired up. 401 → credential not configured; report it.
```

## Response conventions

Three patterns repeat across every endpoint below — stated once so the recipes stay short:

- **The `data` envelope.** Reads return `{"data": ...}` (object or array); writes send
  `{"data": {...}}` and return the result under `data`. An error replaces `data` with `errors` (see
  Error handling). Project `.data`, and check `.errors` when it's missing.
- **`gid`, not name.** Everything is referenced by its string `gid` — resolve names to gids first
  (workspaces, projects, users, tags; recipe 9).
- **`opt_fields` for fields.** Compact records carry only `gid`, `name`, `resource_type`. Add a
  comma-separated `opt_fields` to expand, with dot-notation for relations
  (`assignee.name`, `memberships.section.name`); `gid` is always returned. On POST/PUT, nest options
  in an `options` object beside `data`.

## Core operations

### 1. List tasks (`scripts/asana_tasks.sh`)

Run through the bundled script (path is relative to this skill's directory): it GETs `/tasks`
filtered by project, tag, section, or assignee+workspace, sends an `opt_fields` list, follows
`next_page.offset` through every page, and emits TSV or JSONL.

```bash
scripts/asana_tasks.sh --project 1201234567890123 --limit 200
scripts/asana_tasks.sh --assignee me --workspace 1209876543210987 --completed-since now
```

- Exactly one selector is required: `--project GID`, `--tag GID`, `--section GID`, or
  `--assignee GID --workspace GID` (assignee needs a workspace). `--assignee me` resolves the caller
  via `/users/me`.
- `--completed-since WHEN` — ISO 8601, or `now` to show only incomplete tasks (omit to include all).
- `--fields LIST` — `opt_fields` to request. The TSV columns are fixed (gid, name, completed,
  assignee, due_on, permalink_url); extra fields appear only in `--json` output.
- `--limit N` caps tasks fetched (default 100, `0` = everything); `--page-size N` sets the
  per-request page (1-100, default 100). Fetched count and any truncation warning go to stderr.
- `--json` emits one raw task object per line instead of TSV.
- Exit codes: `0` success, `1` request failed / API error / bad arguments (the API's own
  `errors[].message` is printed to stderr).

If the script errors, read it — it's plain `curl` + `jq` — and debug against `references/api.md`.

### 2. Get one task

```bash
asana "${ASANA_BASE}/tasks/TASK_GID?opt_fields=name,notes,completed,assignee.name,due_on,projects.name,tags.name,parent.name,num_subtasks,custom_fields.name,custom_fields.display_value,permalink_url" \
  | jq '.data'
```

With no `opt_fields` you get only the compact record. Read a task's comments with recipe 5.

### 3. Create a task

Fields nest under `data`. One of `workspace`, `projects`, or `parent` is required (a standalone task
needs a `workspace`).

```bash
asana -X POST "${ASANA_BASE}/tasks" -d '{
  "data": {
    "name": "Draft the launch checklist",
    "notes": "Plain-text body. Use html_notes for rich text.",
    "workspace": "1209876543210987",
    "projects": ["1201234567890123"],
    "assignee": "me",
    "due_on": "2026-06-15",
    "followers": ["1200000000000001"]
  }
}' | jq '.data | {gid, name, permalink_url}'
```

`assignee` and `followers` take user gids (or `me`); `due_on` is a date, `due_at` an ISO 8601
timestamp. Use `html_notes` for rich text (Asana's HTML subset). Custom-field values go in
`custom_fields: {"FIELD_GID": value}`.

### 4. Update or complete a task

PUT replaces only the fields you send (still wrapped in `data`). You complete a task by setting
`completed` — there is no separate endpoint.

```bash
asana -X PUT "${ASANA_BASE}/tasks/TASK_GID" -d '{"data": {"completed": true}}' \
  | jq '.data | {gid, completed, completed_at}'
asana -X PUT "${ASANA_BASE}/tasks/TASK_GID" -d '{"data": {"name": "Revised", "due_on": "2026-07-01"}}'
```

Delete: `asana -X DELETE "${ASANA_BASE}/tasks/TASK_GID"` — returns an empty `data: {}`; the task
goes to the trash.

### 5. Comment on a task / read its activity (stories)

Stories are a task's comments plus system activity. Only comment stories can be created.

```bash
# add a comment
asana -X POST "${ASANA_BASE}/tasks/TASK_GID/stories" \
  -d '{"data": {"text": "Reproduced on main."}}' | jq '.data | {gid, created_at}'

# read comments only (filter out system activity client-side)
asana "${ASANA_BASE}/tasks/TASK_GID/stories?opt_fields=resource_subtype,text,created_by.name,created_at" \
  | jq '.data[] | select(.resource_subtype=="comment_added") | {by: .created_by.name, text, created_at}'
```

Use `html_text` instead of `text` for a rich-text comment.

### 6. Search tasks in a workspace (premium)

Advanced search lives at the workspace and is **premium-only**. It does **not** offset-paginate
(results are unstable, capped at 100) — narrow with filters, or sort by `created_at` and page
manually with `created_at.before`. For plain "tasks in a project / mine", prefer the list script
(recipe 1): it pages fully and works on free plans.

```bash
asana -G "${ASANA_BASE}/workspaces/WORKSPACE_GID/tasks/search" \
  --data-urlencode "text=launch" \
  --data-urlencode "assignee.any=me" \
  --data-urlencode "completed=false" \
  --data-urlencode "sort_by=modified_at" \
  --data-urlencode "opt_fields=name,assignee.name,due_on,permalink_url" \
  | jq '.data[] | {gid, name, due_on}'
```

### 7. Projects and sections

```bash
asana -G "${ASANA_BASE}/projects" --data-urlencode "workspace=WORKSPACE_GID" \
  --data-urlencode "archived=false" --data-urlencode "opt_fields=name,owner.name" \
  | jq '.data[] | {gid, name}'
a
````

## File: README.md
upstream: https://github.com/anthropics/claude-tag-plugins/blob/main/README.md

````text
# claude-tag-plugins

Plugins for [@claude](https://claude.ai) that connect the agent to common SaaS services.
Each service is its own plugin, so a workspace can connect exactly the services it uses.

## Plugins

| Plugin | What it covers |
|--------|----------------|
| **[asana](./asana)** | Tasks, projects, sections, comments; list, search, create/update |
| **[bigquery](./bigquery)** | Run SQL, list datasets/tables, fetch schemas, manage jobs |
| **[claude-tag-data-viz](./claude-tag-data-viz)** | Compose polished charts from tabular data — PNG, SVG, or self-contained interactive HTML |
| **[claude-tag-oncall](./claude-tag-oncall)** | Oncall for @Claude in Slack — alert triage, incident investigation, sitreps, postmortems, rotation handoff |
| **[claude-tag-troubleshoot](./claude-tag-troubleshoot)** | Configure and debug @Claude agents — agent scopes, profiles, connections, plugin/skill loading |
| **[confluence](./confluence)** | Search pages, read/create/update content, spaces, comments |
| **[datadog](./datadog)** | Logs, metrics, monitors, dashboards, SLOs, events, traces, incidents |
| **[enterprise-search](./enterprise-search)** | Search across all connected sources, read documents, submit relevance feedback |
| **[google-drive](./google-drive)** | Search, read, upload, share files; folders; Docs/Sheets export |
| **[grafana](./grafana)** | Dashboards, datasource queries, alerting, annotations, folders |
| **[hubspot](./hubspot)** | Contacts, companies, deals, tickets; CRM search; associations |
| **[jira](./jira)** | Search with JQL, create/transition issues, comments, sprints |
| **[linear](./linear)** | Issues, projects, cycles, teams |
| **[notion](./notion)** | Search, pages, databases, blocks, block children |
| **[pagerduty](./pagerduty)** | Incidents, who's on-call, schedules, escalation policies, services |
| **[redshift](./redshift)** | Run SQL, poll results, list schemas/tables |
| **[salesforce](./salesforce)** | Query records, CRUD objects, describe schema, composite requests |
| **[sentry](./sentry)** | Issues, events, projects, releases, stats |
| **[snowflake](./snowflake)** | Run SQL statements, poll/fetch results, warehouses |

## Getting Started

### Claude Tag

```bash
# Add the marketplace first
claude plugin marketplace add anthropics/claude-tag-plugins

# Install the services you use
claude plugin install jira@claude-tag-plugins
claude plugin install datadog@claude-tag-plugins
```

Once installed, skills activate automatically when relevant.

## How It Works

Each service plugin follows the same structure:

```
<service>/
├── .claude-plugin/plugin.json   # Manifest
└── skills/<service>-api/
    ├── SKILL.md                 # How to connect and core operations
    ├── references/              # Full endpoint catalog, read on demand
    └── scripts/                 # Executable helpers (where present)
```

The two helper plugins use the same `skills/<name>/` layout but carry different
content: [`claude-tag-data-viz`](./claude-tag-data-viz) ships a Python charting
kit instead of curl scripts, and [`claude-tag-troubleshoot`](./claude-tag-troubleshoot)
ships a slash command plus two documentation-only skills.

## Authentication

Plugins contain **no auth setup instructions** — authentication is handled by the runtime.
Credentials are injected into outbound requests; the environment variables each plugin
references (`$DD_API_KEY`, `$ATLASSIAN_API_TOKEN`, `$BQ_TOKEN`, ...) exist only to keep requests
well-formed and may hold placeholder values.

## Security Considerations

The bundled scripts use `Authorization: Bearer ${TOKEN}` headers. When run **outside** the
credential-injecting runtime (e.g. local development or CI without secrets configured), the
token variable will be unset or hold a placeholder — requests will be rejected with `401`.
Never commit real credentials; configure them through your runtime's secret injection
mechanism. To report a security vulnerability, see [SECURITY.md](./SECURITY.md).

## Maintenance Status

Active — maintained by Anthropic. Bug reports and PRs are welcome; see
[CONTRIBUTING.md](./CONTRIBUTING.md).

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

Apache License 2.0 — see [LICENSE](./LICENSE).

The `claude-tag-data-viz` plugin bundles third-party JavaScript libraries (React, ReactDOM, react-is, Recharts) under their original MIT licenses. See [NOTICE](./NOTICE) for full attribution and license text.
````
