How do I install the Jira Workflow Transitions skill?

Run npx skillmds@latest add yebot/jira-workflow-transitions in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Jira Workflow Transitions skill do?

Jira Workflow Transitions Skill It is listed under Productivity on SkillMD.

Is Jira Workflow Transitions safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Jira Workflow Transitions?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Jira Workflow Transitions free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Jira Workflow Transitions?

yebot (@yebot) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Jira Workflow Transitions by yebot — Agent Skill

Name: Jira Workflow Transitions
Author: yebot

Jira Workflow Transitions Skill

Understanding and navigating Jira workflow states and transitions using jira-cli.

Overview

Jira workflows define how issues move through different states from creation to completion. This skill helps you understand workflow concepts and effectively transition issues using jira-cli.

Workflow Fundamentals

What is a Workflow?

A workflow is a set of statuses and transitions that an issue moves through during its lifecycle.

Status: Current state of an issue (e.g., "To Do", "In Progress", "Done")

Transition: Action that moves an issue from one status to another (e.g., "Start Progress", "Resolve")

Common Workflow Types

1. Basic Workflow

To Do → In Progress → Done

2. Scrum Workflow

Backlog → To Do → In Progress → In Review → Done → Closed

3. Complex Workflow

Open → In Progress → In Review → Testing → Blocked
                                         ↓
                                        Done → Closed

Standard Workflow States

Initial States

Backlog

Issues that might be worked on in future
Not yet committed to a sprint
May need grooming

To Do

Ready to be worked on
Accepted into sprint or ready for picking up
All requirements clear

Open

Newly created issue
Needs triage or assignment
May need more information

Active Work States

In Progress

Actively being worked on
Assigned to someone
Development underway

In Review

Code/work completed
Awaiting peer review or approval
Pull request open

Testing / QA

Under quality assurance testing
Verification of acceptance criteria
May be on staging environment

Blocked States

Blocked

Cannot proceed
Waiting on external dependency
Requires resolution of blocker

Waiting for Info

Need clarification or additional details
Awaiting stakeholder input
Cannot proceed without information

Completion States

Done

Work completed
Accepted by product owner
Meets Definition of Done

Closed

Fully resolved and closed
No further action needed
Archived state

Resolved

Issue addressed
May need verification
Intermediate completion state

Rejection States

Won't Fix

Decision not to address
Out of scope
Not a priority

Duplicate

Same as another issue
Linked to original issue
Closed as duplicate

Cannot Reproduce

Bug cannot be reproduced
Insufficient information
May reopen if new info emerges

Transitioning Issues

Basic Transition

jira issue move PROJ-123

This opens an interactive menu showing available transitions.

Direct Transition

jira issue move PROJ-123 "In Progress"

Moves directly to specified state if transition is available.

Transition with Comment

jira issue move PROJ-123 "Done" --comment "Completed feature implementation. Ready for deployment."

Always add comments to provide context about the transition.

Checking Available Transitions

jira issue view PROJ-123 --plain

Shows current status and available next states.

Common Transition Patterns

Starting Work

From To Do to In Progress:

# 1. Assign to yourself
jira issue assign PROJ-123 @me

# 2. Move to In Progress
jira issue move PROJ-123 "In Progress" --comment "Starting work on authentication feature"

Submitting for Review

From In Progress to In Review:

jira issue move PROJ-123 "In Review" --comment "PR created: https://github.com/company/repo/pull/456"

Handling Review Feedback

From In Review back to In Progress:

jira issue move PROJ-123 "In Progress" --comment "Addressing review feedback: refactoring auth logic"

Completing Work

From In Review to Done:

jira issue move PROJ-123 "Done" --comment "PR merged. All acceptance criteria met."

Handling Blockers

From In Progress to Blocked:

jira issue move PROJ-123 "Blocked" --comment "Waiting for API spec from backend team"
jira issue link PROJ-123 PROJ-100 "is blocked by"

From Blocked back to In Progress:

jira issue move PROJ-123 "In Progress" --comment "Blocker resolved. Resuming work."

Closing Issues

From Done to Closed:

jira issue move PROJ-123 "Closed" --comment "Verified in production. No issues reported."

Rejecting Issues

Won't Fix:

jira issue move PROJ-123 "Closed" --resolution "Won't Fix" --comment "Decision: Out of scope for current roadmap"

Duplicate:

jira issue link PROJ-123 PROJ-100 "duplicates"
jira issue move PROJ-123 "Closed" --resolution "Duplicate" --comment "Duplicate of PROJ-100"

Cannot Reproduce:

jira issue move PROJ-123 "Closed" --resolution "Cannot Reproduce" --comment "Unable to reproduce. Please reopen with more details if issue persists."

Workflow Best Practices

1. Always Add Comments

❌ Bad:

jira issue move PROJ-123 "In Progress"

✅ Good:

jira issue move PROJ-123 "In Progress" --comment "Starting with database schema design"

2. Update Before Transitioning

# Update fields first
jira issue edit PROJ-123 --priority High
jira issue assign PROJ-123 @me

# Then transition
jira issue move PROJ-123 "In Progress"

3. Link Related Work

# When moving to review, link PR
jira issue move PROJ-123 "In Review" --comment "PR: https://github.com/company/repo/pull/456"

# When blocking, link blocker
jira issue move PROJ-123 "Blocked"
jira issue link PROJ-123 PROJ-100 "is blocked by"

4. Don't Skip States

❌ Bad (skipping review):

jira issue move PROJ-123 "Done"  # Directly from In Progress

✅ Good (following workflow):

jira issue move PROJ-123 "In Review"  # From In Progress
# ... review happens ...
jira issue move PROJ-123 "Done"       # From In Review

5. Verify Before Completion

Before moving to Done:

# Review issue details
jira issue view PROJ-123 --plain

# Check acceptance criteria met
# Verify tests passing
# Confirm deployment successful

# Then complete
jira issue move PROJ-123 "Done" --comment "All acceptance criteria met. Deployed to production."

Workflow States by Issue Type

Bug Workflow

Open → In Progress → In Review → Testing → Fixed → Closed
                              ↓
                            Cannot Reproduce
                            Won't Fix

Key transitions:

# Start fix
jira issue move BUG-123 "In Progress" --comment "Investigating root cause"

# Submit fix
jira issue move BUG-123 "In Review" --comment "Fix PR: ..."

# After QA
jira issue move BUG-123 "Fixed" --comment "Verified on staging"

# After deployment
jira issue move BUG-123 "Closed" --comment "Fix deployed to production"

Story Workflow

Backlog → To Do → In Progress → In Review → Done → Closed

Key transitions:

# Sprint planning
jira issue move STORY-123 "To Do" --comment "Added to Sprint 42"

# Start development
jira issue move STORY-123 "In Progress"

# Code review
jira issue move STORY-123 "In Review" --comment "PR: ..."

# Accept story
jira issue move STORY-123 "Done" --comment "Demo approved by PO"

Task Workflow

To Do → In Progress → Done

Key transitions:

# Simple workflow
jira issue move TASK-123 "In Progress"
# ... work ...
jira issue move TASK-123 "Done"

Epic Workflow

To Do → In Progress → Done → Closed

Epics transition when child stories complete:

# Start epic when first story starts
jira issue move EPIC-100 "In Progress"

# Complete epic when all stories done
jira issue move EPIC-100 "Done" --comment "All stories completed. Feature fully implemented."

Handling Special Cases

Reopening Issues

Reopen a closed issue:

jira issue move PROJ-123 "Reopened" --comment "Bug has reoccurred. New reproduction steps: ..."

Or back to original state:

jira issue move PROJ-123 "In Progress" --comment "Reopening to address regression"

Moving Between Sprints

# Issue incomplete at sprint end
jira issue move PROJ-123 "To Do" --comment "Moving to Sprint 43 due to blocker"
jira sprint add <NEXT_SPRINT_ID> PROJ-123

Escalating Priority

# Change priority
jira issue edit PROJ-123 --priority Critical

# Add urgency label
jira issue edit PROJ-123 --label urgent

# Move up in workflow if needed
jira issue move PROJ-123 "In Progress" --comment "Escalated to critical. Addressing immediately."

Split Issues

When an issue is too large:

# Create new issues
jira issue create --type Story --summary "Part 1: ..." --parent PROJ-123
jira issue create --type Story --summary "Part 2: ..." --parent PROJ-123

# Close original or mark as epic
jira issue edit PROJ-123 --type Epic

Workflow Automation

Git Integration

Pre-commit hook:

#!/bin/bash
# Ensure commits reference Jira issue
if ! git log -1 --pretty=%B | grep -qE "PROJ-[0-9]+"; then
  echo "ERROR: Commit must reference Jira issue"
  exit 1
fi

Post-merge hook:

#!/bin/bash
# Auto-transition after merge
ISSUE_KEY=$(git log -1 --pretty=%B | grep -oE "PROJ-[0-9]+")
if [ -n "$ISSUE_KEY" ]; then
  jira issue move "$ISSUE_KEY" "Testing" --comment "Merged to main. Ready for QA."
fi

CI/CD Integration

On deployment:

#!/bin/bash
# Extract issue keys from commits since last deploy
ISSUES=$(git log --pretty=%B $LAST_TAG..HEAD | grep -oE "PROJ-[0-9]+" | sort -u)

# Transition each issue
for issue in $ISSUES; do
  jira issue move "$issue" "Testing" --comment "Deployed to staging by CI/CD pipeline"
done

Scheduled Status Updates

Daily reminder script:

#!/bin/bash
# Find stale "In Progress" issues
jira issue list --jql "\
  status = 'In Progress' AND \
  updated <= -3d AND \
  assignee = currentUser() \
" --plain

echo "Reminder: Update status on above issues"

Troubleshooting Transitions

Issue Won't Transition

Problem: Transition not available

Solutions:

Check current status
```
jira issue view PROJ-123 --plain
```

View available transitions

jira issue move PROJ-123  # Interactive mode shows options

Check required fields
- Some transitions require fields to be filled
- Use interactive mode to see requirements
Verify permissions
- You may not have permission for certain transitions
- Contact Jira admin if needed

Missing Transition

Problem: Expected transition not showing

Possible causes:

Workflow doesn't include that transition
Conditional transition based on field values
Permission restrictions
Issue type has different workflow

Solution:

# Check what transitions are available
jira issue move PROJ-123

# Ask admin about workflow configuration

Stuck in Status

Problem: Issue stuck in a status

Solutions:

Check for blockers
```
jira issue view PROJ-123 --plain
```

Add comment explaining situation

jira issue comment PROJ-123 "Stuck waiting for X. Escalating to Y."

Link blocking issues

jira issue link PROJ-123 PROJ-100 "is blocked by"

Move to Blocked status

jira issue move PROJ-123 "Blocked" --comment "Cannot proceed due to X"

Accidental Transition

Problem: Moved to wrong status

Solution:

# Move back to correct status
jira issue move PROJ-123 "In Progress" --comment "Moved back to In Progress. Was accidentally marked as Done."

Workflow Metrics

Cycle Time

Time from "In Progress" to "Done":

# Issues completed this week
jira issue list --jql "\
  status = Done AND \
  resolved >= startOfWeek() \
" --raw

Calculate: resolved_date - in_progress_date

Lead Time

Time from "To Do" to "Done":

# All resolved issues
jira issue list --jql "resolved >= startOfMonth()" --raw

Calculate: resolved_date - created_date

Status Distribution

# Count issues by status
jira issue list --status "In Progress" --raw | grep -c key
jira issue list --status "In Review" --raw | grep -c key
jira issue list --status "Done" --raw | grep -c key

Blocked Issue Tracking

# Currently blocked
jira issue list --status Blocked --plain

# How long blocked
jira issue list --jql "status = Blocked" --raw

Custom Workflows

Organizations often customize workflows. To understand your workflow:

View current issue state:
```
jira issue view PROJ-123 --plain
```

See available transitions:

jira issue move PROJ-123  # Interactive mode

Check workflow diagram:
- Ask Jira admin for workflow documentation
- Or view in Jira UI: Project Settings → Workflows
Document for team: Create a workflow guide specific to your project

When to Use This Skill

Learning Jira workflow concepts
Transitioning issues appropriately
Handling blocked or stuck issues
Integrating workflows with git/CI/CD
Troubleshooting transition issues
Understanding team's specific workflow

Best Practices Summary

Always add meaningful comments when transitioning
Follow the workflow - don't skip states
Update issue details before transitioning
Link related work (PRs, blockers, etc.)
Use appropriate transitions for issue type
Verify completion before marking Done
Handle blockers explicitly - don't leave hanging
Document custom workflows for team reference

Next Steps

Document your team's specific workflows
Create scripts for common transition patterns
Set up automation for workflow events
Define clear Definition of Done for each state
Establish team norms around transitions

Jira Workflow Transitions

File contents

Jira Workflow Transitions Skill

Overview

Workflow Fundamentals

What is a Workflow?

Common Workflow Types

Standard Workflow States

Initial States

Active Work States

Blocked States

Completion States

Rejection States

Transitioning Issues

Basic Transition

Direct Transition

Transition with Comment

Checking Available Transitions

Common Transition Patterns

Starting Work

Submitting for Review

Handling Review Feedback

Completing Work

Handling Blockers

Closing Issues

Rejecting Issues

Workflow Best Practices

1. Always Add Comments

2. Update Before Transitioning

3. Link Related Work

4. Don't Skip States

5. Verify Before Completion

Workflow States by Issue Type

Bug Workflow

Story Workflow

Task Workflow

Epic Workflow

Handling Special Cases

Reopening Issues

Moving Between Sprints

Escalating Priority

Split Issues

Workflow Automation

Git Integration

CI/CD Integration

Scheduled Status Updates

Troubleshooting Transitions

Issue Won't Transition

Missing Transition

Stuck in Status

Accidental Transition

Workflow Metrics

Cycle Time

Lead Time

Status Distribution

Blocked Issue Tracking

Custom Workflows

When to Use This Skill

Best Practices Summary

Next Steps

Related skills

Frequently asked questions

How do I install the Jira Workflow Transitions skill?

What does the Jira Workflow Transitions skill do?

Is Jira Workflow Transitions safe to use?

Which AI agents work with Jira Workflow Transitions?

Is Jira Workflow Transitions free to use?

Who published Jira Workflow Transitions?