Skip to main content
Agent skill

Issue Management

Manage GitHub Issues 2.0 relationships with gh CLI: parent issues, sub-issues, blocked-by, and blocking links.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Issue Management when an AI agent needs a reusable SKILL.md workflow for this job: Manage GitHub Issues 2.0 relationships with gh CLI: parent issues, sub-issues, blocked-by, and blocking links.

When not to use it

Skip Issue Management when the task is outside the productivity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/issue-management
# Save SKILL.md to ~/.claude/skills/issue-management/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/issue-management/SKILL.md. For a shared project, commit the folder at .claude/skills/issue-management/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Issue Management skill for this task: Use Issue Management when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
71/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

Use this skill when creating, editing, inspecting, or removing relationships between GitHub issues.

These commands use the Issues 2.0 `gh issue` support added in GitHub CLI PR [cli/cli#13057](https://github.com/cli/cli/pull/13057). Because this feature is new, first confirm the installed `gh` supports it:

```bash gh issue create --help | grep -E -- '--parent|--blocked-by|--blocking' gh issue edit --help | grep -E -- '--parent|--add-sub-issue|--add-blocked-by|--add-blocking' ```

If those flags are missing, update `gh` before trying to manage issue relationships. Do not invent older commands.

## Issue reference format

Relationship flags accept issue numbers or issue URLs.

Use a number for an issue in the current repository:

```bash gh issue edit 123 --parent 100 ```

Use a full issue URL for a cross-repository relationship:

```bash gh issue edit 123 --blocked-by https://github.com/remotion-dev/remotion/issues/456 ```

Multiple related issues can be passed as a comma-separated list:

```bash gh issue edit 123 --add-blocked-by 200,201 ```

## Parent and sub-issue relationships

A sub-issue has exactly one parent issue.

To create a new issue directly under a parent:

```bash gh issue create \ --title 'Docs: Add issue management skill' \ --body-file /tmp/remotion-issue-body.md \ --parent 100 ```

To set or change the parent of an existing child issue:

```bash gh issue edit <child-number> --parent <parent-number-or-url> ```

To remove the parent from a child issue:

```bash gh issue edit <child-number> --remove-parent ```

To manage children from the parent issue:

```bash gh issue edit <parent-number> --add-sub-issue <child-number-or-url> gh issue edit <parent-number> --remove-sub-issue <child-number-or-url> ```

`--add-sub-issue` moves the child to the new parent if it already has another parent. Do not use `--add-sub-issue` while editing multiple parent issues in one command; one child cannot be added ambiguously to several parents.

## Blocked-by and blocking relationships

Use `blocked-by` when the issue being edited is waiting on another issue.

```bash # Issue 123 is blocked by issue 200. gh issue edit 123 --add-blocked-by 200

# Remove that relationship. gh issue edit 123 --remove-blocked-by 200 ```

Use `blocking` when the issue being edited blocks another issue.

```bash # Issue 123 is blocking issues 300 and 301. gh issue edit 123 --add-blocking 300,301

# Remove one blocking relationship. gh issue edit 123 --remove-blocking 300 ```

Equivalent mental model:

```bash gh issue edit A --add-blocking B ```

means the same relationship as:

```bash gh issue edit B --add-blocked-by A ```

Choose the command based on which issue you are already editing.

When creating an issue, set relationships immediately:

```bash gh issue create \ --title 'Studio: Add timeline validation' \ --body-file /tmp/remotion-issue-body.md \ --blocked-by 200,201 \ --blocking 300 ```

## Inspecting relationships

Human-readable view shows parent, sub-issues, blocked-by, and blocking metadata when present:

```bash gh issue view <number> ```

Raw non-TTY output includes stable relationship lines:

```bash gh issue view <number> | grep -E '^(parent|sub-issues|sub-issues-completed|blocked-by|blocking):' ```

For scripts, request the JSON fields explicitly:

```bash gh issue view <number> \ --json parent,subIssues,subIssuesSummary,blockedBy,blocking ```

`subIssues`, `blockedBy`, and `blocking` are connection objects with `nodes` and `totalCount`. `subIssuesSummary` contains completion counts.

## Safe workflow

1. Create any new issue bodies with `--body-file`, not inline multiline shell strings. 2. Link the relationship using the appropriate `gh issue create` or `gh issue edit` flag. 3. Verify with `gh issue view <number>` or `gh issue view <number> --json parent,subIssues,subIssuesSummary,blockedBy,blocking`. 4. If editing a PR or parent issue body afterward, replace vague checklist text with concrete issue numbers.

Intended uses

  • Use Issue Management when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.