How to Create GitHub Issues from Skills Using the `gh` CLI

You can create GitHub issues from skills by invoking gh issue create with a structured title, body file, and labels, following the declarative templates defined in each skill's SKILL.md file.

The mattpocock/skills repository (Instagit) treats GitHub issue creation as a built-in operation. Every skill that transforms user insights into tracked work items follows a standardized four-step pattern to create GitHub issues from skills using the gh CLI, ensuring durable, refactor-resistant tickets without manual review loops.

The Four-Step Issue Creation Pattern

Each skill in the repository follows the same execution flow when converting conversations into GitHub issues:

1. Gather context – Collect the user’s description, domain-specific language, and any related PRDs or code references.
2. Compose a durable body – Write the issue in plain, user-focused language using the skill’s <issue-template> block, deliberately omitting file paths or line numbers.
3. Invoke the GitHub CLI – Execute gh issue create with the generated title, body file, and appropriate labels.
4. Report the URL – Return the newly created issue URL to the user immediately for follow-up.

This pattern appears consistently across the repository’s SKILL.md files, from bug triage to architectural refactoring.

Where the gh Command Is Defined

The actual CLI invocation is specified in the "Process" section of each skill’s documentation. Here are the key locations:

Skill	Purpose	GitHub Issue Creation Step
triage-issue	Converts bug reports into TDD-oriented fix plans	[triage-issue/SKILL.md (lines 57-60)](https://github.com/mattpocock/skills/blob/main/triage-issue/SKILL.md#L57-L60)
qa	Files problems discovered during interactive QA sessions	[qa/SKILL.md (lines 47-50)](https://github.com/mattpocock/skills/blob/main/qa/SKILL.md#L47-L50)
prd-to-issues	Splits PRDs into independent vertical-slice tickets	[prd-to-issues/SKILL.md (lines 52-55)](https://github.com/mattpocock/skills/blob/main/prd-to-issues/SKILL.md#L52-L55)
improve-codebase-architecture	Opens refactor RFCs as tracked issues	[improve-codebase-architecture/SKILL.md (lines 76-78)](https://github.com/mattpocock/skills/blob/main/improve-codebase-architecture/SKILL.md#L76-L78)

Architectural Principles

Declarative Templates

Each skill ships with an <issue-template> block that defines the exact markdown structure required. The agent fills placeholders for sections like "Problem," "Root Cause Analysis," and "Acceptance Criteria," then passes the completed markdown to gh.

Durability First

The templates enforce a critical constraint: they explicitly forbid file paths or line numbers. Instead, they reference modules and behaviors so the issue remains relevant after major refactors. This rule is codified at [lines 71-77 of triage-issue/SKILL.md](https://github.com/mattpocock/skills/blob/main/triage-issue/SKILL.md#L71-L77).

Labels and State Management

Skills apply semantic GitHub labels to categorize work. Common labels include bug, enhancement, and ready-for-agent. The CLI receives these via the --label flag, allowing immediate triage without human intervention.

No Human Review Loop

All skills are designed to file issues immediately and share the URL. As documented in every SKILL.md, the instruction is clear: "Do NOT ask the user to review before creating." This reduces friction and encourages fast feedback cycles.

CLI-Only Integration

The skills never invoke custom scripts or API wrappers. They rely solely on the official GitHub CLI (gh), which is guaranteed to be present in the execution environment.

Code Examples

Basic Bug Report (triage-issue)

This pattern creates a TDD-oriented issue with a bug label:

cat <<'EOF' > /tmp/issue-body.md

## Problem

The UI crashes when the user clicks “Save”.

## Root Cause Analysis

The save‑handler attempts to write to a nil pointer after a recent refactor.

## TDD Fix Plan

1. **RED** – Write a failing test for the save path.
2. **GREEN** – Guard the pointer before dereferencing.
3. **REFACTOR** – Extract helper to simplify the handler.
EOF

gh issue create \
  --title "UI crashes on Save" \
  --body-file /tmp/issue-body.md \
  --label bug

PRD Vertical Slice (prd-to-issues)

Use this when breaking down product requirements into actionable slices:

cat <<'EOF' > /tmp/slice-body.md

## Parent PRD

#1234

## What to build

Implement the "Export CSV" vertical slice – end‑to‑end flow from UI button to storage file.

## Acceptance criteria

- [ ] Export button appears on the reports page.
- [ ] Clicking the button triggers a download of a correctly‑formatted CSV.
- [ ] Errors are shown as a toast notification.

## Blocked by

None - can start immediately

## User stories addressed

- User story 7 (Export data)
EOF

gh issue create \
  --title "Export CSV – vertical slice" \
  --body-file /tmp/slice-body.md \
  --label enhancement \
  --label ready-for-agent

Refactor RFC (improve-codebase-architecture)

For architectural changes, create an RFC-style issue:

cat <<'EOF' > /tmp/rfc-body.md

## Motivation

Current authentication module tightly couples HTTP transport to business logic, making unit testing hard.

## Proposed change

Introduce an `AuthPort` interface and an in‑memory adapter for tests; keep the HTTP adapter for production.

## Impact

- Existing auth handlers will depend on the new port.
- Test suites can mock the port without network calls.

## Acceptance criteria

- [ ] All auth unit tests run with the in‑memory adapter.
- [ ] Production builds still use the HTTP adapter.
EOF

gh issue create \
  --title "Refactor authentication into a deep module" \
  --body-file /tmp/rfc-body.md \
  --label enhancement \
  --label ready-for-agent

Key Implementation Files

File	Role	Direct Link
triage-issue/SKILL.md	Bug triage workflow and durable issue templates	View source
qa/SKILL.md	Interactive QA session management and issue filing	View source
prd-to-issues/SKILL.md	PRD decomposition into vertical slices	View source
improve-codebase-architecture/SKILL.md	Architectural RFC generation	View source

Summary

• Create GitHub issues from skills using the gh CLI by calling gh issue create with --title, --body-file, and --label flags.
• Each skill in mattpocock/skills follows a four-step pattern: gather context, compose a durable body, invoke the CLI, and report the URL.
• Issue templates forbid file paths and line numbers to ensure refactor resistance.
• Skills apply labels like bug, enhancement, and ready-for-agent automatically.
• No human review is required before creation; the agent files immediately and returns the issue URL.

Frequently Asked Questions

What flags are required when using gh issue create in these skills?

You must provide --title and either --body or --body-file. The skills prefer --body-file to pass multi-line markdown content. Optional --label flags categorize the issue according to the skill’s template.

Why do the issue templates avoid specific file paths and line numbers?

As specified in triage-issue/SKILL.md (lines 71-77), omitting file paths ensures the issue remains useful after code refactors. Referencing modules and behaviors instead of specific locations prevents technical debt in the issue tracker itself.

Can I modify the labels applied by a skill?

Yes. The labels are determined by the skill’s logic before invoking the CLI. You can adjust the --label arguments passed to gh issue create within the SKILL.md process definition, or add multiple labels by repeating the flag.

Does the user review the issue before it gets created?

No. According to the repository’s design principles, skills must not ask for user review before creating the issue. The agent creates the issue immediately and reports the URL, enabling fast feedback cycles without blocking on human approval.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}