SuperAPI AI Directory

create-issue

Coding & development

View repository

Updated 10-15 21:40

About this skill

create-issue

Create a GitHub Issue as a parent-child structure.

Prerequisites

  • gh The CLI is installed and authenticated
  • gh auth status can 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 --milestone accepts only existing names, so first create it with gh 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 MILESTONE set to
    • If the parent Issue number is known and the parent has no milestone set, also reflect the determined MILESTONE on the parent with gh issue edit <親番号> --milestone "${MILESTONE}" (prevent the inconsistency where only the child has a milestone and the parent remains unset. Idempotent)
  • If not assigning: leave MILESTONE empty 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.