Purpose
Transform dense technical troubleshooting information — engineering notes, developer docs, error explanations, or internal knowledge-base entries — into clear, customer-facing language that a non-technical user can follow and act on, without losing any factual accuracy. Solves the recurring gap between what engineering writes and what a customer can actually understand.
When to Use
Invoke this skill when the user asks to:
- Rewrite a technical support article or troubleshooting doc for customers
- Turn an engineer's explanation of a bug or fix into a customer-facing reply
- Simplify a dense error message or system behavior into plain language
- Convert internal knowledge-base content into a public help-center article
- Make a technical concept understandable for non-technical end users
- Reduce jargon in a support macro or canned response without dumbing it down
Inputs Required
Before starting, collect:
- Source content: The technical text to simplify (docs, notes, error output, or transcript)
- Audience technical level: Non-technical / semi-technical / power user
- Delivery format: Support reply, help-center article, in-app message, or knowledge-base entry
- Product context: What the product is and the relevant feature or system involved
- Goal for the reader: What the customer should understand or do after reading
- Constraints: Length limits, brand voice, or terms that must be kept exact (e.g., button names, error codes)
If audience level or format is missing, default to non-technical audience and support-reply format, and note the assumption.
Instructions
Step 1: Extract the Core Facts
Read the source and separate the load-bearing facts from the technical scaffolding.
- List every claim the customer actually needs: what happened, why, what to do, and what to expect
- Flag anything ambiguous or unstated in the source — do not invent a cause or fix to fill a gap
- Mark terms that must stay exact (error codes, menu labels, version numbers, filenames)
Step 2: Identify Jargon and Assumed Knowledge
Scan for language that assumes technical background:
- Jargon: acronyms, internal system names, protocol names, dev shorthand
- Assumed knowledge: steps that skip context a non-technical reader wouldn't have
- Abstractions: "the request times out" → what the customer actually sees and experiences For each item, decide: replace with plain language, keep and define inline, or cut if it doesn't help the reader act.
Step 3: Rebuild in Plain Language
Rewrite using these rules:
- Lead with the outcome, not the mechanism — tell the customer what this means for them first
- Analogy where useful: use a concrete real-world comparison only when it clarifies, never when it distorts
- Second person, active voice: "You'll see..." not "The user is presented with..."
- One idea per sentence; short paragraphs; steps as numbered lists
- Define exact terms once: keep the precise term, add a plain-language gloss in parentheses on first use
- Target a Grade 7–9 reading level for non-technical audiences
Step 4: Add What the Source Left Implicit
Non-technical readers need context engineers omit:
- Why this happens — a one-line reason so the fix feels logical, not arbitrary
- What to expect — how long a step takes, what a successful result looks like
- Reassurance where warranted — whether data is safe, whether the issue is common Only add context that is true and inferable from the source. Never fabricate causes or guarantees.
Step 5: Structure for Scanning
Organize the output so a stressed customer can find their answer fast:
- Open with a one-sentence summary of the situation and resolution
- Use numbered steps for actions, bold for what to click or type
- Add a short "If this doesn't work" fallback line when relevant
- Close with what success looks like
Step 6: Accuracy Validation Pass
Compare the rewrite against the source, claim by claim:
- Every fact from Step 1 is present and unchanged in meaning
- No exact term (error code, label, version) was altered or dropped
- No new claim, cause, or guarantee was introduced that the source doesn't support
- Simplification removed difficulty, not correctness
Output Format
- Structure: One-line summary → plain-language explanation → numbered action steps → what-to-expect / fallback
- Length: 120–350 words depending on complexity, plus a short "Terms translated" note listing jargon swaps
- Format: Structured prose with numbered lists; scannable, not a wall of text
- Sections: Summary line → Explanation → Steps → Expected result → Terms translated (jargon → plain language table)
- Tone: Calm, direct, and reassuring — like a knowledgeable person explaining it to a friend, never condescending
Quality Checklist
Before delivering output, verify:
- [ ] Every core fact from the source is present in the rewrite (check against the Step 1 list)
- [ ] No exact terms (error codes, labels, versions) were changed or dropped
- [ ] No cause, fix, or guarantee appears that isn't supported by the source
- [ ] Reading level matches the target audience (Grade 7–9 for non-technical)
- [ ] Every jargon term is either replaced, defined inline, or listed in the terms-translated note
- [ ] Action steps are numbered and specify exactly what the customer clicks or types
Notes
- The most common failure is accuracy drift — simplifying by rounding off a caveat that actually matters. When in doubt, keep the caveat and phrase it plainly rather than cutting it.
- Analogies are powerful but risky: a good analogy clarifies one specific point; a bad one implies things about the system that aren't true. Use them narrowly.
- If the source itself is unclear or contradictory, surface that to the user rather than smoothing it over — a confident but wrong customer explanation creates more tickets than it prevents.
How to use this skill
This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.
Installing in Claude Code:
~/.claude/skills/<folder-name>/SKILL.md— auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)<your-project>/.claude/skills/<folder-name>/SKILL.md— auto-loads only when working in that project (recommended for project-specific skills)
Restart Claude Code or open a new session to register.
Using in Claude.ai, ChatGPT, Gemini, or other AI tools:
- Drag this file into a new chat, or copy and paste its contents
- Send your task or request as your next message — the AI will apply the skill where it fits
For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills