Skip to main content
skill CX Codex

qa-to-issues — Claude Code skill: what it does, how to install

qa-to-issues runs an interactive QA session to turn reported bugs into durable GitHub issues. The agent asks quick clarifying questions, checks your codebase, and files tickets.

Apache-2.0 ★ 173 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sammcj/agentic-coding --skill qa-to-issues -a claude-code
Open on GitHub

What qa-to-issues does

The skill runs a conversation-driven QA session. You describe an issue in plain terms, and the agent asks up to three targeted questions covering expected behavior, reproduction steps, and failure consistency. In the background, an Explore subagent inspects the repository and consults UBIQUITOUS_LANGUAGE.md to pick up project terminology.

Before filing, it evaluates whether to create a single issue or split the report into smaller parallel tickets. Issue bodies intentionally omit line numbers and file paths, keeping tasks valid after refactoring. Tickets are posted straight to GitHub with gh issue create without pausing for draft approval.

Without a configured and logged-in GitHub CLI (gh) in your environment, creating issues will fail immediately.

What it helps with

  • file structured GitHub issues directly through chat
  • break down multi-part bugs into smaller tickets with blocker links
  • document reproduction steps using domain terms instead of internal file paths

Example prompts for the agent

  • Start a QA session, I found a few bugs while testing checkout
  • The login redirect is broken, let's file an issue for it
  • Let's run a QA review of the export feature and log tickets

How to install qa-to-issues

1Skills CLI (Vercel)

npx skills add sammcj/agentic-coding --skill qa-to-issues -a claude-code

2Manually: put the files in place

~/.claude/skills/qa-to-issues/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/qa-to-issues/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about qa-to-issues

How do I install qa-to-issues in Claude Code?

Run npx skills add sammcj/agentic-coding --skill qa-to-issues -a claude-code. Alternatively, place the skill file into ~/.claude/skills/qa-to-issues/SKILL.md.

Why does qa-to-issues avoid file paths in generated issues?

It focuses on user-facing behavior rather than implementation details. This ensures issues remain clear and actionable even if code is moved or refactored later.

What prerequisites does qa-to-issues require?

You must have the GitHub CLI (gh) installed and authenticated. The skill relies directly on gh issue create to submit tickets to your repository.

Source text

SKILL.md · Apache-2.0
---
name: qa-to-issues
description: Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Use when user wants to report bugs in their own codebase and create Github issues conversationally
metadata:
  source: https://github.com/mattpocock/skills
---

# QA Session

Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language.

## For each issue the user raises

### 1. Listen and lightly clarify

Let the user describe the problem in their own words. Ask **at most 2-3 short clarifying questions** focused on:

- What they expected vs what actually happened
- Steps to reproduce (if not obvious)
- Whether it's consistent or intermittent

Do NOT over-interview. If the description is clear enough to file, move on.

### 2. Explore the codebase in the background

While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to:

- Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
- Understand what the feature is supposed to do
- Identify the user-facing behavior boundary

This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details.

### 3. Assess scope: single issue or breakdown?

Before filing, decide whether this is a **single issue** or needs to be **broken down** into multiple issues.

Break down when:

- The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken")
- There are clearly separable concerns that different people could work on in parallel
- The user describes something that has multiple distinct failure modes or symptoms

Keep as a single issue when:

- It's one behavior that's wrong in one place
- The symptoms are all caused by the same root behavior

### 4. File the GitHub issue(s)

Create issues with `gh issue create`. Do NOT ask the user to review first — just file and share URLs.

Issues must be **durable** — they should still make sense after major refactors. Write from the user's perspective.

#### For a single issue

Use this template:

```
## What happened

[Describe the actual behavior the user experienced, in plain language]

## What I expected

[Describe the expected behavior]

## Steps to reproduce

1. [Concrete, numbered steps a developer can follow]
2. [Use domain terms from the codebase, not internal module names]
3. [Include relevant inputs, flags, or configuration]

## Additional context

[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files]
```

#### For a breakdown (multiple issues)

Create issues in dependency order (blockers first) so you can reference real issue numbers.

Use this template for each sub-issue:

```
## Parent issue

#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"

## What's wrong

[Describe this specific behavior problem — just this slice, not the whole report]

## What I expected

[Expected behavior for this specific slice]

## Steps to reproduce

1. [Steps specific to THIS issue]

## Blocked by

- #<issue-number> (if this issue can't be fixed until another is resolved)

Or "None — can start immediately" if no blockers.

## Additional context

[Any extra observations relevant to this slice]
```

When creating a breakdown:

- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable
- **Mark blocking relationships honestly** — if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None — can start immediately"
- **Create issues in dependency order** so you can reference real issue numbers in "Blocked by"
- **Maximize parallelism** — the goal is that multiple people (or agents) can grab different issues simultaneously

#### Rules for all issue bodies

- **No file paths or line numbers** — these go stale
- **Use the project's domain language** (check UBIQUITOUS_LANGUAGE.md if it exists)
- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws on line 42"
- **Reproduction steps are mandatory** — if you can't determine them, ask the user
- **Keep it concise** — a developer should be able to read the issue in 30 seconds

After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?"

### 5. Continue the session

Keep going until the user says they're done. Each issue is independent — don't batch them.

© sammcj · Apache-2.0 · sammcj/agentic-coding

Similar skills

All skills for Testing and QA →

From the same set73

The whole set →
diagrams-as-code diagrams-as-code is a Claude Code skill that creates architecture and infrastructure diagrams with Python’s diagrams library. It turns code-defined schemes into image files. CX Codex +1 ★ 173repo stars liteparse liteparse extracts text and structure from PDF, DOCX, PPTX, XLSX and images to markdown locally, no cloud or LLM required. CX Codex +1 ★ 173repo stars analyse-design The analyse-design skill examines an app, website, or document’s code and screenshots to map its design system. Use it to audit UI consistency or guide new components. CX Codex +1 ★ 173repo stars invokeai-image-gen invokeai-image-gen — a skill for generating images via local InvokeAI API, supporting FLUX.2 Klein, Z-Image Turbo, and SDXL. Auto-detects models and applies appropriate parameters, saves output as PNG. CX Codex +1 ★ 173repo stars systematic-debugging systematic-debugging — a structured debugging skill for stubborn bugs that survived several fixes. It traces symptoms to root causes before proposing code changes. CX Codex +1 ★ 173repo stars personal-genomics personal-genomics runs pharmacogenomics, disease-risk, carrier and trait checks on raw DNA files, entirely offline — one array export or several sources merged into a single report. CX Codex +1 ★ 173repo stars markedit-tools markedit-tools manages the MarkEdit markdown editor on macOS: installs updates, handles extensions, and edits settings via Claude Code. CX Codex +1 ★ 173repo stars raspberry-pi-pico2 Get guidance on building and debugging Raspberry Pi Pico 2 projects with the Pi Debug Probe. Useful for RP2350, SDK configuration, OpenOCD, and GDB. CX Codex +1 ★ 173repo stars

Project sponsors

Companies that keep this analytics open