Create a GitHub Issue as a parent-child structure.
Prerequisites
ghThe CLI is installed and authenticatedgh auth statuscan be confirmed with
Flow
Step 1: Analyze the task content
Extract the following from the user's explanation:
- Summary of the feature/fix
- Background/motivation
- Acceptance criteria
- Breakdown into individual tasks
Step 1.5: Determine the milestone
Confirm with the user whether to assign a GitHub Milestone to the Issues to be created (the same for both parent and child).
Guard for repositories not using milestones: If the repository has no milestones at all (including closed ones), treat it as a repository not using milestones and skip this step without confirmation (unless the user explicitly requests milestone assignment).
MILESTONE_COUNT=$(gh api "repos/{owner}/{repo}/milestones?state=all" --jq 'length')
# MILESTONE_COUNT が 0 なら、このステップをスキップして Step 2 へ進む
- If assigning:
- If the parent Issue number is known (e.g., adding to an existing tree),
gh issue view <親番号> --json milestone --jq '.milestone.title // empty'retrieve the parent's milestone with and confirm with the user whether it may be inherited. If the retrieval result is empty (the parent has no milestone set), do not inherit it and proceed to the next list presentation flow - If the parent is unknown or the parent's milestone is empty,
gh api repos/{owner}/{repo}/milestones --jq '.[] | select(.state=="open") | .title'present the list of open milestones and have the user choose one - If using a new milestone name not in the list,
gh issue create --milestoneaccepts only existing names, so first create it withgh api --method POST "repos/{owner}/{repo}/milestones" -f "title=<名前>"(if a closed milestone with the same name exists, it will result in 422, so confirm with the user whether to reopen it or use a different name) - Set the determined name in
MILESTONEset to - If the parent Issue number is known and the parent has no milestone set, also reflect the determined
MILESTONEon the parent withgh issue edit <親番号> --milestone "${MILESTONE}"(prevent the inconsistency where only the child has a milestone and the parent remains unset. Idempotent)
- If the parent Issue number is known (e.g., adding to an existing tree),
- If not assigning: leave
MILESTONEempty and proceed to Step 2 and beyond (create the Issue without a milestone)
Step 2: Create the parent Issue
# MILESTONE が空でなければ --milestone を付与する(Step 1.5 で決定済み)
PARENT_ARGS=(--title "feat: 機能名")
if [[ -n "${MILESTONE}" ]]; then
PARENT_ARGS+=(--milestone "${MILESTONE}")
fi
gh issue create "${PARENT_ARGS[@]}" \
--body "$(cat <<'EOF'
## 概要
...
## 背景
...
## 受け入れ条件
- [ ] 条件1
- [ ] 条件2
## 関連
- Figma: ...
- 関連 Issue: #...
EOF
)"
The title uses the Conventional Commits format: feat:, fix:, chore: etc.
Step 3: Create the child Issues
Create each individual task as a child Issue (MILESTONE uses the same value as the parent):
CHILD_ARGS=(--title "feat: タスク名")
if [[ -n "${MILESTONE}" ]]; then
CHILD_ARGS+=(--milestone "${MILESTONE}")
fi
gh issue create "${CHILD_ARGS[@]}" --body "..."
Step 4: Link as Sub-issues
gh api Use to add the child Issues to the parent's sub-issues. The GitHub sub-issues API requires database id rather than the issue number, so first retrieve gh api the database id with and then pass it:
# 子 Issue の database id を取得する(issue 番号 {child_number} から変換)
child_id=$(gh api "repos/{owner}/{repo}/issues/{child_number}" --jq '.id')
# database id を sub_issue_id に渡して紐付ける
gh api \
--method POST \
"repos/{owner}/{repo}/issues/{parent_number}/sub_issues" \
-F "sub_issue_id=${child_id}"
Step 5: Return the Issue URLs
List the URLs of the created parent Issue and child Issues.
Verification
After creating the Issue, verify the following.
# 親 Issue の内容と sub-issues の紐付けを確認
gh issue view <親Issue番号>
# sub-issues が正しく紐付いているか確認
gh api "repos/{owner}/{repo}/issues/<親Issue番号>/sub_issues" --jq '.[].number'
- All child Issues are listed in the parent Issue
- Each Issue's title is in Conventional Commits format
Common failures
| Problem | Workaround |
|---|---|
sub_issue_id pass the issue number to |
gh api .../issues/<number> の .id(database id) and pass it |
| The child Issues are at a granularity where they cannot be completed independently | Review the acceptance criteria, narrow down to a single concern, and re-decompose |
Authentication error causes gh api to fail |
gh auth status check the authentication status withgh auth login re-authenticate with |
Notes
- Issue titles are recommended to be in Conventional Commits format
- Child Issues should be at a granularity where they can be completed independently
- Whether a milestone is needed must always be confirmed with the user in Step 1.5 (do not omit this. Repositories with no milestones at all are skipped by the guard in Step 1.5). If labels are needed, confirm separately as well
Execution in a sandbox environment
This skill requires GitHub operations over the network (gh issue create / gh api .../sub_issues). The relevant commands are executed with the sandbox disabled on a per-command basis. It cannot be executed in environments where network blocking cannot be lifted.