github-triage

Overview of github-triage skill

What github-triage does

The github-triage skill helps an agent triage GitHub issues using a strict label-based state machine instead of ad hoc issue comments. It is designed for repositories that want consistent intake, clearer issue status, and a reliable handoff when an issue becomes ready for implementation.

Who this skill is for

This github-triage skill is best for maintainers, repo operators, and AI-assisted contributors who need to:

• review incoming bugs and feature requests
• decide whether an issue is actionable
• request missing information without losing the thread
• prepare issues for an AFK coding agent
• keep issue labels consistent across a repo

If your real problem is “our issues are messy and nobody knows what is ready,” this skill is a strong fit.

The real job to be done

For most teams, triage is not just labeling. The harder job is turning vague reports into one of a few durable states:

• needs maintainer review
• needs reporter clarification
• ready for an agent
• ready for a human
• not going to be done

github-triage is useful because it treats issue tracking as a workflow, not just a comment-writing task.

What makes github-triage different

The main differentiator is that github-triage enforces two parallel labels on every issue:

• exactly one category label, such as bug or enhancement
• exactly one state label, such as needs-triage or ready-for-agent

That sounds simple, but it materially improves GitHub issue tracking because it prevents ambiguous states and forces a clearer next action.

Why users adopt it

The strongest reason to install github-triage is not automation alone. It is the combination of:

• a defined state machine
• interactive “grilling” to gather missing details
• a durable agent-brief workflow for implementation handoff
• optional institutional memory through .out-of-scope/ records

Those pieces give maintainers something more structured than a generic “please triage this issue” prompt.

Important constraints before you install

This skill assumes a GitHub-centered workflow and explicitly expects use of gh for GitHub operations. It also assumes your repo can support a controlled label taxonomy. If your repository already has a large, conflicting label system and no appetite for cleanup, adoption will be harder than the skill itself.

How to Use github-triage skill

Install context for github-triage

In a Skills-based setup, install github-triage from the mattpocock/skills repository:

npx skills add mattpocock/skills --skill github-triage

After installation, open these files first:

• SKILL.md
• AGENT-BRIEF.md
• OUT-OF-SCOPE.md

That reading order matters: first understand the state machine, then the agent-handoff contract, then the rejection-memory pattern.

What github-triage needs as input

The github-triage skill works best when the agent has:

• the current repository context
• access to git remote so it can infer the repo
• access to gh for reading and updating issues
• the current label set in the target repository
• the issue number or issue list to triage

Without label access and GitHub CLI access, you lose most of the practical value.

Start by checking label readiness

Before using github-triage at scale, confirm your repo has the expected labels:

Category labels

• bug
• enhancement

State labels

• needs-triage
• needs-info
• ready-for-agent
• ready-for-human
• wontfix

The key rule is that each issue should have exactly one category and exactly one state label. If your repo lacks these labels, create or map them first.

The core github-triage workflow

A practical github-triage usage flow looks like this:

1. identify the target issue
2. inspect existing labels for conflicts or missing state/category labels
3. read the issue body and discussion
4. decide whether the issue is:
   • clearly actionable
   • missing information
   • out of scope
   • better for a human than an AFK agent
5. ask focused follow-up questions if needed
6. apply one category label and one state label
7. if ready for an agent, write a structured agent brief

That last step is where this skill becomes more valuable than ordinary issue sorting.

How to prompt github-triage well

A weak prompt:

• “Triage issue #142.”

A stronger prompt:

• “Use github-triage for issue #142 in the current repo. Check for conflicting labels first, classify it as exactly one category and one state, identify missing information if any, and if it is implementation-ready, draft a durable agent brief with testable acceptance criteria.”

Why this is better:

• it tells the agent to validate label state first
• it asks for a classification decision, not just commentary
• it makes the handoff artifact explicit

Turn rough maintainer intent into a complete request

Good maintainers often know the outcome they want but not the prompt shape. Here is a stronger template for github-triage usage:

• “Review issue # with github-triage. Determine whether this is a bug or enhancement, choose the correct state label, ask no more than 5 clarifying questions if information is missing, and recommend ready-for-agent, ready-for-human, or wontfix with reasoning.”

This works because it narrows the decision surface while leaving room for the skill’s workflow.

Use the grilling step carefully

The skill mentions interactive grilling sessions. In practice, that means asking for the minimum missing information needed to move the issue forward. Good grilling is:

• specific
• bounded
• tied to a state transition

For example, ask for:

• reproduction steps
• expected vs actual behavior
• environment details
• API shape or UX expectation
• acceptance criteria

Do not ask broad “tell me more” questions if the issue only needs one missing detail to move from needs-info to ready-for-agent.

How agent briefs should be written

When an issue moves to ready-for-agent, github-triage expects an agent brief that is durable and behavior-oriented. Based on AGENT-BRIEF.md, the brief should:

• define the desired behavior, not implementation steps
• avoid file paths and line numbers
• include concrete, testable acceptance criteria
• act as the authoritative spec, even if the issue discussion is noisy

This is one of the most useful parts of the github-triage guide, especially for issue tracking workflows that hand off work asynchronously.

When to use the out-of-scope knowledge base

If a feature request is repeatedly rejected, github-triage for Issue Tracking becomes more effective when paired with .out-of-scope/ documents. This is useful when maintainers want to:

• avoid re-debating old decisions
• preserve rationale after issue closure
• quickly spot duplicate requests

Create one file per concept, not one file per issue. That turns past decisions into reusable project memory.

Files to read before changing the workflow

Read these files in order if you want to adapt the skill instead of just invoking it:

1. SKILL.md for the label model and triage flow
2. AGENT-BRIEF.md for what “ready-for-agent” really means
3. OUT-OF-SCOPE.md for persistent rejected-request handling

This is the shortest path to understanding how the repo expects issue triage to produce stable outcomes.

Best-fit workflow patterns

github-triage works especially well for:

• repos with frequent inbound issues
• teams using AI agents for implementation
• maintainers who want consistent labels and comment structure
• issue queues where “needs more info” is common

It is less compelling for tiny repos with very low issue volume or teams that already enforce a different, mature issue operations system.

github-triage skill FAQ

Is github-triage only for large repositories?

No. Small repos can benefit too, especially if one maintainer is overwhelmed by inconsistent issue intake. But the biggest gains appear when enough issues arrive that labels and handoff quality start to matter.

Is github-triage beginner-friendly?

Yes, if you already understand basic GitHub labels and issues. The github-triage skill is opinionated, but not technically heavy. The main learning curve is adopting its state machine consistently.

How is github-triage different from a normal prompt?

A normal prompt might summarize an issue or suggest labels. github-triage adds a structured workflow:

• explicit label rules
• conflict checking
• clarification logic
• a defined ready-for-agent handoff artifact
• optional out-of-scope memory

That structure reduces guesswork and keeps triage outputs more consistent across issues.

Do I need GitHub CLI to use github-triage?

For practical use, yes. The skill explicitly expects gh for GitHub operations. Without it, you can still mimic the reasoning, but you lose the direct issue-reading and label-management workflow that makes the skill operationally useful.

When is github-triage a poor fit?

Skip github-triage if:

• your team does not want a strict state label model
• your repo uses a very different label taxonomy with no desire to map it
• you only want freeform discussion, not controlled triage
• your issues rarely progress to agent handoff

In those cases, a lighter custom prompt may be enough.

Does github-triage replace maintainers?

No. The skill helps maintainers standardize decisions, gather missing information, and prepare issues for execution. It does not remove the need for judgment about scope, roadmap, or product direction.

How to Improve github-triage skill

Give github-triage a cleaner operating environment

The fastest way to improve github-triage results is to clean up your labels first. The skill is strongest when the repo has:

• no duplicate state labels
• no overlapping meanings between states
• clear category labels
• agreed definitions for ready-for-agent and ready-for-human

If your labels are messy, the output will feel uncertain because the workflow itself is uncertain.

Provide stronger issue context up front

The skill performs better when the issue already includes useful signal such as:

• reproducible steps
• expected and actual behavior
• screenshots or logs
• version and environment details
• a clear feature request outcome

This reduces unnecessary grilling and makes the state decision more reliable.

Ask for decisions, not summaries

One common failure mode is prompting github-triage to “review” an issue without asking for a state transition. Better prompt framing:

• ask for the exact category label
• ask for the exact state label
• ask whether the issue is ready for agent, human, more info, or rejection
• ask for a brief justification

That produces outputs you can act on immediately.

Improve the quality of ready-for-agent handoffs

If github-triage marks something ready-for-agent, inspect the brief for these weaknesses:

• procedural instructions instead of behavior specs
• references to fragile file paths
• vague acceptance criteria
• no edge cases or failure conditions

A stronger brief should survive repo drift and still tell an agent what success looks like.

Use narrower clarification questions

Another common failure mode is over-questioning. Improve the skill’s output by directing it to ask only questions that unblock the next state change. For example:

• good: “What exact error message do you see?”
• weak: “Can you describe the issue in more detail?”

Specific questions make needs-info issues easier to resolve.

Add and maintain out-of-scope memory

If your project repeatedly rejects the same classes of requests, maintaining .out-of-scope/ content makes github-triage more useful over time. This improves consistency, speeds up triage, and preserves rationale for future maintainers.

Review first-run outputs for state drift

When adopting github-triage install in a real repo, review the first batch of triaged issues for:

• missing category labels
• multiple state labels
• overuse of needs-info
• premature ready-for-agent
• inconsistent wontfix reasoning

These are adoption signals, not just output problems. Fix the policy, then reuse the skill.

Iterate by tightening your prompt contract

If the first output is too loose, do not just ask for “more detail.” Refine the prompt contract. Example:

• “Re-run github-triage on issue #142. Keep exactly one category and one state label, propose at most 3 clarifying questions, and only mark ready-for-agent if you can write acceptance criteria that are independently testable.”

That kind of constraint improves reliability more than asking for a longer answer.

Decide your repository-specific thresholds

The most important improvement is agreeing on what qualifies for each state in your repo. github-triage gives you a framework, but your team should define thresholds such as:

• when a bug has enough reproduction detail
• when an enhancement is specific enough for implementation
• when something is truly out of scope
• when human judgment is required over agent execution

Once those thresholds are explicit, the github-triage skill becomes much more consistent and valuable.