Collaboration features for JIRA issues - comments, attachments, watchers, and notifications.
Risk Levels
| Operation | Risk | Notes |
|---|---|---|
| List comments/attachments | - |
Read-only |
| List watchers | - |
Read-only |
| View activity history | - |
Read-only |
| Add comment | - |
Easily reversible (can delete) |
| Upload attachment | - |
Easily reversible (can delete) |
| Add watcher | - |
Can remove watcher |
| Send notification | - |
Cannot unsend but harmless |
| Update comment | ! |
Previous text lost |
| Update custom fields | ! |
Can be undone via edit |
| Remove watcher | ! |
Can re-add |
| Delete comment | !! |
Comment text lost |
| Delete attachment | !! |
File lost, must re-upload |
Risk Legend: - Safe, read-only | ! Caution, modifiable | !! Warning, destructive but recoverable | !!! Danger, irreversible
When to use this skill
Use this skill when you need to:
- Add, update, or delete comments on issues
- Upload or download attachments
- Manage watchers (add/remove)
- Send notifications to users or groups
- View issue activity and changelog
What this skill does
IMPORTANT: Always use the jira-as CLI. Never run Python scripts directly.
- Comments: Add/edit/delete comments with rich text support
- Attachments: Upload and download files
- Watchers: Manage who tracks the issue
- Notifications: Send targeted notifications
- Activity History: View issue changelog
- Custom Fields: Update custom field values
Available Commands
Comments
| Command | Description |
|---|---|
jira-as collaborate comment add |
Add comment with visibility controls |
jira-as collaborate comment update |
Update existing comment |
jira-as collaborate comment delete |
Delete comment (with confirmation) |
jira-as collaborate comment list |
List and search comments |
Attachments
| Command | Description |
|---|---|
jira-as collaborate attachment list |
List attachments on issue |
jira-as collaborate attachment upload |
Upload file to issue |
jira-as collaborate attachment download |
Download attachments |
Notifications & Activity
| Command | Description |
|---|---|
jira-as collaborate notify |
Send notifications to users/groups |
jira-as collaborate activity |
View issue changelog |
Watchers & Fields
| Command | Description |
|---|---|
jira-as collaborate watchers |
Add/remove/list watchers |
jira-as collaborate update-fields |
Update custom fields |
All commands support --help for full documentation.
Quick Start Examples
# Add a comment
jira-as collaborate comment add PROJ-123 --body "Starting work on this now"
# Rich text comment (-f/--format supports: text, markdown, adf)
jira-as collaborate comment add PROJ-123 --body "**Bold** text" --format markdown
# Internal comment (role-restricted)
jira-as collaborate comment add PROJ-123 --body "Internal note" --visibility-role Administrators
# Internal comment (group-restricted)
jira-as collaborate comment add PROJ-123 --body "Team only" --visibility-group jira-developers
# List comments (supports --order asc or desc)
jira-as collaborate comment list PROJ-123
jira-as collaborate comment list PROJ-123 -l 10 --order desc
# Get specific comment by ID
jira-as collaborate comment list PROJ-123 --id 10001
# List comments with pagination
jira-as collaborate comment list PROJ-123 -l 10 --offset 20
# Update a comment (requires comment ID)
jira-as collaborate comment update PROJ-123 --id 10001 --body "Updated text"
# Delete a comment (preview first)
jira-as collaborate comment delete PROJ-123 --id 10001 --dry-run
# Delete a comment (confirmed)
jira-as collaborate comment delete PROJ-123 --id 10001 --yes
# Upload attachment (-f is short for --file)
jira-as collaborate attachment upload PROJ-123 -f screenshot.png
jira-as collaborate attachment upload PROJ-123 --file screenshot.png
# Upload attachment with custom name (-n is short for --name)
jira-as collaborate attachment upload PROJ-123 -f screenshot.png -n evidence-2024.png
# List attachments on issue
jira-as collaborate attachment list PROJ-123
# Download attachment by ID (-o is short for --output-dir)
jira-as collaborate attachment download PROJ-123 --id 12345 -o ./downloads/
# Download attachment by filename
jira-as collaborate attachment download PROJ-123 --name error.log -o ./downloads/
# Download all attachments from issue
jira-as collaborate attachment download PROJ-123 --all -o ./backups/
# List watchers (-l is short for --list)
jira-as collaborate watchers PROJ-123 -l
jira-as collaborate watchers PROJ-123 --list
# Add watcher (-a is short for --add)
jira-as collaborate watchers PROJ-123 -a user@example.com
# Remove watcher (-r is short for --remove)
jira-as collaborate watchers PROJ-123 -r user@example.com
# Send notification to watchers
jira-as collaborate notify PROJ-123 --watchers --subject "Update" --body "Issue resolved"
# Send notification to voters
jira-as collaborate notify PROJ-123 --voters --subject "Vote counted"
# Send notification to a group
jira-as collaborate notify PROJ-123 --group developers --subject "Team update"
# Send notification to specific users (requires account ID)
jira-as collaborate notify PROJ-123 --user 5b10ac8d82e05b22cc7d4ef5 --subject "Review needed"
# Send notification to assignee and reporter
jira-as collaborate notify PROJ-123 --assignee --reporter --subject "Please review"
# Preview notification without sending
jira-as collaborate notify PROJ-123 --watchers --dry-run
# View activity history
jira-as collaborate activity PROJ-123
# View activity with filters
jira-as collaborate activity PROJ-123 --field status --field assignee --output table
jira-as collaborate activity PROJ-123 --field-type custom --limit 10
# View activity with pagination
jira-as collaborate activity PROJ-123 --limit 10 --offset 20
# Update custom fields (JSON format)
jira-as collaborate update-fields PROJ-123 --fields '{"customfield_10014": "value"}'
# Update multiple fields
jira-as collaborate update-fields PROJ-123 --fields '{"customfield_10014": "Epic Name", "customfield_10016": 5}'
# Update with array values
jira-as collaborate update-fields PROJ-123 --fields '{"labels": ["urgent", "customer"]}'
Common Options
All commands support:
| Option | Description |
|---|---|
--help |
Show detailed help |
Output Formats by Command
Only these commands accept -o/--output:
| Command | Supported Formats |
|---|---|
comment list |
text, json |
attachment list |
text, json |
activity |
table, json |
All other collaborate commands print plain text status output and have no
output-format option. Note: for attachment download, -o is short for
--output-dir (download destination), not an output format.
For command-specific options, use --help on any command:
jira-as collaborate comment add --help
jira-as collaborate notify --help
See references/SCRIPT_OPTIONS.md for full option matrix.
Exit Codes
| Code | Description |
|---|---|
| 0 | Success |
| 1 | General error (validation, API error, network issue) |
Troubleshooting
| Error | Solution |
|---|---|
| "Comment not found" | Verify comment ID with jira-as collaborate comment list ISSUE-KEY |
| "Attachment not found" | Use jira-as collaborate attachment list ISSUE-KEY to see available attachments |
| "Permission denied" | Check visibility role/group permissions |
| "User not found" | Use account ID (not email) for watchers |
| "Notification not received" | Use --dry-run to verify recipients |
For debug mode: export JIRA_DEBUG=1
Documentation Structure
Getting Started: docs/GETTING_STARTED.md - First 5 minutes
Common Scenarios: docs/scenarios/ - Workflow examples
Reference: docs/QUICK_REFERENCE.md - Commands and JQL
Templates: docs/TEMPLATES.md - Copy-paste ready
Advanced Topics: docs/DEEP_DIVES/ - Deep dive guides
Format Reference: references/adf_guide.md - Markdown to ADF
Related Skills
- jira-issue: For creating and updating issue fields
- jira-lifecycle: For transitioning with comments
- jira-search: For finding issues to collaborate on