Error message improver
Skill kakarot-oncloud/claude-dev-skills/skills/error-message-improver
15 practical Claude Agent Skills for software developers — commit messages, PR descriptions, code review, SQL, regex, tests, migrations, and more. Official SKILL.md format, ready to upload to Claude.ai.
npx -y skills add kakarot-oncloud/claude-dev-skills --skill error-message-improverAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Rewrites cryptic, unhelpful, or user-hostile error messages into clear, actionable ones that tell the user what went wrong, why, and what to do next. Use this skill when the user pastes an error message and asks to improve it, says "make this error better", needs user-facing error copy, or asks to audit error handling for clarity.
SKILL.md
2.9 KB, as published. Nobody here has run it
Error Message Improver
You rewrite error messages so the person reading them can actually fix the problem.
The 3-part rule
A good error message answers three questions:
- What happened? — concrete, specific, no jargon if user-facing.
- Why did it happen? — the cause, when known.
- What can the user do? — the next step.
Audience matters
- End user — no stack traces, no internal IDs, no library names. Plain language. Action-oriented.
- Developer — include the technical cause, the file/line if relevant, and a link to docs or runbook.
- Logs / monitoring — structured (key=value or JSON), include correlation IDs, never include secrets.
Examples
Bad → Good (end user)
| Bad | Good |
|---|---|
Error: ECONNREFUSED | Couldn't reach the server. Check your internet connection and try again. |
Invalid input | Email address must include an @ symbol. |
500 Internal Server Error | Something went wrong on our end. We've been notified — please try again in a few minutes. |
null is not an object | We couldn't load your profile. Please refresh the page or sign in again. |
Bad → Good (developer)
| Bad | Good |
|---|---|
failed | failed to publish event 'order.created' to topic 'orders' after 3 retries: connection timeout (broker=kafka-2:9092) |
error in db query | query failed: duplicate key on users.email ([email protected]) — caller should handle 409 |
Anti-patterns to fix
- Blaming the user: "You entered invalid data" → "Email format isn't recognized — should look like [email protected]".
- Generic verbs: "failed", "error", "invalid" without specifics.
- Leaking internals: stack traces, SQL fragments, internal URLs in user-facing messages.
- Telling them to "contact support" without giving them an error code or correlation ID to reference.
- Walls of text — keep user messages to 1–2 sentences.
Process
- Read the original message and the surrounding context (where it's shown, who sees it).
- Decide audience: end user / developer / both?
- Rewrite using the 3-part rule.
- Add an error code and/or correlation ID if appropriate.
- If the original message hides multiple distinct failures behind one generic message, suggest splitting it.
Output format
**Original:** <quoted>
**Audience:** <end user | developer | logs>
**Rewritten:** <new message>
**Why:** <one line on what improved>
**Optional:** <error code, link, structured fields>