Github Sub Issue Add

Add Sub-Issue to GitHub Main/Parent Issue

This skill allows creating a new sub-issue or linking an existing issue as a sub-issue to a parent/main issue using the official GitHub REST API (API version 2026-03-10). It also supports establishing issue dependencies (blocking relationships).

---

⚠️ CRITICAL CONCEPT: GitHub Identifiers

To perform sub-issue or dependency operations, you MUST understand and handle the difference between GitHub's distinct identifier types:

1. Issue Number (e.g., 2396):

• A human-friendly sequential integer unique within a single repository.
• Used in URLs, markdown references (#2396), and standard CLI commands (gh issue view 2396).

1. GraphQL Global Node ID (e.g., "I_kwDOP0rKb88AAAABFCwpYA"):

• A globally unique string identifier.
• WARNING: In the gh CLI, calling gh issue view --json id or gh issue list --json id returns this string Node ID, NOT the numerical database ID!

1. Numerical REST Database ID (e.g., 4633405792):

• A globally unique numerical integer used by GitHub's relational database.
• CRITICAL: The REST API endpoints for sub-issues and dependencies (under API version 2026-03-10) require this numerical Database ID in their JSON payloads. Passing the sequential Issue Number or the string GraphQL Global Node ID will result in validation errors (typically 404 Not Found or 422 Unprocessable Entity).

---

⚡ RECOMMENDED METHOD: Foolproof Helper Script

To automate ID resolution, API calls, and handle fallbacks gracefully, always use the workspace helper script:

Link Sub-Issue to Parent:

npx node .agents/skills/github-sub-issue-add/scripts/github-sub-issue-helper.js add --parent  --sub 

Establish Issue Dependency (Blocking Relationship):

npx node .agents/skills/github-sub-issue-add/scripts/github-sub-issue-helper.js dependency --dependent  --blocking 

---

🛠️ MANUAL METHOD: Step-by-Step API Execution

If the helper script cannot be executed, follow these steps manually:

Phase 1: Retrieve the Numerical REST Database ID

To get the correct numerical database ID of an issue (e.g., #2390), run:

gh api repos/{owner}/{repo}/issues/2390 --jq .id

Note: The {owner} and {repo} placeholders inside curly braces are automatically replaced by the gh CLI with your active repository details.

Phase 2: Create and Link Sub-Issue

Scenario A: Create a New Sub-Issue and Link it

1. Create the New Issue and retrieve its sequential issue number:

``bash SUB_ISSUE_NUMBER=$(gh issue create \ --title "[Agent] " \ --body "Part of #\n\n## Task\n" \ --assignee "pm-username,dev-username" \ --json number --jq .number) ``

1. Retrieve the Numerical Database ID of the new sub-issue:

``bash SUB_ISSUE_DB_ID=$(gh api repos/{owner}/{repo}/issues/$SUB_ISSUE_NUMBER --jq .id) ``

1. Link as Sub-Issue to the Parent Issue:

Establish the native parent-child relationship: ``bash gh api \ -H "Accept: application/vnd.github+json" \ -H "X-GitHub-Api-Version: 2026-03-10" \ --method POST \ /repos/{owner}/{repo}/issues//sub_issues \ -f sub_issue_id=$SUB_ISSUE_DB_ID ` *Note: Use -f (lowercase) so gh api` correctly formats the payload as a JSON number.*

Scenario B: Link an Existing Issue as a Sub-Issue

gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  --method POST \
  /repos/{owner}/{repo}/issues//sub_issues \
  -f sub_issue_id=

---

Phase 3: Manage Issue Dependencies (Blocking / Blocked By)

If a task is blocked by another task, establish the blocking relationship:

gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  --method POST \
  /repos/{owner}/{repo}/issues//dependencies/blocked_by \
  -f issue_id=

---

Phase 4: Robust Fallback Strategy

If the native REST API calls fail (due to outdated CLI, restricted API access, or missing repo features):

1. Checkbox Linkage in Parent Issue description:

Read the parent issue description and append the child issue under an implementation progress checklist: ```markdown ## Implementation Progress

• [ ] #

`` Edit the description via: `bash gh issue edit --body "" ``

1. Reference Comments:

Comment on the parent and sub-issues to guarantee audit traceability: ``bash gh issue comment --body "Sub-task linked (fallback): #" gh issue comment --body "Part of parent issue #" ``

1. Dependency Fallback Comments:

If dependency mapping fails, post comments on both issues: ``bash gh issue comment --body "⚠️ **Blocked By:** #" gh issue comment --body "🔗 **Blocks:** #" ``

---

Phase 5: Verification

Verify that relationships and dependencies are updated:

gh issue view  --json sub_issues_summary,issue_dependencies_summary

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: P2ERGmbH
• Source: P2ERGmbH/agentic-coding
• License: MIT

Install and usage instructions live in the source repository linked above.