error-message-improver
Skill0 starsChanged 7 months agoMITView on GitHub
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.
In this repository14 other files it gives its agents.
- api-designerSkill
- bug-report-formatterSkill
- changelog-writerSkill
- code-reviewerSkill
- commit-message-writerSkill
- dependency-upgraderSkill
- dockerfile-doctorSkill
- env-var-auditorSkill
- migration-plannerSkill
- pr-description-writerSkill
- readme-generatorSkill
- regex-builderSkill
- sql-query-expertSkill
- test-generatorSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 52
Read the original message and the surrounding context (where it's shown, who sees it).
- Distinctive: line 55
Add an error code and/or correlation ID if appropriate.
- Distinctive: line 56
If the original message hides multiple distinct failures behind one generic message, suggest splitting it.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 (value=alice@example.com) — caller should handle 409 |
Anti-patterns to fix
- Blaming the user: "You entered invalid data" → "Email format isn't recognized — should look like name@example.com".
- 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>Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.