Go Package Debugger skill for Claude and Codex
A root-cause diagnosis for a Go package that will not compile, panics, or misbehaves: the likely cause ranked by evidence, the fix with before-and-after code…
Install it once and Claude or Codex runs it for you. When your request matches, your AI loads the skill, asks for anything it is missing, and works through the template itself. Prefer to fill it in by hand? See the full prompt template.
Download the skill (.zip) · View SKILL.md
When it is used
Use when a Go package fails to compile, panics with a stack trace, deadlocks, or fails the race detector and the user needs the root cause and the fix. Do not use for general Go code review or performance profiling of code that already works. Related topics: coding, package.
What it will ask you for
- Package import path (free text, e.g. "github.com/acme/app/internal/billing")
- Go version (choose one: 1.21, 1.22, 1.23, 1.24)
- Target OS and architecture (choose one: linux/amd64, linux/arm64, darwin/arm64, windows/amd64)
- Observed symptom (choose one: Compile error, Panic at runtime, Wrong output, Hangs or deadlocks, Race detector report, Test failure)
- Error output (longer free text)
- Relevant code (longer free text)
- What you expected (free text, e.g. "One sentence")
- Level of detail (choose one: Brief, Moderate, Thorough)
- Include test command snippets (choose one: Yes, No)
How it works
- Extract the failing file, line, and frame from the compiler output or stack trace before reading the code, so the diagnosis starts where the runtime says.
- Classify the failure and name the most likely root cause with its supporting evidence, plus one alternative when the evidence is ambiguous.
- Write the fix as a before-and-after code change that keeps Go idioms: errors returned, no recover to hide bugs, no sleeps around races.
- List the go build, go vet, and go test commands that prove the fix, with the -race flag for concurrency bugs and the expected output.
- Add the test snippet that would have caught the bug when test commands are requested, and trim the write-up to the chosen level of detail.
What you get
A markdown report with sections Summary, Root cause (with evidence), Fix (before and after code), Verify (commands and expected output), and Prevent (one or two lines), sized to the selected detail level.
What it watches out for
- Blaming the line that panicked when the nil was created several frames earlier, which fixes a symptom and leaves the bug.
- Wrapping the crash in recover or adding a nil check without finding why the value was nil.
- Ignoring GOOS and GOARCH, so a build-tag or cgo problem that only shows on the target platform is missed.
How to install
Claude.ai and the Claude desktop app
- Download the skill .zip.
- Open Settings, then Capabilities, and find Skills.
- Choose Upload skill and select the .zip.
- Ask Claude for help with the task. It loads the skill when your request matches.
Claude Code
- Download the skill .zip.
- Unzip it into ~/.claude/skills/ (or .claude/skills/ inside a project).
- Start a new session. Claude Code loads the skill when your request matches.
Codex
- Download the skill .zip.
- Unzip it into ~/.agents/skills/ (or .agents/skills/ inside a project).
- Codex picks it up on its own. Type $ and the skill name to use it, or just ask for the task.
Cursor
- Download the Cursor rule (.mdc).
- Save it in .cursor/rules/ inside your project.
- Cursor's agent applies the rule when your request matches its description.
AGENTS.md (Codex, Cursor, and other coding agents)
- Copy the AGENTS.md section.
- Paste it into AGENTS.md at the root of your repository, creating the file if needed.
- Coding agents that read AGENTS.md follow it when your request fits.