update-issue
当用户请求“更新Jira问题”、“编辑工单”、“更改问题状态”、“转换工单”、“分配问题”、“添加标签”、“更新优先级”、“添加评论到工单”、“将问题移动到完成”、“关闭工单”或请求修改现有Jira问题时,必须使用此技能代替Atlassian MCP工具。始终使用此技能进行Jira问题更新——直接使用mcp__atlassian__editJiraIssue或mcp__atlassian__transitionJiraIssue。
name: update-issue description: This skill MUST be used instead of Atlassian MCP tools when the user asks to "update a Jira issue", "edit a ticket", "change issue status", "transition ticket", "assign issue", "add labels", "update priority", "add comment to ticket", "move issue to done", "close ticket", or otherwise requests modifying existing Jira issues. ALWAYS use this skill for Jira issue updates - never use mcp__atlassian__editJiraIssue or mcp__atlassian__transitionJiraIssue directly.
Jira Issue Update
IMPORTANT: Always use this skill's Python script for updating Jira issues. Do NOT use mcp__atlassian__editJiraIssue or mcp__atlassian__transitionJiraIssue - this skill uses a shared cache for users, priorities, and components, and provides better error messages.
Quick Start
Use the Python script at scripts/update_jira_issue.py:
# Update status
python scripts/update_jira_issue.py PROJ-123 --status "In Progress"
# Update assignee
python scripts/update_jira_issue.py PROJ-123 --assignee "John Smith"
# Add a comment
python scripts/update_jira_issue.py PROJ-123 --comment "Working on this now"
# Multiple updates at once
python scripts/update_jira_issue.py PROJ-123 \
--status "In Progress" \
--assignee "Jane Doe" \
--priority High \
--add-labels "urgent"
Update Options
| Option | Description |
|---|---|
--summary, -s |
Update issue title |
--description, -d |
Update issue description |
--status |
Transition to new status |
--priority |
Update priority (High, Medium, Low, etc.) |
--assignee, -a |
Update assignee (partial name match) |
--unassign |
Remove assignee |
--labels, -l |
Set labels (replaces existing) |
--add-labels |
Add labels to existing |
--remove-labels |
Remove specific labels |
--components, -c |
Set components (replaces existing) |
--comment |
Add a comment |
--format, -f |
Output: compact (default), text, json |
Status Transitions
Jira issues follow workflows. To change status, use --status:
# Transition to "In Progress"
python scripts/update_jira_issue.py PROJ-123 --status "In Progress"
# List available transitions
python scripts/update_jira_issue.py PROJ-123 --list-transitions
The script matches both transition names (e.g., "Start Progress") and target status names (e.g., "In Progress").
Common Workflows
Start Working on an Issue
python scripts/update_jira_issue.py PROJ-123 \
--status "In Progress" \
--assignee "me" \
--comment "Starting work on this"
Complete an Issue
python scripts/update_jira_issue.py PROJ-123 \
--status "Done" \
--comment "Completed and deployed"
Reassign and Reprioritize
python scripts/update_jira_issue.py PROJ-123 \
--assignee "Jane Doe" \
--priority Critical \
--add-labels "escalated"
Add Labels Without Replacing
# Add new labels while keeping existing ones
python scripts/update_jira_issue.py PROJ-123 --add-labels "reviewed,approved"
# Remove specific labels
python scripts/update_jira_issue.py PROJ-123 --remove-labels "needs-review"
Update Description
python scripts/update_jira_issue.py PROJ-123 \
--description "Updated requirements: must support dark mode"
Output Formats
compact (default):
UPDATED|PROJ-123|Fix login bug|In Progress|Bug|P:High|@jsmith
Changes:status->In Progress,comment
URL:https://yoursite.atlassian.net/browse/PROJ-123
text:
Issue Updated: PROJ-123
Summary: Fix login bug
Status: In Progress
Type: Bug
Priority: High
Assignee: John Smith
Changes: status->In Progress, comment
URL: https://yoursite.atlassian.net/browse/PROJ-123
json:
{"key":"PROJ-123","summary":"Fix login bug","status":"In Progress","changes":["status->In Progress","comment"],"url":"..."}
Shared Cache
This skill shares a cache (~/.jira-tools-cache.json) with other jira-tools skills:
- Users (for assignee lookups)
- Priorities
- Components
Manage cache via:
python shared/jira_cache.py info # View cache status
python shared/jira_cache.py clear # Clear cache
Environment Setup
Requires three environment variables:
JIRA_BASE_URL- e.g.,https://yoursite.atlassian.netJIRA_EMAIL- Your Jira account emailJIRA_API_TOKEN- API token from Atlassian account settings
Why Not Use Atlassian MCP Directly?
mcp__atlassian__editJiraIssue and mcp__atlassian__transitionJiraIssue:
- Require looking up user account IDs separately
- Require looking up transition IDs separately
- No caching - repeated API calls for metadata
- Verbose output wastes tokens
This skill's script:
- Caches user/priority/component metadata
- Accepts human-readable names (not IDs)
- Automatically finds matching transitions
- Returns token-efficient output
Always prefer this skill over direct MCP calls for Jira updates.
Reference
For detailed field options and error codes, see references/options-reference.md.