When to use this
- A bug report says something like "sometimes X breaks" with no clear steps.
- Before attempting a fix for anything non-trivial -- reproduce first, fix second.
- Not needed when the bug already has a clean, minimal repro attached -- go straight to root-cause-analyzer.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: bug-reproducer description: Turn a vague or incomplete bug report into a minimal, deterministic reproduction case, narrowing from the full report down to the smallest input/steps that reliably trigger it. Use before attempting a fix, when a report lacks clear repro steps. --- # Bug Reproducer A bug you can't reliably reproduce is a bug you can't verify you've fixed. This is the step that makes every downstream step (root cause, fix, regression test) actually trustworthy. ## Process 1. Extract every concrete detail from the report: exact error message, environment, data involved, sequence of actions, and *anything* the reporter considered irrelevant but mentioned anyway -- it often isn't. 2. Attempt the most literal reproduction first, using the exact steps described, before guessing at variations. 3. If it doesn't reproduce immediately, vary one dimension at a time: data shape, timing, concurrency, environment/config -- and track what you've ruled out, not just what you've tried. 4. Once it reproduces, narrow it: remove every part of the repro that isn't necessary to trigger the bug, until you have the smallest possible case. 5. Confirm determinism: run the minimal repro multiple times. If it's intermittent, that's important information for root-cause-analyzer, not a reason to give up narrowing it. ## Output The minimal repro steps/code, the exact observed behavior vs. expected behavior, and a note on determinism (always reproduces / reproduces N/M times / conditions that seem to matter).
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /bug-reproducer.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Giving up after the first reproduction attempt fails and jumping straight to guessing at a fix.
- Stopping at a reproduction that works but is far larger/more complex than necessary -- narrow it, it pays off in every later step.
- Discarding a detail from the original report as "probably irrelevant" without actually testing that assumption.