# Create Github Issues > Create GitHub Issues from a conversation, plan, or TODO list. Produces one Epic parent Issue and child Issues per task, each with background, requirements, specs, dependency, and acceptance criteria, linked to the Epic as GitHub sub-issues with dependencies recorded as blocked-by/blocking relations. Requirements (what) and specs (how) are kept separate and length-capped so bodies stay concise, and the Epic also renders a Mermaid diagram (a compact table for large epics) showing which child Issues block each other and which can run in parallel. Issue titles, bodies, and every interactive prompt are written in Japanese by default; pass `lang en` to generate the whole run in English instead. Use this skill when the user asks to track tasks with an Epic, turn TODOs or a plan into GitHub Issues, or extract action items from a review or investigation. - Skill: `maro114510/create-github-issues` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add maro114510/create-github-issues` - Raw SKILL.md: https://api.skillmd.com/api/skills/maro114510/create-github-issues/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: maro114510 (https://skillmd.com/u/maro114510) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/maro114510/create-github-issues --- # create-github-issues Create a GitHub Epic and child Issues from conversation context. Write concise, length-capped bodies (requirements separated from specs), model dependencies explicitly, then link hierarchy and dependencies via native `gh` CLI flags and render the dependency graph in the Epic. **Core rule that governs every step below: an Issue body may only contain facts already surfaced and approved earlier in this flow (Step 1.5 / Step 2 / Step 3). Step 4 is formatting, not authoring — never introduce a new requirement, spec detail, or dependency for the first time while writing the final Markdown body.** If you notice you need to state something new while writing a body, stop, go back to Step 3, and get it approved there first. --- ## Step 1: Identify Repository Check `$ARGUMENTS`: - If `repo ` is provided, use that repository. - Otherwise, auto-detect from the remote URL: ```bash git remote get-url origin ``` Extract `owner/repo` from `https://github.com/owner/repo.git` or `git@github.com:owner/repo.git` and store it as `REPO`. --- ## Step 1a: Determine Output Language Check `$ARGUMENTS` for `lang ` and store it as `LANG`; default to `ja` if omitted (preserves existing behavior). `LANG` is fixed for the rest of this run and governs everything produced from here on — AskUserQuestion prompts, summaries, reviews, warnings, Issue/Epic titles, and Issue/Epic bodies. From Step 1.5 through Step 6, read only `references/templates..md` — never the other language's file, and never switch languages mid-run. --- ## Step 1.5: Specification Clarification Scan the conversation context across three axes and determine whether enough information is available to write high-quality Issues. ### Evaluation Axes | Axis | Criterion | |------|-----------| | Granularity | Can each task be implemented and merged as an independent PR? | | Acceptance criteria | Can completion be confirmed with numbered verification steps? | | Specification | Are there implementation choices that could be interpreted more than one way? | ### Decision Branches **All axes are clear:** Skip to Step 2. Do not ask any questions. **One or more axes are unclear:** Use **AskUserQuestion** to surface the ambiguities, following the "Step 1.5: Clarification Question Format" template in `references/templates..md` — use only the labeled subsection(s) for the axis/axes actually unclear, not all three unconditionally. For each unclear item, present specific answer choices (e.g., "(A) include JWT refresh in the same Issue / (B) split into a separate Issue"). Batch all unclear items into a single AskUserQuestion call (up to 4 questions); if more than 4 items are unclear, prioritize the ones with the highest impact on Issue scope. **Stop after calling AskUserQuestion. Do not proceed to Step 2 until the user has responded.** **User instructs to proceed with unresolved items:** Output the warning using the "Step 1.5: Warning Format" template in `references/templates..md`, then proceed to Step 2. Mark unresolved sections in Issue bodies with the confirmation tag defined in that template. Anything that stays unresolved after this step must **not** be silently decided later. Either it gets the confirmation tag, or it gets left out of the Issue entirely — never invented. --- ## Step 2: Structure Tasks and Dependencies Analyze the current conversation context (recent plans, investigations, TODO lists) and extract: **Epic (parent Issue)** - Title: one phrase that captures the entire work stream - Purpose: why this work is needed (background, motivation) - Scope: what is included in this Epic **Child Issue list** - **Hierarchy is at most three levels: Epic → `Tn` → `Tn.m`. A `Tn.m` is never a parent.** Every `Tn` is a leaf by default, carrying its own Requirements/Specs/Verification. When a `Tn` overflows the 5-bullet cap in Step 4, split it into a sibling `Tn` by default — for fragments the Epic-level reader would find independently interesting, or when there are only two. Split into `Tn.m` grandchildren instead only when three or more fragments share one cohesive theme already named by the original `Tn`. In that case `Tn` becomes a pure container: it drops its own Requirements/Specs/Verification and keeps only background, scope, and a dependency diagram of its `Tn.m` children — see Step 4's Container `Tn` body. A `Tn.m` is never split further; that overflow becomes a new sibling `Tn` instead. - Split each task into independently implementable and verifiable units - Assign each a short temporary ID: `T1`, `T2`, `T3`, ... (used only during this conversation; never shown to the end reader) - Title and a one-line summary of each task's role in the Epic - For each task, capture its **requirement bullets** (what must be true — observable/functional, no implementation detail) and its **spec bullets** (only if the conversation already settled concrete technical decisions). Cap each list at 5, one line each. - **The cap is a split signal, not a compression target.** If a task genuinely needs more than 5 bullets to describe — or, as shown at Step 4, more than 5 distinct verification scenarios (one happy path plus several failure/retry/rollback cases is a common trigger) — that is evidence the task is doing too much for one child Issue. Split it into more `Tn` (e.g. "happy path" vs "error handling / compensating recovery") rather than cramming everything into one Issue or silently dropping items to fit the cap. - Never write step-by-step procedures (`a→b→c→d`), pseudocode, or function-level implementation detail into these bullets. That level of detail belongs in a design doc, not an Issue body — reference it by path instead. **Dependency extraction** - For each `Tn`, list `depends_on: [Tm, ...]` based only on dependencies explicitly stated or clearly implied in the conversation (e.g., "merge A before starting B"). Do not infer a dependency that wasn't actually discussed. A statement that a task is merely independent of unrelated *existing* code (not another `Tn`) is not a `depends_on` entry — leave it out of the dependency list entirely; it's background/requirement framing at most. - A grandchild `Tn.m`'s `depends_on` may only reference sibling `Tn.m` under the same parent `Tn` — never a different `Tn`'s child, and never a `Tn` itself. If work genuinely depends on something in a different theme, that dependency belongs at the `Tn` level (the whole container depends on the whole other theme), not wired directly between grandchildren across trees. - Compute **waves** by topological order: Wave 1 = tasks with no dependencies; Wave *k* = tasks whose dependencies all fall in Wave 1..*k-1*. Tasks in the same wave can be implemented in parallel. - If a cycle is detected, treat it as an unresolved ambiguity and raise it via **AskUserQuestion** before continuing — do not silently break the cycle. - **If splitting a task per the cap rule above, and another `Tn` already depends on the task being split, re-wire that dependency**: point it at whichever new piece represents the completion of the original scope (usually the last piece in the split's natural sequence). If it's genuinely ambiguous which piece satisfies the original dependency, depend on all of the resulting pieces rather than guessing one. - A dependency **between the new pieces created by a split** (e.g., "error handling" depends on the "happy path" it wraps) may be inferred from the decomposition itself — this is not the kind of invented dependency the "do not infer" rule above is guarding against, since the pieces didn't exist as separate units in the conversation to begin with. - **The 12-task threshold above governs rendering only (Mermaid vs. table) — it says nothing about whether one Epic is still the right unit of work.** Separately: if the dependency graph splits into two or more fully independent connected components (no `depends_on` edge between them in either direction) and the total child count is large (rule of thumb: 15+), that's a sign the work may belong in separate Epics — one per component — rather than one Epic covering several unrelated parallel tracks. Don't decide this yourself: note it as a suggestion in the Step 3 summary (see template) and let the user choose. --- ## Step 3: Show Summary and Get Approval Use the "Step 3: Summary Format" in `references/templates..md`. This preview must show, per task: its `Tn` id, title, wave/dependency, one-line background, requirement bullets, spec bullets, one-line target state, and the full verification bullet list (up to 5) — plus a dependency preview keyed by `Tn` (real Issue numbers don't exist yet), and, for the Epic, its own one-line background and scope (included/excluded). **Apply the same 12-task threshold as the Epic body here**: a Mermaid flowchart for 12 or fewer tasks, the compact wave table for more — the user is approving the same structure that Step 4 will render, so the two must never diverge in form. This preview is allowed to be more detailed than the final Issue bodies — its job is to surface every piece of content that will end up in an Issue, so nothing new gets invented in Step 4. Because Step 4.5's full-body review is skipped by default (see Step 4.5), this is the substantive approval gate: it must carry enough detail that approving it is equivalent to approving the final bodies, not just their shape. **End your response here and wait for the user's reply.** **Do not proceed to Step 4 until approval is received.** If the user requests changes, update the summary (including the dependency graph and wave assignment if affected) and show it again before proceeding. --- ## Step 4: Generate Issue Bodies After approval, write the Markdown body for the Epic and each child Issue using the templates in `references/templates..md`. Use only content already approved in Step 3 — do not add, soften, or elaborate on requirements/specs while formatting. **Leaf Issues** — every non-container `Tn`, and every `Tn.m`: - Requirements section: the approved requirement bullets, verbatim in substance (may be copy-edited for clarity, not expanded). - Specs section: the approved spec bullets. Omit this section entirely if no technical decision was actually settled in the conversation — do not fill it with invented detail. - Dependencies section: one line referencing the sibling it depends on, or the template's "none" phrasing. Which parent it points to differs by level: - `Tn`: points to the Epic for the full dependency picture. - `Tn.m`: points to its parent `Tn`'s body instead — the Epic never shows grandchildren, per Step 2's dependency-scope rule. Don't restate the full dependency chain here; that lives only in the parent. - Acceptance Criteria section: concrete, verifiable statements equivalent to "Given X, When Y, Then Z", not vague phrases like "works correctly". Cap the Verification subsection at 5 items. If the real scenarios don't fit in 5, don't compress them: go back to Step 2, split this task into more siblings or grandchildren, and re-run Step 3 approval before writing bodies again. **Container `Tn`** — only when Step 2 promoted it: - No Requirements, Specs, or Acceptance Criteria section — those live only on its `Tn.m` leaves. - Background and Scope sections, same shape as the Epic's but scoped to this one theme: what the grouped `Tn.m` children cover. - Dependencies & Sub-tasks section: a small Mermaid `flowchart` grouping its own `Tn.m` children by wave, using `{{Tn.m}}` tokens. Past 12 grandchildren, use the wave table instead — same threshold as the Epic, rarely reached in practice. Scoped to this container only: never another `Tn`'s children, and the Epic's own diagram still shows this `Tn` as a single node, exactly like a leaf. **Epic:** - Dependencies & Parallel Execution Plan section: a Mermaid `flowchart` grouping child Issues into `subgraph` blocks per wave, using `{{Tn}}` tokens (double curly braces) everywhere a real Issue number will later be substituted — both in node labels and in any prose. **If there are more than 12 child Issues, replace the flowchart with the compact wave table** in `references/templates..md` instead — a graph that large stops being readable. - **Escaping in node labels:** if a title contains a double quote, write it as the entity code `#quot;` inside the `["..."]` label — never a raw `"` (it terminates the label) and never a backslash-escaped `\"` (Mermaid does not support backslash escaping and the diagram fails to render). Same rule applies to the Step 3 dependency preview. - This diagram is a rendering of the same `depends_on`/wave data that Step 5 also uses to set native GitHub blocked-by/blocking relations on each child Issue. Both are generated once, from the same approved data, in the same run — the diagram is a human-readable view, not a hand-maintained duplicate that can drift from the real relations after creation. Do not use any `{{Tn}}` or `{{Tn.m}}` token in a leaf body (a non-container `Tn`, or any `Tn.m`) — leaves stay abstract (`T1`, not `{{T1}}`) and are never rewritten after creation. Only the Epic body (`{{Tn}}` tokens) and a container `Tn`'s own body (`{{Tn.m}}` tokens for its own children only) get a substitution pass, both in Step 5. --- ## Step 4.5: Full Draft Review (only if requested) By default, skip this step: go straight from Step 3's approval to Step 4.6 validation and then Step 5, without re-displaying the generated bodies. Run this step only when the user explicitly asks to see the full draft before creation (e.g. "ドラフト見せて", "本文を確認したい", "show me the draft") — whether that request is part of their Step 3 approval reply or said earlier in the conversation. When triggered, use the "Step 4.5: Body Review Format" template in `references/templates..md` to display the Epic and all child Issues in order. Note explicitly that `{{Tn}}` tokens in the Epic body are placeholders that will be replaced with real Issue numbers (`#123`) once the child Issues exist. **Stop after presenting. Do not proceed to Step 4.6 until the user explicitly approves.** If the user requests changes, apply them and re-display the updated bodies before proceeding. --- ## Step 4.6: Automated Pre-Creation Validation Always run this step, whether or not Step 4.5 ran — it is the safety net that replaces routine human re-review of the mechanical formatting Step 4 performs. Check the generated bodies programmatically; there is no need to show them to the user unless a check fails: - Every leaf Issue's (non-container `Tn`, or any `Tn.m`) Requirements / Specs / Verification bullet lists stay within the 5-item cap. - No Mermaid node label (Step 3 preview, Epic body, or a container `Tn` body) contains a raw `"` — a title with a quote must use `#quot;` instead. - Leaf bodies never contain a `{{Tn}}` or `{{Tn.m}}` token — that substitution syntax is container-body-only (the Epic for its `Tn` tokens, a container `Tn` for its own `Tn.m` tokens). - Collect every `{{Tn}}` token appearing anywhere in the Epic body (diagram/table node labels, dependency-column references, prose) and confirm that set of ids exactly matches the set of `Tn` (leaf and container alike) about to be created — none missing, none referring to a `Tn` that doesn't exist. Separately, for each container `Tn`, collect every `{{Tn.m}}` token in its own body and confirm that set exactly matches the set of its own `Tn.m` grandchildren — none missing, none referring to a different container's child. A given id may legitimately appear more than once within its own scope (e.g. once as its own row, again in another row's dependency column), so check set membership, not occurrence count. If any check fails, stop, report the specific problem and its location to the user, and fix it before proceeding. Never silently patch it and never create Issues with a body known to be broken. --- ## Step 5: Create Issues See `references/commands.md` for the exact shell commands. **The Epic is created first**, since `--parent` needs it to already exist. Every `Tn` — leaf or container — is created next in wave order, each with `--parent $EPIC_NUM` and `--blocked-by `; never `--parent` pointing at another `Tn`, per the hierarchy rule in Step 2. A container `Tn`'s own body still carries unsubstituted `{{Tn.m}}` tokens at this point, since its grandchildren don't exist yet. Once every `Tn` exists, create each container's `Tn.m` grandchildren with `--parent` set to that `Tn`'s real number and `--blocked-by` limited to sibling `Tn.m` it depends on — never a `Tn`, never a different container's child, per Step 2's dependency-scope rule. Substitution then happens bottom-up: for each container `Tn`, substitute its own body's `{{Tn.m}}` placeholders with the real grandchild numbers and update it via `gh issue edit`, before touching the Epic. Only after every container is updated, substitute the Epic body's `{{Tn}}` placeholders — leaf and container alike — and update the Epic. Before each `gh issue edit`, confirm no token remains in that body's scope; if one does and the failure case below doesn't explain it, the substitution missed it — fix it before submitting. If a `Tn`'s creation fails, skip creating its would-be `Tn.m` grandchildren entirely — there is no valid parent for them — flag it in the Step 6 report, and replace its `{{Tn}}` reference in the Epic body with a short inline note such as "creation failed". If a `Tn.m`'s creation fails instead, its container is still created/updated normally; replace only that grandchild's `{{Tn.m}}` reference in the container's own body with the same note. Neither failure aborts the rest of the run. A failed `Tn`/`Tn.m` never gets a real number, so any not-yet-created sibling whose `depends_on` names it must drop that id from its own `--blocked-by` list — never pass a number that doesn't exist. Note the dropped edge in the Step 6 report so the user knows that dependency was never wired, rather than silently creating an Issue that was supposed to wait but isn't blocked on anything. Note in the completion report (Step 6) that the Epic's number is lowest, `Tn` numbers come next in wave order, and each container's `Tn.m` numbers come after their parent. --- ## Step 6: Report Completion Use the "Step 6: Completion Report" template in `references/templates..md`.