triage

Overview of triage skill

What triage does

triage is a GitHub issue-triage skill for moving incoming issues through a role-based state machine. It helps you classify reports, decide whether more information is needed, and route work to either an AFK agent or a human maintainer. If you need a triage skill for Issue Tracking, this is meant to reduce guesswork and keep issue handling consistent.

Who it fits best

Use the triage skill if you manage a busy issue queue, want a repeatable intake process, or need a structured way to turn messy bug reports into actionable work. It is especially useful when you need to separate bug from enhancement, then move each issue into needs-triage, needs-info, ready-for-agent, ready-for-human, or wontfix.

What makes it different

The main differentiator is the explicit state machine plus role discipline. The skill is not just “summarize the issue”; it expects exactly one category role and one state role, and it includes a hard requirement that every triage comment or issue message begin with a disclosure disclaimer. That matters if you need predictable outputs, policy-aware routing, and a triage workflow that can hand off cleanly to another agent.

How to Use triage skill

Install and first read

Install with:

npx skills add mattpocock/skills --skill triage

For the triage install, start with SKILL.md, then read AGENT-BRIEF.md and OUT-OF-SCOPE.md. Those files explain the durable brief format and how rejected ideas are recorded, which are the two parts most likely to affect real triage quality. The repo does not include helper scripts or extra reference folders, so those three files are the practical core.

Give the skill the right input

The triage usage works best when you provide the issue title, body, any existing labels, and the exact goal of the triage pass. Strong inputs tell the skill whether you want classification, more information, an agent brief, or a final rejection decision.

Good prompt shape:

• “Triage this GitHub issue. Classify it as bug or enhancement, choose the correct state role, and say whether it should go to an AFK agent or stay with a human.”
• “Here is the issue thread and current labels. Apply the triage state machine and draft the comment with the required disclaimer.”
• “This looks under-specified. Determine whether it belongs in needs-info or ready-for-agent, and explain the missing acceptance criteria.”

Use the workflow, not just the label

A practical triage guide is to treat the output as routing, not taxonomy. First confirm whether the issue is a bug or enhancement. Then check whether it is actionable, blocked on reporter input, or explicitly out of scope. If it is ready for agent work, the brief should describe behavioral expectations and acceptance criteria rather than file paths or implementation steps.

Watch the repository rules

Two details materially affect output quality: the disclaimer requirement and the “exactly one category role plus one state role” rule. If the issue’s state is ambiguous, the skill says to flag the conflict and ask the maintainer before changing anything else. That is the right moment to stop and clarify instead of forcing a label.

triage skill FAQ

Is triage only for GitHub issue labels?

No. The skill is built around GitHub-style issue tracking, but the core job is decisioning issue state and routing work. If your tracker uses different label strings, the canonical roles still matter, and you map them to your system before acting.

Do I need this if I can write a normal prompt?

A normal prompt can classify one issue, but the triage skill adds a repeatable state model, a brief-writing pattern, and explicit out-of-scope handling. That is valuable when you want consistent decisions across many issues, not one-off summaries.

Is triage beginner-friendly?

Yes, if you already understand basic issue labels. The triage skill is easier to use than writing a bespoke policy prompt because it tells you what states exist and what each transition means. The biggest beginner mistake is skipping the issue context and asking for a label with no body, no discussion, and no current state.

When should I not use triage?

Do not use triage for deep implementation planning or code review. It is for intake, routing, and readiness decisions. If the issue already has a full specification and you need design or coding help, a different skill or a direct implementation prompt is a better fit.

How to Improve triage skill

Provide richer issue context

The triage skill gets better when you include the full issue body, visible comments, current labels, and any maintainer notes. A bare title often leads to weak routing because the skill cannot tell whether the report is reproducible, already answered, or missing key details.

Ask for the decision you actually need

If your goal is “ready for agent,” say so. If your goal is “should this be closed as wontfix,” say that directly. The strongest triage usage is specific about the decision boundary, because the skill can then optimize for the right state instead of producing a generic summary.

Improve handoff quality

When an issue is moved to ready-for-agent, ask for an agent brief that states the behavior, constraints, and acceptance criteria in durable language. Avoid asking for file-level implementation instructions unless you truly need them; the repository guidance favors behavioral contracts because they survive codebase drift.

Iterate on the first pass

If the first triage pass is too tentative, refine it with one of three additions: reproduction steps, expected vs actual behavior, or why the issue matters to users. Those details often decide whether the issue belongs in needs-info, ready-for-human, or wontfix, and they make the triage skill more decisive on the second pass.