Claude-skill-registry jira-git-integration

Generic JIRA + Git workflow utilities for ticket management, branch creation, and integration

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/jira-git-integration" ~/.claude/skills/majiayu000-claude-skill-registry-jira-git-integration && rm -rf "$T"

manifest: skills/data/jira-git-integration/SKILL.md

What I do

I provide JIRA + Git integration utilities that can be used across multiple workflows:

Get JIRA Resources: Detect and retrieve Atlassian cloud ID, visible projects, and accessible resources
Get JIRA User Info: Retrieve current user's account ID for ticket assignment
Create JIRA Tickets: Create new tasks, stories, or bugs in specified JIRA projects
Add JIRA Comments: Add comments to existing JIRA tickets with Markdown formatting
Upload Images to JIRA: Upload local images as JIRA attachments and retrieve attachment URLs
Generate JIRA Branch Names: Create consistent branch names from JIRA tickets
Fetch JIRA Issue Details: Retrieve ticket information including status, assignee, description

When to use me

Use this framework when:

You need JIRA integration in a workflow
You're creating a skill that requires JIRA ticket management
You need to upload images to JIRA tickets
You want to ensure consistent branch naming across JIRA workflows
You need to add comments or attachments to JIRA tickets

This is a framework skill - it provides JIRA utilities that other skills use.

Core Workflow Steps

Step 1: Get Accessible Atlassian Resources

Purpose: Retrieve cloud ID and list of accessible Atlassian resources

Tools Used:

atlassian_getAccessibleAtlassianResources

# Get accessible resources (includes cloud IDs)
atlassian_getAccessibleAtlassianResources

Expected Output:

[
  {
    "id": "23594c42-08ff-4d2a-8065-6756e3590c37",
    "url": "https://company.atlassian.net",
    "name": "company",
    "scopes": ["read:jira-work", "write:jira-work", "read:confluence", "write:confluence"]
  }
]

Extract Cloud ID: Store the

id

field for use in subsequent JIRA operations

Step 2: Get JIRA User Information

Purpose: Retrieve current user's account ID for ticket assignment

Tools Used:

atlassian_atlassianUserInfo

# Get current user info
atlassian_atlassianUserInfo

Expected Output:

{
  "account_id": "712020:1fe13d6b-e3ff-4455-9349-39a1f243e9bb",
  "email": "user@company.com",
  "name": "John Doe",
  "account_status": "active"
}

Extract Account ID: Store the

account_id

field for assigning tickets

Step 3: Get Visible JIRA Projects

Purpose: List all JIRA projects the user has access to

Tools Used:

atlassian_getVisibleJiraProjects

# Get visible projects
atlassian_getVisibleJiraProjects --cloudId <CLOUD_ID>

Expected Output:

{
  "values": [
    {
      "key": "IBIS",
      "name": "Project Name",
      "id": "10205",
      "issueTypes": [
        {
          "name": "Task",
          "id": "10222"
        },
        {
          "name": "Story",
          "id": "10220"
        },
        {
          "name": "Bug",
          "id": "10223"
        }
      ]
    }
  ]
}

Extract Project Key: Store the

key

field (e.g.,

IBIS

) for use in ticket creation

Step 4: Create JIRA Ticket

Purpose: Create a new ticket in specified JIRA project

Tools Used:

atlassian_createJiraIssue

# Create new ticket
atlassian_createJiraIssue \
  --cloudId <CLOUD_ID> \
  --projectKey <PROJECT_KEY> \
  --issueTypeName <ISSUE_TYPE> \
  --summary "<Ticket Title>" \
  --description "<Ticket Description>" \
  --assignee_account_id <USER_ACCOUNT_ID>

Parameters:

```
cloudId
```
: Atlassian cloud ID (from Step 1)
```
projectKey
```
: JIRA project key (e.g.,
```
IBIS
```
)
```
issueTypeName
```
: Issue type name (e.g.,
```
Task
```
,
```
Story
```
,
```
Bug
```
)
```
summary
```
: Short title for the ticket
```
description
```
: Detailed description in Markdown format
```
assignee_account_id
```
: User's account ID (from Step 2, optional)

Description Template:

## Description
<Detailed description of the work>

## Type
<Task | Story | Bug>

## Context
<Additional background information>

## Acceptance Criteria
- [ ] Criteria 1
- [ ] Criteria 2
- [ ] Criteria 3

## Files to Modify
1. `path/to/file1.ts` - Description
2. `path/to/file2.tsx` - Description

## Notes
<Additional notes or constraints>

Expected Output:

{
  "id": "12345",
  "key": "IBIS-101",
  "self": "https://api.atlassian.com/ex/jira/.../issue/12345"
}

Extract Ticket Key: Store the

key

field (e.g.,

IBIS-101

) for reference

Step 5: Add Comment to JIRA Ticket

Purpose: Add a comment to an existing JIRA ticket

Tools Used:

atlassian_addCommentToJiraIssue

# Add comment
atlassian_addCommentToJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY> \
  --commentBody "<Comment Content>"

Parameters:

```
cloudId
```
: Atlassian cloud ID
```
issueIdOrKey
```
: Ticket key (e.g.,
```
IBIS-101
```
)
```
commentBody
```
: Comment content in Markdown format

Comment Templates:

PR Reference Comment:

## Pull Request Created

**PR**: #<PR_NUMBER> - <PR_TITLE>
**URL**: <PR_URL>
**Branch**: <branch-name>

### Changes Summary
<Brief description of changes>

### Files Modified
<list of key files changed>

### Quality Checks
- Linting: ✅ Passed
- Build: ✅ Passed
- Tests: ✅ Passed

### Review Request
@reviewer1 @reviewer2

Implementation Update Comment:

## Implementation Started

Branch: <branch-name>
Status: In Progress

### Next Steps
1. <Step 1>
2. <Step 2>
3. <Step 3>

Image-Embedded Comment:

## Diagrams/Visuals

### Workflow Diagram
![Workflow Diagram](https://company.atlassian.net/secure/attachment/12345/workflow.png)

### Architecture
![System Architecture](https://company.atlassian.net/secure/attachment/12346/architecture.png)

Step 6: Upload Image to JIRA

Purpose: Upload a local image file as a JIRA attachment

Tools Used:

atlassian_addAttachmentToJiraIssue

# Upload image
atlassian_addAttachmentToJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY> \
  --attachment <IMAGE_FILE_PATH>

Parameters:

```
cloudId
```
: Atlassian cloud ID
```
issueIdOrKey
```
: Ticket key (e.g.,
```
IBIS-101
```
)
```
attachment
```
: Path to local image file (e.g.,
```
/tmp/workflow.png
```
)

Expected Output:

{
  "id": "10001",
  "filename": "workflow.png",
  "content": "image/png",
  "size": 12345,
  "self": "https://api.atlassian.com/ex/jira/.../attachment/10001"
  "thumbnail": "https://company.atlassian.net/secure/thumbnail/12345/workflow.png"
}

Extract Attachment URL: The

self

field provides the URL for embedding in comments

Attachment URL Format:

https://company.atlassian.net/secure/attachment/<ATTACHMENT_ID>/<FILENAME>

Usage in Comments:

![Workflow Diagram](https://company.atlassian.net/secure/attachment/10001/workflow.png)

Step 7: Generate JIRA Branch Name

Purpose: Create a consistent branch name from a JIRA ticket key

Branch Naming Conventions:

Format	Example	Use Case
`PROJECT-NUM`	`IBIS-101`	Simple, direct reference
`feature/PROJECT-NUM`	`feature/IBIS-101`	Feature branch pattern
`feature/PROJECT-NUM-description`	`feature/IBIS-101-add-login`	Descriptive feature branch
`bugfix/PROJECT-NUM`	`bugfix/IBIS-102`	Bug fix branch
`hotfix/PROJECT-NUM`	`hotfix/IBIS-103`	Hotfix branch

Implementation:

# Generate branch name from ticket key
TICKET_KEY="IBIS-101"

# Simple format
BRANCH_NAME="${TICKET_KEY}"  # IBIS-101

# Feature format
BRANCH_NAME="feature/${TICKET_KEY}"  # feature/IBIS-101

# Descriptive feature format
BRANCH_NAME="feature/${TICKET_KEY}-add-dark-mode"  # feature/IBIS-101-add-dark-mode

# Create and checkout branch
git checkout -b "${BRANCH_NAME}"

Branch Naming Best Practices:

Use lowercase
Replace spaces with hyphens
Include ticket key for traceability
Keep branch names under 72 characters
Follow git branch naming conventions

Step 8: Get JIRA Issue Details

Purpose: Retrieve detailed information about a JIRA ticket

Tools Used:

atlassian_getJiraIssue

# Get issue details
atlassian_getJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY>

Parameters:

```
cloudId
```
: Atlassian cloud ID
```
issueIdOrKey
```
: Ticket key (e.g.,
```
IBIS-101
```
)

Expected Output:

{
  "key": "IBIS-101",
  "fields": {
    "summary": "Implement new feature",
    "status": {
      "name": "In Progress"
    },
    "assignee": {
      "accountId": "712020:1fe13d6b-e3ff-4455-9349-39a1f243e9bb",
      "displayName": "John Doe"
    },
    "description": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "text": "Detailed description..."
            }
          ]
        }
      ]
    }
    }
  }
}

Extract Information:

Ticket status
Assignee information
Description content
Priority, labels, etc.

Image Handling Strategy

Image Detection Patterns

Search for images in these locations:

# Common image locations
./diagrams/**/*.png
./diagrams/**/*.svg

# Recent images in tmp
/tmp/*.png
/tmp/*.jpg

# Documentation images
./docs/images/**/*.png
./assets/images/**/*.png

# Workflow-related (by filename pattern)
**/*workflow*.png
**/*diagram*.png
**/*flow*.png
**/*architecture*.png
**/*sequence*.png

Image Categorization

# Determine if image needs upload
if [[ "$image_path" =~ ^https?:// ]]; then
  # It's a URL - check if accessible
  if curl -s -o /dev/null -w "%{http_code}" "$image_path" | grep -q "200"; then
    TYPE="accessible_url"
  else
    TYPE="inaccessible_url"
  fi
else
  # It's a file path
  if [[ -f "$image_path" ]]; then
    TYPE="local_file"
  else
    TYPE="not_found"
  fi
fi

Handling Each Image Type

Type	Action
accessible_url	Embed directly in JIRA comment
inaccessible_url	Download and upload as JIRA attachment
local_file	Upload as JIRA attachment
not_found	Warn user and skip

Step 9: Transition JIRA Ticket Status

Purpose: Update JIRA ticket status after PR merge

Tools Used:

atlassian_getTransitionsForJiraIssue

atlassian_transitionJiraIssue

Usage:

# Get available transitions
TRANSITIONS=$(atlassian_getTransitionsForJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY>)

# Find "Done" or "Closed" transition
TARGET_TRANSITION_ID=$(echo "$TRANSITIONS" | jq -r '.transitions[] | select(.to.name == "Done" or .to.name == "Closed") | .id' | head -1)

# Execute transition
atlassian_transitionJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY> \
  --transition '{"id": "<TRANSITION_ID>"}')

When to Use:

PR has been successfully merged
Work is complete and ticket should be closed
Automating workflow to eliminate manual status updates

Integration:

Use with
```
jira-status-updater
```
skill for complete automation
Use with
```
pr-creation-workflow
```
for integrated PR + status updates
Use with
```
git-pr-creator
```
for optional status updates after manual merge

Best Practices

Cloud ID: Always retrieve cloud ID once per session
User Info: Cache user account ID for assignment operations
Project Keys: Use project keys (e.g.,
```
IBIS
```
) consistently
Ticket References: Always use ticket keys (e.g.,
```
IBIS-101
```
) for traceability
Branch Naming: Use consistent branch naming with ticket keys
Image Uploads: Upload local/temporary images, don't link to local paths
Comment Formatting: Use Markdown for rich formatting in JIRA comments
Error Handling: Check for JIRA API errors and provide clear messages
Permissions: Verify user has appropriate permissions for operations

Common Issues

Cloud ID Not Found

Issue: Cannot determine Atlassian cloud ID

Solution:

# Use getAccessibleAtlassianResources to find cloud ID
atlassian_getAccessibleAtlassianResources

Project Not Found

Issue: JIRA project key is invalid or inaccessible

Solution:

# List visible projects to find correct key
atlassian_getVisibleJiraProjects --cloudId <CLOUD_ID>

User Not Assigned

Issue: Ticket not assigned to current user

Solution:

# Get user account ID
atlassian_atlassianUserInfo

# Create ticket with assignee
atlassian_createJiraIssue --assignee_account_id <ACCOUNT_ID>

Image Upload Fails

Issue:

atlassian_addAttachmentToJiraIssue

returns error

Solution:

Verify file path is correct
Check file size limits (JIRA typically limits to 10-100MB)
Ensure you have permission to add attachments
Verify file is not corrupted

Branch Name Conflicts

Issue: Branch with same name already exists

Solution:

# Force create new branch
git checkout -B <branch-name>

# Or switch to existing branch
git checkout <existing-branch>

Troubleshooting Checklist

Before JIRA operations:

After ticket creation:

Ticket number/key is captured
Ticket URL is accessible
Ticket is assigned to correct user
Branch name is generated correctly

After comment/attachment operations:

Comment is added successfully
Images are uploaded to JIRA
Attachment URLs are accessible
Comments display formatting correctly

Related Commands

# Get visible JIRA projects
atlassian_getVisibleJiraProjects --cloudId <CLOUD_ID>

# Get JIRA issue details
atlassian_getJiraIssue --cloudId <CLOUD_ID> --issueIdOrKey <TICKET_KEY>

# Add comment to JIRA issue
atlassian_addCommentToJiraIssue --cloudId <CLOUD_ID> --issueIdOrKey <TICKET_KEY> --commentBody "<markdown>"

# Upload attachment to JIRA
atlassian_addAttachmentToJiraIssue --cloudId <CLOUD_ID> --issueIdOrKey <TICKET_KEY> --attachment <file-path>

# Create JIRA ticket
atlassian_createJiraIssue --cloudId <CLOUD_ID> --projectKey <PROJECT_KEY> --issueTypeName "Task" --summary "Title" --description "<desc>"

# Get user info
atlassian_atlassianUserInfo

# Get accessible resources
atlassian_getAccessibleAtlassianResources

Relevant Skills

Skills that use this JIRA integration framework:

```
git-pr-creator
```
: PR creation with JIRA comments and image uploads
```
jira-git-workflow
```
: JIRA ticket creation and branch management
```
nextjs-pr-workflow
```
: Next.js PR workflow with JIRA integration
```
jira-status-updater
```
: Automated JIRA ticket status transitions after PR merge

Additional related skills:

```
pr-creation-workflow
```
: Generic PR creation workflow
```
ticket-branch-workflow
```
: Ticket-to-branch-to-PLAN workflow