Communitygithub.com

mwpryer/asnx

⚡ 에이전트 우선 Asana CLI, 스키마 인트로스펙션 내장

asnx란 무엇인가요?

이 스킬은 AI 에이전트가 Asana API와 직접 상호작용할 수 있도록 설계된 CLI 도구 `asnx`를 제공합니다. 엔티티와 액션을 기반으로 하는 평면적이고 일관된 명령 구조(`asnx <entity> <action>`)를 사용하며, `asnx describe` 명령을 통해 스키마를 실시간으로 탐색할 수 있어 에이전트가 API 구조를 학습하며 명령을 구성할 수 있습니다. 인증은 `--account` 플래그, 환경 변수(`ASANA_TOKEN`), 저장된 계정 순으로 해결되며, `asnx auth status`로 토큰 유효성을 확인할 수 있습니다. 입력은 개별 플래그 또는 `--json`을 통한 원시 JSON 본문을 지원하고, 출력은 `meta`와 `data`로 구성된 JSON 봉투(envelope) 형식으로 일관되게 반환됩니다. 커서 기반 페이지네이션, `--dry-run`을 통한 쓰기 미리보기, `--opt-fields`로 응답 최적화 등 에이전트 자동화에 적합한 기능을 제공하며, Claude Code, Cursor, Codex 등 다양한 AI 플랫폼에서 활용 가능합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add mwpryer/asnx

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

asnx: Asana CLI

asnx <entity> <action> [<gid>] [--flags...]

CLI는 항상 평면적(flat)입니다: asnx <entity> <action>. 하위 리소스와 동사 액션은 명시적으로 유지됩니다. 예를 들어 asnx tasks subtasks, asnx tasks create-subtasks, asnx tasks add-followers와 같습니다.

스키마 인트로스펙션(introspection)을 위해 asnx describe [<entity> [<action>]]를 사용하세요.

인증(Auth)

해결 순서: --account <name> > ASANA_TOKEN 환경 변수 > 저장된 단일 계정.

asnx auth status는 확인된 토큰을 API에 대해 검증합니다. 401 오류 진단에 사용하세요.

입력(Input)

쓰기(writes)는 개별 플래그 또는 원시 JSON 본문을 허용합니다. 충돌 시 --json이 우선합니다.

asnx tasks create --json '{"name":"bugfix","projects":["def"]}'

--json은 전체 Asana { "data": ... } 봉투가 아닌, 원시 요청 필드만 예상합니다.

출력(Output)

성공적인 명령은 meta와 data를 포함한 JSON 봉투를 출력합니다:

{
  "meta": {
    "command": "tasks.list",
    "status": 200,
    "nextPage": null
  },
  "data": [ ... ]
}
  • meta.command는 항상 entity.action (점 하나)입니다. 예: tasks.list, tasks.subtasks, project-briefs.create-for-project.
  • data는 래핑 해제된 Asana 페이로드입니다. 단일 리소스는 객체, 목록은 배열입니다.
  • meta.nextPage는 페이지네이션 오프셋(문자열) 또는 null입니다. --offset으로 전달하세요.

오류는 stderr로 {"error":{"status":...,"message":...,"help":...}} 형식으로 출력됩니다. 로컬 오류(사용법, 전송)의 경우 status는 null입니다. 오류 시 종료 코드는 항상 1입니다.

규칙(Rules)

  • --dry-run을 사용하여 쓰기 전에 미리보기를 확인하세요.
  • GET 요청에는 --opt-fields를 사용하여 응답을 작게 유지하세요.
  • 페이지네이션은 수동입니다: meta.nextPage를 확인하고 --offset으로 전달하세요.
  • GID를 추측하지 말고 먼저 조회하세요. asnx workspaces list로 시작한 다음, 예: asnx tasks search <workspace-gid> --text "bugfix".
  • 엔티티 명령이 unknown으로 반환되면 스키마 캐시가 없는 것입니다: asnx schema update를 실행하세요.
  • 점으로 구분된 Asana 필터는 CLI에서도 점을 유지합니다. 예: --projects.any 또는 --due-on.before.

주의사항(Gotchas)

  • start_on은 due_on이 필요합니다: 항상 함께 보내세요.
  • me는 위치 기반 GID 별칭이지 액션이 아닙니다. users me 대신 users get me를 사용하세요.
  • tasks for-project는 기본적으로 완료된 작업을 포함한 모든 작업을 반환합니다. 완료되지 않은 작업만 얻으려면 --completed-since <recent-timestamp> (예: now)를 전달하세요. Asana는 그 시점 이후로 완료되지 않았거나 완료된 작업을 반환합니다.
  • tasks duplicate 및 projects duplicate는 모든 연결 관계를 가져오지 않습니다. 복제된 작업은 --include로 복사할 요소(예: --include projects,subtasks,assignee)를 지정하지 않으면 프로젝트 멤버십이 없습니다(projects: []).
  • stories for-task 및 stories for-goal은 댓글과 시스템 이벤트를 함께 반환합니다. 댓글은 "type": "comment"인 항목입니다. 클라이언트 측에서 필터링하세요.
  • tasks search는 최종적 일관성(eventually-consistent)을 가집니다. 최근 쓰기는 tasks get 또는 tasks for-project로 확인하고 search로 확인하지 마세요.
  • attachments create는 Asana 측에서 multipart이며 이 CLI는 JSON 전용입니다. 액션은 표시되지만 항상 실패합니다. 파일 업로드는 원시 API를 사용하세요.
  • project-briefs create-for-project는 일반 --text를 Rich text should be wrapped in <body> tag.와 함께 거부할 수 있습니다. 그런 경우 --html-text '<body>...</body>'로 재시도하세요.
  • <entity> remove-members --members me (포트폴리오, 프로젝트, 목표, 팀)는 자신의 접근 권한을 취소합니다.

관련 스킬