jira-issue

Core CRUD operations for JIRA issues - create, read, update, and delete tickets.

Risk Levels

| Operation | Risk | Notes | |-----------|------|-------| | Get/view issue | - | Read-only | | Create issue | - | Easily reversible (can delete) | | Update fields | ! | Can be undone via edit | | Delete issue | !!! | PERMANENT — JIRA Cloud has no issue trash; a confirmation prompt is required | | Delete with --force | !!! | PERMANENT, and skips the confirmation prompt |

Risk Legend: - Safe, read-only | ! Caution, modifiable | !! Warning, destructive but recoverable | !!! Danger, irreversible

⚠️ PRIMARY USE CASE: Viewing Issue Details

This skill MUST be invoked when the user wants to see issue information.

CRITICAL: When user asks to view/show/get/see issue details, you MUST:

Load this skill immediately (if not already loaded)
Use the jira-as issue get command to retrieve the issue
Display the full issue information to the user

Common phrases that REQUIRE invoking this skill:

"Show me [the issue/bug/task]" → Use jira-as issue get
"Get details of [issue]" → Use jira-as issue get
"View [the issue we created]" → Use jira-as issue get
"What's in [issue key]?" → Use jira-as issue get
"Display issue information" → Use jira-as issue get
"Look up [issue]" → Use jira-as issue get
"See [the bug]" → Use jira-as issue get
"Details of the bug/task/issue" → Use jira-as issue get

When to Use This Skill

Triggers: User asks to...

View/show/display/get/retrieve/see/check issue details ← Most common use case
Create a new JIRA issue (bug, task, story, epic)
Look up or examine an issue
Update issue fields (summary, description, priority, assignee, labels)
Delete an issue

Context awareness: If the user refers to "the issue/bug/task we just created" or uses pronouns like "it", resolve to the most recently created/mentioned issue in the conversation and retrieve its details.

Available Commands

This skill provides the following commands via the jira-as issue CLI:

jira-as issue create: Create new issues
jira-as issue get: Retrieve issue details
jira-as issue update: Modify issue fields
jira-as issue delete: Remove issues
jira-as issue transition: Transition an issue to a new status (alias for jira-as lifecycle transition)
jira-as issue transitions: List available transitions, read-only (alias for jira-as lifecycle transitions)
jira-as issue comment: Add a comment to an issue (alias for jira-as collaborate comment add)

All commands support --help for full option documentation.

Output Options

-o, --output [text|json] is available on issue get, issue create, and issue transitions. Other issue commands print plain-text output.

Templates

Pre-configured templates for common issue types:

bug_template.json - Bug report template
task_template.json - Task template
story_template.json - User story template

Use the --template option to apply a template during issue creation:

# Quick bug report using template
jira-as issue create --project PROJ --template bug --summary "Login page error"

# Quick task using template
jira-as issue create --project PROJ --template task --summary "Update documentation"

# Quick story using template
jira-as issue create --project PROJ --template story --summary "User can reset password"

Common Patterns

Create Issues

# Basic issue creation
jira-as issue create --project PROJ --type Bug --summary "Login fails on mobile"

# With description
jira-as issue create --project PROJ --type Bug --summary "Login fails on mobile" \
  --description "Users report 500 error when logging in from mobile browsers. See attached screenshot."

# With assignee (use 'self' for current user)
jira-as issue create --project PROJ --type Task --summary "Review PR #42" \
  --assignee self

# With agile fields
jira-as issue create --project PROJ --type Story --summary "User login" \
  --epic PROJ-100 --story-points 5

# With relationships and time estimate
jira-as issue create --project PROJ --type Task --summary "Setup database" \
  --blocks PROJ-123 --estimate "2d"

# With 'relates to' links
jira-as issue create --project PROJ --type Task --summary "Related feature" \
  --relates-to PROJ-456,PROJ-789

# With labels and components
jira-as issue create --project PROJ --type Task --summary "Setup CI pipeline" \
  --labels "backend,infrastructure" --components "Build,DevOps"

# With custom fields (JSON format)
jira-as issue create --project PROJ --type Bug --summary "Critical bug" \
  --custom-fields '{"customfield_10050": "production"}'

# Assign to sprint
jira-as issue create --project PROJ --type Story --summary "Feature X" \
  --sprint 42

# Create as a child of an epic or parent task
jira-as issue create --project PROJ --type Task --summary "Child task" \
  --parent PROJ-100

# For workflows that reject a parent at create time: create without the
# parent, then set it in a follow-up update
jira-as issue create --project PROJ --type Task --summary "Child task" \
  --parent PROJ-100 --parent-via-update

# Preview the payload that would be sent without creating the issue
jira-as issue create --project PROJ --type Bug --summary "Bug" --dry-run

# Create without project context defaults
jira-as issue create --project PROJ --type Bug --summary "Bug" --no-defaults

Retrieve Issues

# Basic retrieval
jira-as issue get PROJ-123

# With full details
jira-as issue get PROJ-123 --detailed --show-links --show-time

# Retrieve specific fields only
jira-as issue get PROJ-123 --fields "summary,status,priority,assignee"

# JSON output for scripting
jira-as issue get PROJ-123 --output json

Note: Using --show-links or --show-time automatically enables detailed view.

Update Issues

# Update priority and assignee
jira-as issue update PROJ-123 --priority Critical --assignee self

# Update description
jira-as issue update PROJ-123 --description "Updated description with **markdown** support"

# Update without notifications
jira-as issue update PROJ-123 --summary "Updated title" --no-notify

# Unassign issue (accepts "none" or "unassigned")
jira-as issue update PROJ-123 --assignee none

# Update labels and components (replaces existing)
jira-as issue update PROJ-123 --labels "urgent,reviewed" --components "API"

# Move issue under a new parent (epic or parent task)
jira-as issue update PROJ-123 --parent PROJ-100

# Remove the parent
jira-as issue update PROJ-123 --parent none

# Update custom fields
jira-as issue update PROJ-123 --custom-fields '{"customfield_10050": "staging"}'

Assignee special values:

self: Assigns to the current authenticated user
none or unassigned: Removes the assignee

Notification suppression (--no-notify): Suppressing watcher notifications requires the "Administer Jira" global permission. For non-admin users JIRA rejects the whole request with a 403, so the CLI automatically retries without suppression: the update still lands, watchers are notified, and a warning is printed on stderr.

Rich-Text Custom Fields (ADF)

JIRA Cloud stores rich text as Atlassian Document Format (ADF). The CLI automatically wraps plain-string values for the built-in rich-text fields (description, environment) in ADF, converting markdown so formatting survives. If your instance has rich-text custom fields, list their IDs in the JIRA_ADF_CUSTOM_FIELDS environment variable (comma-separated) and their values are auto-wrapped too, on both create and update:

export JIRA_ADF_CUSTOM_FIELDS="customfield_10050,customfield_10051"

jira-as issue update PROJ-123 \
  --custom-fields '{"customfield_10050": "Deployed to **staging**"}'

Values that are already ADF documents pass through untouched.

Transition and Comment Aliases

For convenience, common lifecycle and collaboration operations are aliased under issue, with the same options as the underlying commands:

# List available transitions (alias for `jira-as lifecycle transitions`)
jira-as issue transitions PROJ-123
jira-as issue transitions PROJ-123 --output json

# Transition to a new status (alias for `jira-as lifecycle transition`)
jira-as issue transition PROJ-123 --to "In Progress"
jira-as issue transition PROJ-123 --to Done --resolution Fixed
jira-as issue transition PROJ-123 --id 31 --dry-run

# Add a comment (alias for `jira-as collaborate comment add`)
jira-as issue comment PROJ-123 --body "Starting work"
jira-as issue comment PROJ-123 --body "**Done**" --format markdown

This supports the common create → work → transition → comment flow without switching command groups. For advanced workflow and comment operations (editing/deleting comments, attachments, versions, components), use the full jira-as lifecycle and jira-as collaborate groups.

Delete Issues

# Delete with confirmation
jira-as issue delete PROJ-456

# Force delete (skips confirmation prompt; deletion is PERMANENT)
jira-as issue delete PROJ-456 --force

Example Workflows

Create and View Issue

This is the most common workflow - create an issue, then immediately view its details:

# 1. Create a bug
jira-as issue create --project DEMO --type Bug --summary "Login fails on mobile" --priority High

# Output: Created DEMO-105

# 2. View the details of the bug we just created
jira-as issue get DEMO-105

# Output shows:
# - Issue Key: DEMO-105
# - Type: Bug
# - Summary: Login fails on mobile
# - Priority: High
# - Status: Open (or whatever the initial status is)
# - And all other fields

When user says "Show me the details of the bug we just created", this skill should:

Identify the most recently created issue from context (e.g., DEMO-105)
Execute: jira-as issue get DEMO-105
Display the full issue details including key, type, summary, priority, status, etc.

Shell Completion

To enable shell completion for the jira-as CLI, add the appropriate command to your shell's configuration file (e.g., .bashrc, .zshrc, config.fish).

Bash:

eval "$(_JIRA_AS_COMPLETE=bash_source jira-as)"

Zsh:

eval "$(_JIRA_AS_COMPLETE=zsh_source jira-as)"

Fish:

_JIRA_AS_COMPLETE=fish_source jira-as | source

Exit Codes

| Code | Description | |------|-------------| | 0 | Success | | 1 | Error (see error message) |

Troubleshooting

| Error | Cause | Solution | |-------|-------|----------| | 401 Unauthorized | Invalid credentials | Verify JIRA_API_TOKEN and JIRA_EMAIL | | 403 Forbidden | No permission | Check project permissions with JIRA admin | | 404 Not Found | Issue doesn't exist | Verify issue key format (PROJ-123) | | Invalid issue type | Type not in project | Check available types for target project | | Epic/Sprint errors | Agile fields misconfigured | Verify settings.json agile field IDs |

For credential setup, generate tokens at: https://id.atlassian.com/manage-profile/security/api-tokens

Configuration

Requires JIRA credentials via environment variables (JIRA_SITE_URL, JIRA_EMAIL, JIRA_API_TOKEN).

Agile Field IDs (story points, sprint, epic link)

Custom field IDs for Agile fields often differ per instance — and per project. The --story-points, --sprint, and --epic options resolve their field IDs in priority order (highest first):

Per-project overrides in settings: jira.projects.<KEY>.agile_fields
Global settings block: jira.agile_fields
Environment variables (JIRA_STORY_POINTS_FIELD, JIRA_SPRINT_FIELD, JIRA_EPIC_LINK_FIELD)
Built-in defaults

Example settings entry with a per-project story points override:

{
  "jira": {
    "agile_fields": {
      "story_points": "customfield_10016"
    },
    "projects": {
      "MYAPP": {
        "agile_fields": {
          "story_points": "customfield_10116",
          "sprint": "customfield_10120"
        }
      }
    }
  }
}

Related Resources

Resources in the skill directory (skills/jira-issue/):

docs/BEST_PRACTICES.md - Issue content and metadata guidance
references/field_formats.md - ADF and field format details
references/api_reference.md - REST API endpoints

Related Skills

jira-lifecycle: Workflow transitions and status changes
jira-search: JQL queries for finding issues
jira-collaborate: Comments, attachments, watchers
jira-agile: Sprint and epic management
jira-relationships: Issue linking and dependencies
jira-time: Time tracking and worklogs