| name | jira-issue-relationships |
| description | Issue linking, blockers, and dependency analysis. TRIGGERS: 'what's blocking', 'what is blocking', 'is blocked by', 'link issues', 'link to', 'blockers for', 'depends on', 'clone issue', 'clone with', 'blocking chain', 'dependency graph', 'show dependencies', 'get blockers', 'relates to', 'duplicates'. Use for issue dependencies, relationships, and cloning. NOT FOR: epic linking (use jira-agile), field updates (use jira-issue), bulk cloning (use jira-bulk). |
| version | 1.0.0 |
| author | jira-assistant-skills |
| license | MIT |
| allowed-tools | ["Bash","Read","Glob","Grep"] |
jira-relationships
Issue linking and dependency management for JIRA - create, view, and analyze issue relationships.
Risk Levels
| Operation | Risk | Notes |
|---|
| Get link types | - | Read-only |
| Get links/blockers | - | Read-only |
| Get dependencies | - | Read-only |
| Link statistics | - | Read-only |
| Create link | - | Easily reversible (can unlink) |
| Remove link | ! | Link data lost, can recreate |
| Bulk link | ! | Many links created, can remove |
| Clone issue | - | Creates new issue, can delete |
| Clone with subtasks | ! | Creates multiple issues |
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:
- Link issues together (blocks, duplicates, relates to, clones)
- View issue dependencies and blockers
- Find blocker chains and critical paths
- Analyze issue relationships and dependencies
- Get link statistics for issues or projects
- Bulk link multiple issues
- Clone issues with their relationships
What this skill does
IMPORTANT: Always use the jira-as CLI. Never run Python scripts directly.
This skill provides issue relationship operations:
-
Get Link Types: View available link types in JIRA instance
- Lists all configured link types
- Shows inward/outward descriptions
- Filter by name pattern
-
Link Issues: Create relationships between issues
- Semantic flags for common types (--blocks, --relates-to, etc.)
- Support for all JIRA link types
- Optional comment on link creation
- Dry-run mode for preview
-
View Links: See all relationships for an issue
- Filter by direction (inward/outward)
- Filter by link type
- Shows linked issue status and summary
-
Remove Links: Delete issue relationships
- Remove specific links between issues
- Remove all links of a type
- Dry-run and confirmation modes
-
Blocker Analysis: Find blocking dependencies
- Direct blockers for an issue
- Recursive blocker chain traversal
- Circular dependency detection
- Critical path identification
-
Dependency Graphs: Visualize relationships
- Export to DOT format for Graphviz
- Export to Mermaid diagrams
- Export to PlantUML format
- Export to D2 diagrams (Terrastruct)
- Transitive dependency tracking
-
Link Statistics: Analyze link patterns
- Stats for single issue or entire project
- Link breakdown by type and direction
- Find orphaned issues (no links)
- Identify most-connected issues
- Status distribution of linked issues
-
Bulk Operations: Link multiple issues at once
- Link from JQL query results
- Progress tracking
- Skip existing links
-
Clone Issues: Duplicate issues with relationships
- Copy fields to new issue
- Create "clones" link to original
- Optionally copy subtasks and links
Available Commands
| Command | Description |
|---|
jira-as relationships link-types | List available link types |
jira-as relationships link | Create link between issues |
jira-as relationships get-links | View links for an issue |
jira-as relationships unlink | Remove issue links |
jira-as relationships get-blockers | Find blocker chain (recursive) |
jira-as relationships get-dependencies | Find all dependencies |
jira-as relationships stats | Analyze link statistics for issues/projects |
jira-as relationships bulk-link | Bulk link multiple issues |
jira-as relationships clone | Clone issue with links |
All commands support --help for full documentation.
Common Options
All commands support these common options:
| Option | Description |
|---|
-o/--output FORMAT | Output format (see table below) |
--help | Show help message and exit |
Output Formats by Command
| Command | Supported Formats |
|---|
link-types | text, json |
link | text, json |
get-links | text, json |
unlink | text, json |
get-blockers | text, json |
get-dependencies | text, json, mermaid, dot, plantuml, d2 |
stats | text, json |
bulk-link | text, json |
clone | text, json |
Examples
Quick Start - Common Operations
jira-as relationships link-types
jira-as relationships link-types --filter block
jira-as relationships link-types --output json
jira-as relationships link PROJ-1 --blocks PROJ-2
jira-as relationships link PROJ-1 --is-blocked-by PROJ-2
jira-as relationships link PROJ-1 --duplicates PROJ-2
jira-as relationships link PROJ-1 --clones PROJ-2
jira-as relationships link PROJ-1 --relates-to PROJ-2
jira-as relationships link PROJ-1 --type "Blocks" --to PROJ-2
jira-as relationships get-links PROJ-123
jira-as relationships get-links PROJ-123 --direction outward
jira-as relationships unlink PROJ-1 PROJ-2
jira-as relationships unlink PROJ-1 PROJ-2 --dry-run
jira-as relationships unlink PROJ-1 --type blocks --all
jira-as relationships clone PROJ-123 --clone-subtasks -l
jira-as relationships clone PROJ-123 -p OTHER
jira-as relationships clone PROJ-123 --summary "Custom summary"
jira-as relationships clone PROJ-123 --no-link
Advanced - Blocker Analysis & Statistics
jira-as relationships get-blockers PROJ-123 --recursive
jira-as relationships get-blockers PROJ-123 --recursive --include-done
jira-as relationships get-blockers PROJ-123 -r --depth 3
jira-as relationships get-blockers PROJ-123 -r --depth 0
jira-as relationships get-blockers PROJ-123 -d inward
jira-as relationships get-dependencies PROJ-123
jira-as relationships get-dependencies PROJ-123 -t blocks,relates
jira-as relationships stats PROJ-123
jira-as relationships stats PROJ
jira-as relationships stats -p PROJ
jira-as relationships stats --jql "type = Epic"
jira-as relationships stats -p PROJ -t 20
jira-as relationships stats -p PROJ --max-results 100
jira-as relationships bulk-link --jql "project=PROJ AND fixVersion=1.0" --relates-to PROJ-500 --dry-run
jira-as relationships bulk-link --issues PROJ-1,PROJ-2,PROJ-3 --blocks PROJ-100
jira-as relationships bulk-link --issues PROJ-1,PROJ-2 --blocks PROJ-100 --output json
jira-as relationships bulk-link --jql "sprint in openSprints()" --relates-to PROJ-500 --skip-existing
Visualization - Dependency Graphs
jira-as relationships get-dependencies PROJ-123 --output mermaid
jira-as relationships get-dependencies PROJ-123 --output dot > deps.dot
dot -Tpng deps.dot -o deps.png
jira-as relationships get-dependencies PROJ-123 --output plantuml > deps.puml
jira-as relationships get-dependencies PROJ-123 --output d2 > deps.d2
d2 deps.d2 deps.svg
Exporting Dependency Graphs
Use jira-as relationships get-dependencies with --output flag to generate diagrams:
- Formats:
text (default), json, mermaid (GitHub docs), dot (Graphviz), plantuml, d2
- All formats include status-based coloring and link type labels
- Run
jira-as relationships get-dependencies --help for rendering instructions
Link Types
Standard JIRA link types and when to use them:
| Link Type | Outward | Inward | When to Use |
|---|
| Blocks | blocks | is blocked by | Sequential dependencies: Task A must finish before B starts |
| Duplicate | duplicates | is duplicated by | Mark redundant issues; close the duplicate |
| Relates | relates to | relates to | General association; cross-team awareness |
| Cloners | clones | is cloned by | Issue templates; multi-platform variants |
Link Direction: When A blocks B, A is "outward" (blocks) and B is "inward" (is blocked by).
Use --blocks when source issue blocks target; use --is-blocked-by when source is blocked by target.
Note: Issue links are labels only - they do not enforce workflow rules. Combine with automation or team discipline.
Exit Codes
| Code | Description |
|---|
| 0 | Success |
| 1 | Error (validation failed, API error, or issue not found) |
Troubleshooting
"Issue does not exist" error
- Verify the issue key format is correct (e.g., PROJ-123)
- Check that you have permission to view the issue
- Confirm the project exists in your JIRA instance
"Link type not found" error
- Run
jira-as relationships link-types to see available link types
- Link type names are case-sensitive in some JIRA instances
- Custom link types may have different names than standard ones
"Permission denied" when creating links
- Ensure you have "Link Issues" permission in the project
- Some projects may restrict who can create certain link types
Bulk link operations timing out
- Reduce the number of issues in a single operation
- Use
--max-results to limit JQL query results
- Consider breaking large operations into smaller batches
Clone operation fails
- Verify you have "Create Issues" permission in the target project
- Check that required fields for the target project are satisfied
- Some fields may not be cloneable (e.g., custom field restrictions)
Circular dependency detected
- The blocker analysis command automatically detects and reports cycles
- Review the blocker chain to identify and break the cycle
- Consider whether the blocking relationship is correctly modeled
Configuration
Requires JIRA credentials via environment variables (JIRA_SITE_URL, JIRA_EMAIL, JIRA_API_TOKEN).
Architecture Patterns
For strategic guidance on blocker chains, circular dependencies, cross-project linking, and visualization strategies, see Patterns Guide.
Related skills
- jira-issue: For creating and updating issues
- jira-lifecycle: For transitioning issues through workflows
- jira-search: For finding issues to link
- jira-agile: For epic and sprint management
