gh-link-subissues

GitHub Sub-issue Linking Skill

Link one or more child Issues as Sub-issues to a parent Issue. Linking is possible even across different repositories (cross-repository). After linking, all Issues are automatically added to a GitHub Project.

Prerequisites

• gh The CLI must be installed and authenticated
• You must have access rights to the target repository

Configuration File

The configuration used for adding to a GitHub Project is loaded from ~/.claude/custom-config/create-issue-config.json . /create-issue It shares configuration with the skill, preventing duplicate management.

{
  "project": {
    "owner": "org-or-user-name",
    "number": 1
  }
}

If the configuration file does not exist, skip adding to the Project and guide the user to create the configuration file.

Input

Collect the following information from the user:

• Parent Issue: owner/repo#number format or GitHub URL
• Child Issues (one or more): owner/repo#number format or a list of GitHub URLs

Procedure

Step 1: Get the Issue Node IDs

Get the Node ID of each Issue via the GitHub GraphQL API. Issues in the same repository can be fetched together in a single API call using aliases.

# 単一 Issue の Node ID 取得
gh api graphql -f query='
query($owner: String!, $repo: String!, $number: Int!) {
  repository(owner: $owner, name: $repo) {
    issue(number: $number) { id title }
  }
}' -f owner="OWNER" -f repo="REPO" -F number=NUMBER \
  -q '.data.repository.issue.id'

# 同一リポジトリの複数 Issue をエイリアスで一括取得
gh api graphql -f query='
query {
  repository(owner: "OWNER", name: "REPO") {
    i1: issue(number: 10) { id title }
    i2: issue(number: 20) { id title }
  }
}' -q '.data.repository'

Step 2: Link with the addSubIssue mutation

Using the retrieved Node IDs, link each child Issue to the parent Issue.

gh api graphql -f query='
mutation($parent: ID!, $child: ID!) {
  addSubIssue(input: {issueId: $parent, subIssueId: $child}) {
    issue { id title }
    subIssue { id title }
  }
}' -f parent="PARENT_NODE_ID" -f child="CHILD_NODE_ID"

If there are multiple child Issues, execute the mutation for each of them.

Step 3: Add to GitHub Project

~/.claude/custom-config/create-issue-config.json Load project.owner と project.number from, and add the parent Issue and all child Issues to the GitHub Project.

# 設定ファイルから Project 情報を読み込み
PROJECT_OWNER=$(jq -r '.project.owner' ~/.claude/custom-config/create-issue-config.json)
PROJECT_NUMBER=$(jq -r '.project.number' ~/.claude/custom-config/create-issue-config.json)

# 全 Issue（親 + 子）を Project に追加
# gh project item-add は冪等（既に追加済みでもエラーにならない）
gh project item-add "$PROJECT_NUMBER" --owner "$PROJECT_OWNER" --url "ISSUE_URL"

Execute this for the parent Issue and each of all child Issues. The Issue URL is in the https://github.com/{owner}/{repo}/issues/{number} format.

Step 4: Set Project Fields

Set the Status, Priority, and Start date of each Issue added to the Project.

4a. Get the Project's field definitions

gh api graphql -f query='
{
  user(login: "PROJECT_OWNER") {
    projectV2(number: PROJECT_NUMBER) {
      id
      fields(first: 30) {
        nodes {
          ... on ProjectV2Field {
            id
            name
            dataType
          }
          ... on ProjectV2SingleSelectField {
            id
            name
            options { id name }
          }
        }
      }
    }
  }
}'

Field IDs to retrieve:

• Status field ID and the ID of each option (Backlog, In progress, etc.)
• Priority field ID and the ID of each option (P0, P1, P2)
• Start date field ID

4b. Get the Project Item ID of each Issue

gh api graphql -f query='
{
  repository(owner: "OWNER", name: "REPO") {
    issue(number: NUMBER) {
      projectItems(first: 5) {
        nodes {
          id
          project { id }
        }
      }
    }
  }
}' -q '.data.repository.issue.projectItems.nodes[] | select(.project.id == "PROJECT_ID") | .id'

Issues in the same repository can be fetched together using aliases.

4c. Set the field values

# Status の設定
gh project item-edit --project-id "PROJECT_ID" --id "ITEM_ID" \
  --field-id "STATUS_FIELD_ID" --single-select-option-id "OPTION_ID"

# Priority の設定
gh project item-edit --project-id "PROJECT_ID" --id "ITEM_ID" \
  --field-id "PRIORITY_FIELD_ID" --single-select-option-id "OPTION_ID"

# Start date の設定
gh project item-edit --project-id "PROJECT_ID" --id "ITEM_ID" \
  --field-id "START_DATE_FIELD_ID" --date "$(date +%Y-%m-%d)"

Field Value Determination Rules

Field	How to determine the value
Status	Default: Backlog. If the user specifies a value, use that value
Priority	If the Issue title has a [P0]/[P1]/[P2] prefix, correspond to it. Otherwise, skip
Start date	create-issue-config.json の project.start_date が "today" then today's date. Otherwise, skip

Do not set Priority on the parent Issue (because the priorities of child Issues are mixed).

Step 5: Checking the results

Please report the results of the linking and Project settings together:

• Titles of the parent Issue and child Issues that were successfully linked
• Number of Issues added to the Project
• Breakdown of the fields that were set (Status, Priority, Start date)
• If an error occurred, its details

Notes

• -f is used for string parameters,-F is used for numeric parameters (number は Int! type, so -F）
• -q uses a jq filter to extract specific fields from the result
• Node ID は I_kwDO a globally unique identifier starting with
• If it is already linked, an error is returned
• gh project item-add is idempotent, so it can be safely run even on Issues already added to the Project
• gh project item-edit is also idempotent, so there is no problem with setting the same value again on a field that has already been set
• If the configuration file does not exist, skip adding to the Project and setting fields, and only perform Sub-issue linking
• The Project Item ID is different from the Issue's Node ID. Issue → projectItems → filter by the target Project to obtain it