Skip to content
Get packs

Guide · Agent skill

How to use the Bug Triage agent skill (bug-triage)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Bug Triage skill is an agent skill for Claude Code that reads your game project's bug reports, separates how bad each bug is (severity) from how urgently it must be fixed (priority), and writes a dated triage report. It is written for game studios and solo developers using the Claude Code game-studios template who keep bugs as markdown files. By the end of this guide you will know what the skill does, how to install it, how to trigger it with plain requests, and where its limits are.

Bug TriageDonchitos/Claude-Code-Game-Studios · MIT

Quick start

  1. 1Download the ZIP. Download the bug-triage skill ZIP from the skill page on this site.
  2. 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into your project's .claude/skills/ folder for one project.
  3. 3Check your bug files. Make sure bug reports exist in production/qa/bugs/*.md, or in the fallback files the skill names.
  4. 4Run the skill. Type /bug-triage sprint, /bug-triage full or /bug-triage trend in Claude Code.
  5. 5Review the report. Open production/qa/bug-triage-[date].md and check the priorities and assignments.
  6. 6Act on the recommendations. Fix P1 bugs before QA hand-off and investigate any flagged hot-spot systems.

What is an agent skill and what does bug-triage do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to carry out a specific task. When you ask for that task, the agent follows the instructions in the file. This skill is named bug-triage and its description is: re-evaluate open bugs, covering priority vs severity, sprint assignment and systemic trends, to be run when the bug count grows.

When a game project's bug list grows, the skill makes the agent read the bug reports and produce a triage report at production/qa/bug-triage-[date].md. The report ranks bugs into P1 to P4 priority levels, assigns fixable P1 and P2 bugs to the current sprint where capacity allows, and flags patterns such as several bugs in one system or regressions in stories already marked complete.

  • Severity: S1 Critical, S2 High, S3 Medium, S4 Low, based on impact on the game.
  • Priority: P1 fix this sprint, P2 fix soon, P3 backlog, P4 won't fix or deferred.
  • Trend mode: a read-only analysis with no assignments.

How do you install the bug-triage skill?

Download the ZIP from the skill page on this site, then unzip it. You can install the skill in one of two places. For all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead of Claude Code, you can upload the skill under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/ (available across projects).
  • Project install: .claude/skills/ inside your project folder.
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP.

What does your project need before you run it?

The skill only works on markdown bug files. It looks for individual reports in production/qa/bugs/*.md first. If that folder is missing, it falls back to a single log at production/qa/bugs.md, and then to a Bugs Found table in any production/qa/qa-plan-*.md file.

It also runs a helper script, hooks/yaml-helper.sh, to read project configuration, so you need a bash shell. Optional files are .claude/docs/automation-modes.md and project.yaml, which control how much the agent asks before writing. Sprint files in production/sprints/ let the skill assign bugs to the current sprint. Without them, it assigns bugs to the backlog only.

  • Claude Code or a compatible SKILL.md agent.
  • Bug reports in production/qa/bugs/*.md (or the fallback files).
  • A bash shell.
  • Optional: .claude/docs/automation-modes.md and project.yaml.

How do you trigger the skill with a natural request?

You can invoke the skill with a slash command and an optional mode: sprint, full or trend. If you give no argument, the skill runs sprint mode when a current sprint exists, and full mode otherwise. You can also describe what you want in ordinary words, such as asking the agent to triage the open bugs against the current sprint.

Run the skill when the bug count grows. The skill's own guidance suggests running it at sprint start, after QA has filed new bugs, or once there are more than 10 open bugs.

  • /bug-triage sprint: assign fixable bugs to the sprint backlog and defer the rest.
  • /bug-triage full: triage every bug regardless of sprint scope.
  • /bug-triage trend: analysis only, a read-only report.
  • Natural request: "Triage our open bugs against this sprint and flag any regressions."
/bug-triage sprint

What does a triage run look like?

The skill first loads the bug backlog, then the most recently modified file in production/sprints/ for sprint context. It classifies each bug by severity and priority, checks for systematic problems, and then writes the report. In sprint and full modes it re-evaluates priority against severity for each bug.

The deviation check flags three kinds of pattern: three or more bugs from the same system in one sprint, two or more S1 or S2 bugs in the same story, and a bug filed against a story marked Complete. The report ends with recommended actions, usually starting with fixing P1 bugs before QA hand-off.

  • Three or more bugs from one system in one sprint: possible design or implementation quality issue.
  • Two or more S1/S2 bugs in one story: the story may need reopening before shipping.
  • Bug against a Complete story: regression, so the story should be reopened in sprint tracking.

What safety and control points should you know?

This skill runs scripts, specifically hooks/yaml-helper.sh, and it can write and edit files. It does not use the network. Its output is a local report, but the skill may also edit files, so review what it produces before relying on it. It does not change your issue tracker.

Automation mode is set in your project configuration. In collaborative mode the agent asks before each write. In guided mode it asks only about major changes. In autonomous mode it logs its actions and proceeds. Check the report and any edited files before you act on them.

  • Runs scripts: yes (hooks/yaml-helper.sh).
  • Uses network: no.
  • Writes a local report and may edit files.
  • Automation mode is set in project configuration: collaborative, guided or autonomous.

What tips improve the triage results?

Keep one bug per file in production/qa/bugs/ so the skill can read each report cleanly. Bold the header fields, such as **Severity**, **System** and **Status**, because the trend search matches those bolded labels. Keep your sprint file current so the skill can see capacity and story scope.

Do not use this skill on a very small backlog. Under about 10 bugs the overhead adds little value.

  • Use one bug per markdown file in production/qa/bugs/.
  • Bold the field labels so the trend search can find them.
  • Keep the sprint file in production/sprints/ up to date.
  • Use trend mode for a quick, read-only health check.

What people use it for

  • Preparing sprint planning by building a prioritised list of bugs for the next sprint.
  • Checking a backlog for regressions in stories already marked complete.
  • Finding which system has the most open bugs or the highest share of S1/S2 bugs.
  • Running a quick read-only trend check before a milestone with /bug-triage trend.
  • Spotting aged high-severity bugs that have sat unassigned for more than two sprints.

Frequently asked questions

Is the bug-triage skill free to use?

The skill is released under the MIT licence, as stated on this page. Check the licence file in the source repository for the full terms.

What do I need to run bug-triage?

You need Claude Code or a compatible SKILL.md agent, a bash shell, and bug reports as markdown files in production/qa/bugs/. Optional project.yaml and automation-modes.md files control its behaviour.

Can bug-triage read bugs from Jira or GitHub Issues?

No. The skill only reads markdown files in production/qa/. If your bugs live in Jira or GitHub Issues, it will find nothing to triage.

How do I install bug-triage in Claude?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills.

What is the difference between severity and priority in this skill?

Severity measures how bad the bug's impact is, from S1 Critical to S4 Low. Priority measures how urgently it must be fixed, from P1 fix this sprint to P4 won't fix. A bug can be severe but low priority, or minor but urgent.

Will bug-triage change my bug tracker or fix the bugs for me?

It does not change any tracker, and it does not use the network. It writes a local report and may edit files, so review its output before relying on it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use bug-triage if you run a game project with the Claude Code game-studios template and track bugs as markdown files in production/qa/, especially when the backlog has grown past about 10 bugs. Pick something else if your bugs live in Jira or GitHub Issues, or if you want an agent that updates your tracker automatically.

Download the skill