Guide · Agent skill
How to use the Bug Reproduction Brief agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Bug Reproduction Brief skill is an agent skill for AI coding assistants that turns a vague, intermittent, or environment-specific bug report into a minimal, observed failure. It is useful when someone says 'it sometimes fails' or 'only works on my machine'. After reading this guide you will know what the skill makes the agent do, how to install it, how to ask for it in plain language, and what to check before trusting its output.
Bug Reproduction Briefgithub/awesome-copilot · MIT Download the skill Quick start
- 1Download the ZIP. Get the bug-reproduction-brief ZIP from this page.
- 2Unzip into a skills folder. Place the bug-reproduction-brief folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 4Describe the bug. Give the agent the failing test, route or command, plus any known input and environment.
- 5Ask for reproduction only. State that you do not want a fix yet and ask for the smallest safe failing fixture.
- 6Review the brief. Check the evidence, repeat counts and unknowns before starting diagnosis.
What an agent skill is and what this one does
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when a task matches the skill's description. This skill's description is: turn a vague, intermittent, or environment-specific bug report into a minimal evidence-backed reproduction before proposing a fix.
When it is used, the agent works through a fixed sequence. It records the exact observed failure, identifies the environment using only facts it can inspect, writes explicit expected and actual behaviour, reduces the reproduction by removing unrelated data, services and steps, and checks that the failure repeats. The output is a brief with a fixed set of fields.
- Record the exact error, incorrect output, timestamp, affected route or command, and smallest known input.
- Record environment facts such as repository and commit, runtime versions, operating system or container, lockfile, and feature flags.
- Write Expected and Actual as two observable statements, without the suspected cause.
- Reduce the case to the smallest fixture that still fails, and run it at least twice where safe.
- Stop before repair. The skill tells the agent not to edit implementation code.
Install the skill from the ZIP download
Download the ZIP for bug-reproduction-brief from this page. The skill is distributed as a folder whose main file is SKILL.md. Unzip it so that the bug-reproduction-brief folder, with SKILL.md inside, sits in the right skills location.
For a personal install, put it in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder. Either way, the skill folder should contain SKILL.md directly.
- Personal: ~/.claude/skills/bug-reproduction-brief/
- Project: .claude/skills/bug-reproduction-brief/ inside your repository
- Alternative: in the Claude apps, go to Settings → Capabilities → Skills and upload the skill there.
~/.claude/skills/bug-reproduction-brief/SKILL.mdHow to trigger the skill with a natural request
You do not need a special command. Describe the bug and say that you want the reproduction done first. The source's own example asks the agent to use the skill, to avoid fixing yet, and to report evidence.
Be specific about what you want back: the exact command, the expected result, the actual result, and the unknowns. If the bug is only in one environment, say which one.
- Name the failing test, route or command you have.
- Say explicitly 'do not fix it yet' so the agent stops after reproduction.
- Ask for the smallest safe failing fixture rather than a production reproduction.
Use the Bug Reproduction Brief skill on the failing checkout test. Do not fix it yet. Reduce it to the smallest safe failing fixture and report the exact command evidence, expected result, actual result, and remaining unknowns.Safety notes: scripts, network and production data
This skill does not run scripts and does not use the network, according to its listing. It requires nothing beyond the agent and the skill files. The agent still runs whatever commands your project's tests or scripts require, so review what it executes in your environment.
The skill advises against reproducing against production. It says not to change production data merely to reproduce a bug, not to publish secrets or customer records, and to use read-only or reversible discovery first. It also says not to guess credentials or production configuration.
- Runs scripts: no. Uses network: no. Requires: nothing listed.
- Avoid production data; prefer an isolated test, minimal script, or smallest safe request.
- Logs are to be kept free of secrets and personal data.
Tips for getting a useful brief
The skill works best when the bug report is genuinely unclear. If you already have a clear stack trace and known steps, a direct debugging request may be quicker.
If the failure is intermittent, expect the brief to report observed frequency and duration rather than calling the bug deterministic. Treat any suggested cause as a hypothesis to test, not a conclusion, because the skill says not to claim root cause from correlation alone.
- Give the agent second-hand reports too; the skill marks them as unverified.
- Ask for the brief's output format, which lists Target and commit, Environment, Expected, Actual, Minimal steps, Minimal fixture, Reproduced, Evidence, Unknowns and Safe next hypothesis.
- Run the repair as a separate task once the reproduction is verified.
What people use it for
- Triaging a bug report that says 'it sometimes fails' and needs a repeatable case.
- Reproducing a failure that only happens in one environment, such as a particular runtime or container.
- Reducing a failing test to its smallest safe fixture before anyone proposes a fix.
- Documenting a failing request with exact error, expected and actual behaviour for a teammate.
Frequently asked questions
How do I install the bug-reproduction-brief skill?
Download the ZIP from this page and unzip it so the bug-reproduction-brief folder with SKILL.md sits in ~/.claude/skills/ for personal use or .claude/skills/ inside a project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What does the Bug Reproduction Brief skill require?
The listing says it requires nothing beyond the agent itself. It does not run scripts and does not use the network, though the agent may run your project's own test commands.
Is the bug-reproduction-brief skill free?
It is published under the MIT licence, as stated on this page. Check the licence text in the source repository for the full terms.
Will the skill fix the bug for me?
No. The skill instructs the agent to stop once the failure is verified and not to edit implementation code. Diagnosis and repair are meant to be separate workflows.
Can the agent reproduce bugs against production?
The skill advises against it, because changing production data to reproduce a bug can harm real customers. It prefers an isolated test, minimal script or smallest safe request.
Why isn't the skill triggering for my request?
Make sure the folder contains SKILL.md directly and is in the correct skills location. Then describe a vague, intermittent or environment-specific bug and say you want the reproduction done first, so the request matches the skill's purpose.
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 when a bug report is unclear, intermittent, or tied to one environment and you want evidence before anyone guesses a cause. Skip it for simple bugs with a clear stack trace and known steps, where the extra process adds little value.
Download the skill