Skip to content
Get packs

Guide · Agent skill

How to use the Hotfix Emergency Workflow agent skill

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

The hotfix skill is a step-by-step emergency workflow for Claude Code. You run it with /hotfix when a serious bug is in a live build and needs fixing outside the normal sprint process. This guide explains what the skill makes the agent do, how to install it, how to start it, what it needs, and what to watch for before you deploy.

Hotfix Emergency WorkflowDonchitos/Claude-Code-Game-Studios · MIT

Quick start

  1. 1Download and unzip. Download the hotfix ZIP from this page and unzip it so the hotfix folder sits in ~/.claude/skills/ or in .claude/skills/ inside your project.
  2. 2Prepare your project. Make sure the project is a git repository and, if you can, set commands.test in project.yaml so the agent can run targeted tests.
  3. 3Start with /hotfix. Type /hotfix followed by the bug ID or a short description of the problem and its player impact.
  4. 4Confirm severity. Answer the severity question. S3 or lower sends you to the normal bug fix workflow and ends the hotfix flow.
  5. 5Approve branch and fix. Choose the base ref and approve the branch creation, then approve the proposed minimal fix before any code changes.
  6. 6Collect approvals and QA sign-off. Let the agent gather lead-programmer, qa-tester and producer sign-off, then pass the QA gate with smoke check or team-qa.
  7. 7Approve deployment. Only after the QA gate is met, approve the merge, patch tag and deploy step explicitly, or choose to merge to main only or stop.

What the hotfix skill makes the agent do

An agent skill is a folder with a SKILL.md file that tells the agent how to handle one kind of task. This skill covers urgent, serious bugs. It assesses severity, drafts a tracked hotfix record, and proposes a branch based on the release that contains the bug, not the latest main code.

The agent stops at several points and asks for your decision. It does not change code until you approve the proposed fix. It then requests sign-off from simulated lead-programmer, QA and producer roles, and checks QA evidence before any deployment.

  • Phase 1: assess severity as S1, S2 or S3 or lower
  • Phase 2: draft a hotfix record in production/hotfixes/
  • Phase 3: create a hotfix branch from the affected release
  • Phase 4: investigate and propose a minimal fix, then wait for approval
  • Phase 5 and 5b: collect approvals and pass a QA gate
  • Phase 6: ask again before merging, tagging or deploying

Install the hotfix skill

Download the ZIP for the skill from this page. The skill is listed as containing one file, SKILL.md. Unzip it so the hotfix folder sits in one of these locations: ~/.claude/skills/ for all your projects, or .claude/skills/ inside a single project.

If you use the Claude apps instead of Claude Code, open Settings, then Capabilities, then Skills, and upload the skill there.

  • Personal install: ~/.claude/skills/hotfix
  • Project install: .claude/skills/hotfix inside your project folder
  • Claude apps: Settings → Capabilities → Skills → upload

Run the skill with /hotfix

The skill only runs when you type /hotfix yourself. The source marks it as explicit invocation only, so a natural sentence such as 'we have a crash on load' will not start it on its own. Type /hotfix, then describe the bug or give its ID. The argument hint is [bug-id or description].

The agent will first ask you to confirm the severity it assessed. Answer that question before anything else happens, because the severity decides whether the emergency path applies at all.

  • Good: /hotfix crash on save in the inventory menu, players lose items
  • Good: /hotfix BUG-142 boss fight softlocks after phase 2
  • Not needed: minor typos or cosmetic issues, which go to the normal bug fix workflow
/hotfix

Understand the severity check and the approval points

Severity uses the scale from /bug-triage. S1 is a crash, data loss or complete feature failure where the game cannot proceed. S2 is a major feature broken while the game is still playable. S3 or lower means a degraded feature with a workaround, or a cosmetic issue. Choosing S3 or lower ends the hotfix flow and redirects you to the normal bug fix workflow.

Expect several pauses. The agent asks before it creates a branch, before it edits any code, before it runs the QA gate, and before merging or deploying. The source states that the deployment gate applies even in autonomous mode.

  • Branch creation needs your choice: create it, use a different base ref, or skip
  • Code changes need your approval of the proposed fix
  • Merge, tag and deploy need explicit approval every time

Check the hotfix record and QA gate before deploying

The hotfix record is a markdown file written to production/hotfixes/ after you approve. It holds the problem, root cause, fix, testing notes, approval checkboxes and a rollback plan. The agent records 'Tests: NOT RUN' with a reason if no test runner is configured or no test covers the change.

Before deploying, the agent asks qa-lead whether a smoke check is enough or a targeted team-qa pass is needed. A NOT ASSESSED result counts as unmet, not as a pass. If you choose to deploy anyway, the decision and the reason must be logged in the Testing section.

  • Smoke check: /smoke-check against the hotfix build
  • Targeted pass: /team-qa feature: [affected-system]
  • Full pass: /team-qa sprint, for S1 fixes that touch core systems
  • A FAIL sends the work back to the fix step and repeats the approvals
/smoke-check

Know what the skill needs and what it touches

The skill needs git, because it creates branches and looks up tags and release branches. It also works best with a project.yaml that sets commands.test, so the agent can run targeted tests. Setting commands.test is optional but recommended. The skill depends on other parts of the Claude Code Game Studios framework: the /bug-triage, /smoke-check and /team-qa skills, and the lead-programmer, qa-tester, producer and qa-lead agents. Without them the workflow will not run as designed.

On the safety side, the skill is listed as running scripts and not using the network. Its allowed git commands are limited to reading the repository, listing tags and branches, and creating a branch after you approve. It never uses the head of main as the base, because main may hold unreleased work.

  • Required: git
  • Recommended: project.yaml with commands.test set
  • Required framework pieces: /bug-triage, /smoke-check, /team-qa, lead-programmer, qa-tester, producer, qa-lead
  • Scripts: yes. Network: no
  • Base ref is the tag for the affected release or its release/* branch, not main
git rev-parse --is-inside-work-tree

Tips for using the skill well

Give a specific description of the player impact. The severity check and the hotfix record both depend on it. Keep the fix minimal: the skill is built to refuse refactors and feature work mixed into a hotfix. If you want a different base than the one proposed, choose the option to specify a base ref instead of accepting the default.

Read the proposed root cause carefully before approving. The approval is the audit trail, and the record is only as good as the decisions behind it.

  • Name the release the bug is in, so the base ref is correct
  • Check that commands.test runs the affected suite
  • Do not accept a NOT ASSESSED QA result as a pass without a logged reason
  • Keep rollback steps in the plan before deployment

What people use it for

  • A crash on load in a live build, rated S1, where the team needs a tracked patch with a documented rollback plan.
  • A boss fight that softlocks in the released version, rated S2, fixed on a branch from the affected release tag rather than from unreleased main work.
  • A save-data bug reported by a player, where the lead wants severity checked and approvals recorded before anything ships.
  • A studio using the Claude Code Game Studios setup that wants every emergency change to pass the same gated steps.

Frequently asked questions

Is the hotfix agent skill free to use?

The source lists the licence as MIT. It does not state any price, so check the download page for any terms that apply to your copy.

How do I install the hotfix skill in Claude Code?

Download the ZIP from this page and unzip it so the hotfix folder is in ~/.claude/skills/ for all projects, or in .claude/skills/ inside one project. In the Claude apps you can instead upload it under Settings, Capabilities, Skills.

Why doesn't the hotfix skill start when I describe a bug?

The skill is set to explicit invocation only. It runs when you type /hotfix. It does not auto-start from a natural sentence about a bug.

What do I need to run the hotfix skill?

You need git. A project.yaml with commands.test is optional but recommended. The workflow also depends on the /bug-triage, /smoke-check and /team-qa skills and the lead-programmer, qa-tester, producer and qa-lead agents from the Claude Code Game Studios framework.

Does the hotfix skill use the internet or run scripts?

The listing says it runs scripts and does not use the network. Its git commands are limited to reading the repository, listing tags and branches, and creating a branch after approval.

Can the hotfix skill fix minor or cosmetic bugs?

No. Bugs rated S3 or lower are redirected to the normal bug fix workflow. The skill is meant for S1 and S2 issues that need an emergency path.

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 this skill if you work in a game studio or team using the Claude Code Game Studios setup and need emergency patches to follow a documented, gated process with an audit trail. Pick something else if you need fully automatic fixes, if your project lacks the referenced agents and skills, or if your bug is minor, since the skill sends those to the normal workflow.

Download the skill