git-issue-hierarchy

When to Use This Skill

Context

• Repo: !git remote -v
• Parent issue: (parsed from arguments)

Parameters

Parse these parameters from the command:

Every issue argument — <parent-issue> and each <N> flag value below — is accepted as a bare number, #N, or a full GitHub issue URL, and normalized to a (number, repo) pair in Step 0.

When to Use

Sub-issues vs. dependencies vs. "related to"

GitHub ships three distinct ways to link issues. Pick the right one — they're not interchangeable:

Sub-issues express composition ("is part of"). Dependencies express ordering ("must happen before"). The same two issues should rarely use both — a sub-issue is implicitly ordered by its parent's scope.

Execution

Execute the requested issue hierarchy operation.

Step 0: Normalize issue references

Before any API call, normalize <parent-issue> and every issue value passed to a flag (--add, --remove, --block, --blocked-by, --unblock) into a (number, repo) pair. Accept these forms:

Rules:

1. Strip a leading #; strip a URL #... fragment after the number. A token is an issue ref only if, after stripping, it is all digits or matches the /issues/<digits> URL shape (require trailing digits — a /pull/<N>, /discussions/<N>, or bare /issues list URL is not a ref).
2. For the plural flags (--add/--remove, which take <N...>), normalize each space-separated value independently; never split a single URL into two refs.
3. For a URL whose <owner>/<repo> differs from the current remote (Step 1 REPO), record it as cross-repo and carry -R <owner>/<repo> on every gh issue call and target repos/<owner>/<repo>/… on every gh api call for that issue. Sub-issue and dependency links require both endpoints to live in the same repo — if a normalized ref points at a different repo than the parent, surface that rather than issuing a mismatched cross-repo link.

Downstream steps use the normalized $PARENT, $N, and $CHILD numbers; where a ref was cross-repo, substitute its <owner>/<repo> for $OWNER/$REPO_NAME and add -R <owner>/<repo> to the corresponding gh issue call.

Step 1: Resolve Repository Context

REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
OWNER=$(echo "$REPO" | cut -d/ -f1)
REPO_NAME=$(echo "$REPO" | cut -d/ -f2)

If Step 0 normalized <parent-issue> to a cross-repo URL, use that URL's <owner>/<repo> as $OWNER/$REPO_NAME (and pass -R <owner>/<repo> to the gh issue view below) instead of the current remote.

Verify the parent issue exists:

gh issue view $PARENT --json number,title,state,subIssuesSummary

Step 2: Branch on Operation Mode

Determine which operation to perform based on parsed parameters.

If --status (or no flags): Display sub-issue summary and list.

If --add: Add existing issues as sub-issues.

If --create: Create new issue, then add as sub-issue.

If --remove: Remove specified sub-issues.

If --list: List all sub-issues with their states.

If --deps, --blocking, --block, --blocked-by, --unblock: Manage native GitHub issue dependencies via the dependencies/blocked_by and dependencies/blocking API endpoints.

Step 3: Execute API Calls

Sub-Issue Status

# Get summary
gh issue view $PARENT --json title,state,subIssuesSummary

# List all sub-issues with details
gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/sub_issues \
  --jq '.[] | "#\(.number) \(.state) \(.title)"'

Report format:

Issue #42: Refactor authentication system
Sub-issues: 3/5 completed (60%)

  #43 ✓ Extract token validation
  #44 ✓ Add refresh token support
  #45 ✓ Update OAuth provider
  #46 ○ Migrate session storage
  #47 ○ Update API documentation

Add Sub-Issues

For each issue number in --add:

# Get the issue's node ID (required for sub_issue_id)
CHILD_ID=$(gh api repos/$OWNER/$REPO_NAME/issues/$CHILD --jq '.id')

# Add as sub-issue
gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/sub_issues \
  -f sub_issue_id=$CHILD_ID

Verify each was added successfully. Report any errors (e.g., issue not found, already a sub-issue, sub-issues not enabled).

Create and Add Sub-Issue

# Create the new issue
NEW_ISSUE=$(gh issue create --title "$TITLE" --body "Parent: #$PARENT" --json number --jq '.number')

# Get its ID
NEW_ID=$(gh api repos/$OWNER/$REPO_NAME/issues/$NEW_ISSUE --jq '.id')

# Add as sub-issue
gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/sub_issues \
  -f sub_issue_id=$NEW_ID

Remove Sub-Issues

For each issue number in --remove:

# Get the sub-issue ID from the sub-issues list
SUB_ISSUE_ID=$(gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/sub_issues \
  --jq ".[] | select(.number == $CHILD) | .id")

# Remove it
gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/sub_issues/$SUB_ISSUE_ID -X DELETE

Dependency Management

Dependencies use GitHub's native dependencies/blocked_by and dependencies/blocking endpoints. They appear in the issue sidebar under "Relationships" and mark the blocked issue with a "Blocked" badge on project boards. Both endpoints require the target issue's node id (.id on the issue payload), not the human-readable issue number.

Add "blocked by" relationship (--blocked-by <N>): parent is blocked by N

# Resolve the blocker's node id
BLOCKER_ID=$(gh api repos/$OWNER/$REPO_NAME/issues/$N --jq '.id')

# Record the dependency on the parent
gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/dependencies/blocked_by \
  -f issue_id=$BLOCKER_ID

Add "blocks" relationship (--block <N>): parent blocks issue N

The API is one-directional — write the relationship on the blocked side:

# Resolve the parent's node id
PARENT_ID=$(gh api repos/$OWNER/$REPO_NAME/issues/$PARENT --jq '.id')

# Record on issue N that it is blocked by the parent
gh api repos/$OWNER/$REPO_NAME/issues/$N/dependencies/blocked_by \
  -f issue_id=$PARENT_ID

Remove relationship (--unblock <N>):

Look up which side carries the link, then delete it. The DELETE path takes the stored dependency's {issue_id} segment:

# Is the parent blocked by N?
gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/dependencies/blocked_by \
  --jq ".[] | select(.number == $N) | .id"

# Or does the parent block N?
gh api repos/$OWNER/$REPO_NAME/issues/$N/dependencies/blocked_by \
  --jq ".[] | select(.number == $PARENT) | .id"

# Delete whichever is present
gh api repos/$OWNER/$REPO_NAME/issues/$ISSUE/dependencies/blocked_by/$DEP_ID \
  -X DELETE

List what the parent blocks (--blocking):

gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/dependencies/blocking \
  --jq '.[] | "#\(.number) \(.state) \(.title)"'

Show dependency graph (--deps):

Combine both dependency endpoints with the sub-issues summary. Do not parse issue bodies — the native API is authoritative:

# What blocks the parent
gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/dependencies/blocked_by \
  --jq '.[] | "#\(.number) \(.state) \(.title)"'

# What the parent blocks
gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/dependencies/blocking \
  --jq '.[] | "#\(.number) \(.state) \(.title)"'

# Sub-issues (composition, not ordering)
gh api repos/$OWNER/$REPO_NAME/issues/$PARENT/sub_issues \
  --jq '.[] | "#\(.number) \(.state) \(.title)"'

Render output as:

#42 Refactor authentication
├── Blocked by: #40 Database migration (✓ closed)
├── Blocks:     #45 Deploy auth v2 (○ open)
└── Sub-issues:
    ├── #43 ✓ Extract token validation
    └── #44 ○ Add refresh token support

Surface Blocked by entries that are still open prominently — those are what prevent the parent from starting.

Step 4: Report Results

Report what was done:

Error Handling

Agentic Optimizations

See Also

• github-issue-writing skill for creating standalone issues
• git:issue skill for implementing/processing issues
• gh-cli-agentic skill for raw API patterns