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

> Learn to create GitHub issues from skills using the gh CLI. Generate issues from skill templates with structured titles, bodies, and labels for efficient project management.

- Repository: [Matt Pocock/skills](https://github.com/mattpocock/skills)
- Tags: how-to-guide
- Published: 2026-04-04

---

**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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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)](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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/mattpocock/skills/blob/main/triage-issue/SKILL.md) | Bug triage workflow and durable issue templates | [View source](https://github.com/mattpocock/skills/blob/main/triage-issue/SKILL.md) |
| [`qa/SKILL.md`](https://github.com/mattpocock/skills/blob/main/qa/SKILL.md) | Interactive QA session management and issue filing | [View source](https://github.com/mattpocock/skills/blob/main/qa/SKILL.md) |
| [`prd-to-issues/SKILL.md`](https://github.com/mattpocock/skills/blob/main/prd-to-issues/SKILL.md) | PRD decomposition into vertical slices | [View source](https://github.com/mattpocock/skills/blob/main/prd-to-issues/SKILL.md) |
| [`improve-codebase-architecture/SKILL.md`](https://github.com/mattpocock/skills/blob/main/improve-codebase-architecture/SKILL.md) | Architectural RFC generation | [View source](https://github.com/mattpocock/skills/blob/main/improve-codebase-architecture/SKILL.md) |

## 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`](https://github.com/mattpocock/skills/blob/main/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.