How to use the Oh My Issues Triage agent skill

What is an agent skill?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. The agent reads those instructions and follows the workflow they describe.

What the Oh My Issues skill makes the agent do

The skill treats a pile of GitHub issues as symptoms of a few underlying architectural defects. Instead of closing issues one at a time, the agent groups symptoms that one architectural change would fix into a cluster, gives each cluster a single plan-master issue with a design doc, and closes the children with a standard redirect comment.

It also handles two other jobs: preparing one pull request that closes all children of a cluster, and routing newly filed bugs into an existing plan as a "Round N" comment instead of opening new tracked issues.

• Cluster pass: reduce many open issues to a few plan masters, each named as an architectural problem
• Triage: match a new incoming bug against existing masters and append it to the right one
• Bundle: list a plan's children and prepare a PR whose description uses Closes #N for each child

Install the skill

Download the ZIP from this page and unzip it. You can install it for yourself across all projects or for a single repository.

For a personal install, unzip it into ~/.claude/skills/. For a project install, unzip it into the project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside the repository
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

The skill depends on the GitHub CLI and jq, and it needs write access to the repository. It makes network calls to GitHub. According to the skill's listing, it does not run scripts on its own; the commands it uses are GitHub CLI calls that the agent issues.

• GitHub CLI (gh) installed and authenticated
• jq installed, for parsing JSON output
• Write access to the repository's issues and pull requests
• Uses network: yes. Runs scripts: no

Trigger the skill with natural requests

You do not need a special command. Ask for the outcome in plain language and the agent will match the request against the skill's description. Phrases the skill is written to respond to include asking to triage, consolidate, cluster, dedupe or group issues, asking for a plan or roadmap built from open issues, and asking where a new bug belongs.

• "Triage the open issues in this repo and cluster them by root cause."
• "Consolidate our issue backlog into plan masters."
• "Make a plan series from the open issues."
• "A new bug came in about the installer failing on Windows. Does it belong to an existing plan?"
• "Build a PR that closes all the children of the spawn-contract cluster."

Understand the three modes

The skill has three modes. The cluster pass is for a backlog that has never been consolidated. Triage is for new bugs once consolidation is in place. Bundle is for shipping a cluster as one pull request.

In the cluster pass the agent reads every open issue's body and full comment thread, because reproduction steps often live in comments. It names each cluster with an architectural title, such as a title that states the fix rather than the topic, and mirrors each master as a plans/0X-slug.md design doc. The skill's target for about 100 issues is 4 to 8 masters.

• Cluster pass: read everything, cluster by root cause, open masters, close children as not planned, verify only masters remain open
• Triage: post a Round N comment on the matching master, close the new child as not planned
• Bundle: verify every child is covered, write the PR with Closes #N lines, add the plan's test matrix to CI

Read the backlog with the GitHub CLI

The skill uses GitHub CLI calls to list issues. It warns that a single gh issue list call does not return comment bodies, so comments must be fetched per issue. It also warns that an explicit --limit can silently truncate a large backlog, so the total open count is checked first. The skill's own commands look like this:

• gh issue list does not return comment bodies; use gh issue view <N> --json comments for each issue
• Check the total open count before setting --limit

Safety notes and when not to use it

The skill changes real issues and pull requests, so review what it proposes. The skill itself says that with fewer than about 15 open issues you should just close them. It also should not be used for genuinely independent bugs, because forced clustering is misleading. If the repository has no plans/ design-doc practice, the skill says to propose one and get agreement before introducing it.

Closing children as not planned is the skill's standard behaviour. Check the redirect comment and the master issue before you let the agent close anything.

• Not for repositories with fewer than about 15 open issues
• Not for projects with independent bugs
• Propose before introducing a plans/ practice
• Review each redirect and closure before it happens