Agent skill

jira

Jira Cloud REST API via curl. Use this skill to create, update, search, and manage issues, projects, and workflows in Jira.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/jira-neversight-skills-feed

SKILL.md

Jira API

Use the Jira Cloud REST API via direct curl calls to manage issues, projects, and workflows.

Official docs: https://developer.atlassian.com/cloud/jira/platform/rest/v3/

When to Use

Use this skill when you need to:

  • Create issues in Jira projects
  • Search issues using JQL (Jira Query Language)
  • Update issues (status, assignee, priority, etc.)
  • Get issue details and comments
  • List projects and their metadata
  • Transition issues through workflow states
  • Add comments to issues

Prerequisites

  1. Go to Atlassian Account Settings
  2. Click Create API token
  3. Copy the generated token (you won't see it again)
bash
export JIRA_DOMAIN="mycompany" # e.g., "mycompany" or "mycompany.atlassian.net"
export JIRA_EMAIL="[email protected]" # Your Atlassian account email
export JIRA_API_TOKEN="your-api-token" # API token from step 2

Rate Limits

Jira Cloud has rate limits that vary by endpoint. For most REST API calls, expect limits around 100-500 requests per minute.

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.field'

How to Use

All examples below assume JIRA_DOMAIN, JIRA_EMAIL, and JIRA_API_TOKEN are set.

Base URL: https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3

Note: ${JIRA_DOMAIN%.atlassian.net} strips the suffix if present, so both mycompany and mycompany.atlassian.net work.

1. Get Current User

Verify your authentication:

bash
bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/myself" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"'

2. List Projects

Get all projects you have access to:

bash
bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/project" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"'

3. Get Project Details

Get details for a specific project:

bash
PROJECT_KEY="PROJ"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/project/${PROJECT_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"'

4. Get Issue Types for Project

List available issue types (Task, Bug, Story, etc.):

bash
PROJECT_KEY="PROJ"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/project/${PROJECT_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"'

5. Search Issues with JQL

Search issues using Jira Query Language:

Write to /tmp/jira_request.json:

json
{
  "jql": "project = PROJ AND status NOT IN (Done) ORDER BY created DESC",
  "maxResults": 10,
  "fields": ["key", "summary", "status", "assignee", "priority"]
}

Then run:

bash
bash -c 'curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/search/jql" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json' | jq '.issues[] | {key, summary: .fields.summary, status: .fields.status.name, assignee: .fields.assignee.displayName, priority: .fields.priority.name}''

Common JQL examples:

  • project = PROJ - Issues in project
  • assignee = currentUser() - Your issues
  • status = "In Progress" - By status
  • status NOT IN (Done, Closed) - Exclude statuses
  • created >= -7d - Created in last 7 days
  • labels = bug - By label
  • priority = High - By priority

6. Get Issue Details

Get full details of an issue:

bash
ISSUE_KEY="PROJ-123"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"'

7. Create Issue

Create a new issue (API v3 uses Atlassian Document Format for description):

Write to /tmp/jira_request.json:

json
{
  "fields": {
    "project": {"key": "PROJ"},
    "summary": "Bug: Login button not responding",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "The login button on the mobile app is not responding when tapped."}
          ]
        }
      ]
    },
    "issuetype": {"name": "Bug"}
  }
}

Then run:

bash
bash -c 'curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json'

8. Create Issue with Priority and Labels

Create issue with additional fields:

Write to /tmp/jira_request.json:

json
{
  "fields": {
    "project": {"key": "PROJ"},
    "summary": "Implement user authentication",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "Add OAuth2 authentication flow for the mobile app."}
          ]
        }
      ]
    },
    "issuetype": {"name": "Story"},
    "priority": {"name": "High"},
    "labels": ["backend", "security"]
  }
}

Then run:

bash
bash -c 'curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json'

9. Update Issue

Update an existing issue:

bash
ISSUE_KEY="PROJ-123"

Write to /tmp/jira_request.json:

json
{
  "fields": {
    "summary": "Updated: Login button not responding on iOS",
    "priority": {"name": "Highest"},
    "labels": ["bug", "ios", "urgent"]
  }
}

Then run:

bash
bash -c 'curl -s -X PUT "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json'

Returns 204 No Content on success.

10. Get Available Transitions

Get possible status transitions for an issue:

bash
ISSUE_KEY="PROJ-123"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/transitions" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"'

11. Transition Issue (Change Status)

Move issue to a different status:

bash
ISSUE_KEY="PROJ-123"
TRANSITION_ID="31" # Get from transitions endpoint

Write to /tmp/jira_request.json:

json
{
  "transition": {
    "id": "<your-transition-id>"
  }
}

Then run:

bash
bash -c 'curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/transitions" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json'

Returns 204 No Content on success.

12. Add Comment

Add a comment to an issue:

bash
ISSUE_KEY="PROJ-123"

Write to /tmp/jira_request.json:

json
{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "text": "Investigated and found the root cause. Working on a fix."}
        ]
      }
    ]
  }
}

Then run:

bash
bash -c 'curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/comment" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json'

13. Get Issue Comments

List all comments on an issue:

bash
ISSUE_KEY="PROJ-123"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/comment" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"'

14. Assign Issue

Assign an issue to a user:

bash
ISSUE_KEY="PROJ-123"
ACCOUNT_ID="5b10ac8d82e05b22cc7d4ef5" # Get from /rest/api/3/user/search

Write to /tmp/jira_request.json:

json
{
  "accountId": "<your-account-id>"
}

Then run:

bash
bash -c 'curl -s -X PUT "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/assignee" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json'

15. Search Users

Find users by email or name:

Write to /tmp/jira_search.txt:

john
bash
bash -c 'curl -s -G "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/user/search" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --data-urlencode "query@/tmp/jira_search.txt"'

16. Delete Issue

Delete an issue (use with caution):

bash
ISSUE_KEY="PROJ-123"

bash -c 'curl -s -X DELETE "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}"'

Returns 204 No Content on success.

Atlassian Document Format (ADF)

Jira API v3 uses ADF for rich text fields like description and comment.body. Basic structure:

json
{
  "type": "doc",
  "version": 1,
  "content": [
  {
  "type": "paragraph",
  "content": [
  {"type": "text", "text": "Plain text"},
  {"type": "text", "text": "Bold text", "marks": [{"type": "strong"}]},
  {"type": "text", "text": "Code", "marks": [{"type": "code"}]}
  ]
  },
  {
  "type": "bulletList",
  "content": [
  {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Item 1"}]}]},
  {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Item 2"}]}]}
  ]
  },
  {
  "type": "codeBlock",
  "attrs": {"language": "python"},
  "content": [{"type": "text", "text": "print('hello')"}]
  }
  ]
}

Guidelines

  1. Use JQL for complex queries: JQL is powerful for filtering issues by any field combination
  2. Check transitions first: Before changing status, get available transitions for the issue
  3. Handle pagination: Use startAt and maxResults for large result sets
  4. Use account IDs: Jira Cloud uses account IDs (not usernames) for user references
  5. ADF for rich text: API v3 requires Atlassian Document Format for description and comments
  6. Rate limiting: Implement exponential backoff if you receive 429 responses

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results