Jira Cloud Access

Access Jira Cloud (uniquevacation.atlassian.net) via a local helper script with credentials stored in ~/.claude-skills/.env.

Setup

1. Copy .env.example to ~/.claude-skills/.env and fill in JIRA_EMAIL and JIRA_API_TOKEN.
2. Get your API token from https://id.atlassian.com/manage-profile/security/api-tokens.
3. Find your account ID by running:

   .claude/skills/jira/scripts/jira-api GET /rest/api/3/myself

   The accountId field in the response is your JIRA_ACCOUNT_ID.

Helper Script

.claude/skills/jira/scripts/jira-api --help

All examples below use the helper. It reads auth from ~/.claude-skills/.env and targets uniquevacation.atlassian.net.

Common Operations

Search Issues (JQL)

IMPORTANT: Jira Cloud deprecated GET /search. Use POST /search/jql instead.

.claude/skills/jira/scripts/jira-api POST /rest/api/3/search/jql '{
  "jql": "project = GP AND status != Done ORDER BY updated DESC",
  "maxResults": 20,
  "fields": ["summary","status","assignee","priority","issuetype","updated"]
}'

Useful JQL patterns:

• My open issues: assignee = currentUser() AND status != Done
• Sprint issues: project = GP AND sprint in openSprints()
• Recent updates: project = GP AND updated >= -7d ORDER BY updated DESC
• By label: project = GP AND labels = "fraud-detection"
• Unassigned: project = GP AND assignee is EMPTY AND status != Done

Get Issue Details

.claude/skills/jira/scripts/jira-api GET '/rest/api/3/issue/GP-1234?fields=summary,description,status,assignee,priority,issuetype,labels,comment,updated,created'

Create Issue

.claude/skills/jira/scripts/jira-api POST /rest/api/3/issue '{
  "fields": {
    "project": { "key": "GP" },
    "summary": "Issue title here",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Description here" }] }]
    },
    "issuetype": { "name": "Task" }
  }
}'

Issue types: Task, Bug, Story, Epic.

Update Issue

.claude/skills/jira/scripts/jira-api PUT /rest/api/3/issue/GP-1234 '{
  "fields": {
    "summary": "Updated title"
  }
}'

Add Comment

.claude/skills/jira/scripts/jira-api POST /rest/api/3/issue/GP-1234/comment '{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Comment text here" }] }]
  }
}'

Transition Issue (change status)

Two-step: get available transitions, then apply one.

# Step 1: Get transitions
.claude/skills/jira/scripts/jira-api GET /rest/api/3/issue/GP-1234/transitions

# Step 2: Apply transition (use the ID from step 1)
.claude/skills/jira/scripts/jira-api POST /rest/api/3/issue/GP-1234/transitions '{
  "transition": { "id": "31" }
}'

Get Projects

.claude/skills/jira/scripts/jira-api GET '/rest/api/3/project/search?maxResults=50'

Get Board Sprints (Agile API)

.claude/skills/jira/scripts/jira-api GET '/rest/agile/1.0/board/{boardId}/sprint?state=active'

Execution Strategy

1. Always use the helper script — it handles auth from the local .env file.
2. Combine related calls — batch dependent API calls when they depend on each other (e.g., get transitions then transition).
3. Handle pagination — Jira defaults to maxResults=50. Use startAt parameter for pagination.
4. Jira Cloud uses ADF — Description and comment bodies use Atlassian Document Format (the doc / paragraph / text structure shown above), NOT plain strings.

Response Formatting

When presenting Jira data to the user:

• Show ticket key as a link: [GP-1234](https://uniquevacation.atlassian.net/browse/GP-1234)
• Include status, assignee, and priority for search results
• For descriptions, convert ADF to readable text
• Show timestamps in the user's local timezone