When to use this
- A crash/exception needs explaining, especially through unfamiliar framework or library internals.
- A stack trace points into third-party or generated code and the real cause is somewhere in application code that called it.
- Not needed for a trace whose cause is already obvious from the top frame -- don't over-explain the trivial cases.
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: stack-trace-explainer description: Explain a stack trace by identifying the actual application-code frame responsible (not just the top frame, which may be deep in a library), the call path that led there, and the specific state that would produce this exact exception. Use for confusing or framework-heavy traces. --- # Stack Trace Explainer ## Find the real frame The top frame is often inside a library, framework, or runtime -- not where the actual bug is. Walk down the trace to find the deepest frame that's in *this codebase's* code; that's usually where the actual mistake was made, even if the exception is thrown several frames deeper. ## Reconstruct the call path Read each frame from the application-code frame down to the throw point, and explain in plain language what sequence of calls led there -- "handler X called service Y with argument Z, which passed it to library function W without checking for null, which threw here." ## State the specific triggering condition Don't just restate the exception type/message -- explain the *state* that had to be true for this specific trace to occur (e.g. "this NullPointerException happens because `config.retries` was never set, which only happens when the config loader falls back to defaults, which only happens when the config file path is wrong"). ## Output Plain-language explanation of the failure, the responsible application- code line, and (if asked) a suggested fix -- distinct from just pasting the trace back with annotations.
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 /stack-trace-explainer.
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.
- Explaining only the top frame when it's deep in framework/library code and the real application-code cause is several frames down.
- Restating the exception message without explaining the actual state/condition that produced it.
- Guessing at the cause without actually reading the source at the responsible frame.