home / skills / seika139 / dotfiles / gh-link-subissues

gh-link-subissues skill

safe

/claude/profiles/cg-m2-mac/skills/gh-link-subissues

This skill links a parent GitHub issue with one or more sub-issues across repositories using GraphQL, returning titles.

npx playbooks add skill seika139/dotfiles --skill gh-link-subissues

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: "gh-link-subissues"
description: "GitHub Issue に Sub-issue を紐付けます。クロスリポジトリ対応。親 Issue の URL/番号と、子 Issue の URL/番号リストを指定してください。"
---

# GitHub Sub-issue 紐付けスキル

親 Issue に1つ以上の子 Issue を Sub-issue として紐付けます。
異なるリポジトリ間（クロスリポジトリ）でも紐付け可能です。

## 前提条件

- `gh` CLI がインストール・認証済みであること
- 対象リポジトリへのアクセス権があること

## 入力

ユーザーから以下の情報を収集してください：

- **親 Issue**: `owner/repo#number` 形式または GitHub URL
- **子 Issue（1つ以上）**: `owner/repo#number` 形式または GitHub URL のリスト

## 手順

### Step 1: Issue の Node ID を取得

各 Issue の Node ID を GitHub GraphQL API で取得します。
同一リポジトリの Issue はエイリアスを使って1回の API コールでまとめて取得できます。

```bash
# 単一 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'
```

```bash
# 同一リポジトリの複数 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: addSubIssue mutation で紐付け

取得した Node ID を使い、各子 Issue を親 Issue に紐付けます。

```bash
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"
```

子 Issue が複数ある場合は、それぞれに対して mutation を実行してください。

### Step 3: 結果の確認

紐付けが成功したら、親 Issue と子 Issue のタイトルを表示して結果を報告してください。

## 注意事項

- `-f` は文字列パラメータ、`-F` は数値パラメータに使う（`number` は `Int!` 型なので `-F`）
- `-q` は jq フィルタで結果から特定フィールドを抽出する
- Node ID は `I_kwDO` で始まるグローバルに一意な識別子
- 既に紐付け済みの場合はエラーが返る

Overview

This skill links one or more GitHub Issues as sub-issues to a parent Issue, supporting cross-repository relationships. It uses the GitHub GraphQL API via the gh CLI to fetch Issue Node IDs and perform addSubIssue mutations. Provide a parent Issue and one or more child Issues as URLs or owner/repo#number strings.

How this skill works

The skill parses the parent and child Issue identifiers and retrieves each Issue's Node ID using gh api graphql queries. For multiple Issues in the same repository it batches lookups with aliased queries to reduce API calls. It then calls the addSubIssue mutation for each child Node ID to attach it to the parent, and reports titles to confirm success.

When to use it

You want to represent task hierarchies by linking child Issues under a parent Issue.
You need to associate Issues across different repositories (cross-repo linking).
You manage project workflows where a parent Issue aggregates progress of sub-tasks.
You prefer scripting the process via gh CLI instead of the GitHub web UI.

Best practices

Ensure gh CLI is installed and authenticated before running the skill.
Verify you have the necessary repository permissions for all involved Issues.
Use owner/repo#number or full GitHub Issue URLs consistently to avoid parsing errors.
Batch Node ID lookups for Issues in the same repository using GraphQL aliases.
Handle already-linked errors gracefully; the API will return an error if a sub-issue is already attached.

Example use cases

Link three task Issues from a feature repo as sub-issues under a cross-repo planning Issue.
Automate creating a parent Issue then attaching multiple existing child Issues as part of a release workflow.
Script daily synchronization to ensure sprint parent Issues reference current work items in other repositories.

FAQ

What inputs does the skill accept?

It accepts a parent Issue and one or more child Issues specified as owner/repo#number or full GitHub Issue URLs.

What permissions are required?

You need gh CLI authentication and write access to the repositories containing the parent and child Issues.