Purpose
Turn a raw technical integration description into a clear, multi-level explainer that speaks to developers, architects, and executives without rewriting the whole thing three times by hand. Solves the recurring Solutions Engineering problem of a single integration story landing well with one audience and confusing the other two.
When to Use
Invoke this skill when the user asks to:
- Explain how a specific integration works to a mixed room of engineers and business stakeholders
- Produce partner-facing documentation for an API, webhook, or data sync integration
- Turn a technical spec or architecture into a readable explainer at a chosen depth
- Create an executive summary and a developer deep-dive for the same integration
- Prepare integration talking points for a sales engineering or partner enablement call
- Translate an internal integration design into external-ready documentation
Inputs Required
Before starting, collect:
- Integration description: What systems connect and what the integration accomplishes (2–5 sentences or a spec)
- Integration pattern: How data moves — REST API, webhooks, event stream, batch/file sync, iPaaS/middleware, direct DB, or SDK
- Systems involved: The named products/platforms on each side (source, destination, any middleware)
- Data and direction: What data flows, one-way or bidirectional, and roughly what volume/frequency
- Auth and security model: OAuth, API keys, mTLS, SSO, etc.
- Target audience level: Developer / Architect / Executive / All three
- Business outcome: The problem this integration solves for the end customer
If the audience level is missing, generate all three levels. If auth or volume details are missing, note the assumption inline and keep the explainer valid without them.
Instructions
Step 1: Extract the Integration Backbone
Before writing any audience-specific text, distill the integration into a reusable core:
- The one-sentence summary: "System A sends [data] to System B when [trigger] so that [outcome]."
- The trigger: What initiates the flow (user action, schedule, event, threshold)
- The path: The ordered hops the data takes from source to destination
- The transformation: What changes to the data in transit (mapping, enrichment, filtering, format conversion)
- The failure mode: What happens when a step fails (retry, dead-letter, alert, manual reconcile)
This backbone is the single source of truth — all three audience levels describe the same system, only the altitude changes.
Step 2: Write the Developer Level
Audience: implementing engineers. They need to build against or debug this.
- Lead with the integration pattern and protocol (e.g., "Outbound webhook, POST with HMAC-signed payload").
- Include a request/response shape described in prose or a sample JSON structure — endpoints, key fields, status codes.
- Cover authentication mechanics concretely (token exchange, header names, scopes).
- Describe error handling and retries: retry policy, idempotency keys, timeout behavior, dead-letter path.
- Note rate limits, pagination, and edge cases if relevant.
- Vocabulary: unrestricted technical terms; assume API literacy.
Step 3: Write the Architect Level
Audience: solution and enterprise architects. They need to evaluate fit, risk, and scale.
- Lead with the system topology: which components own which responsibilities and where the boundary lines are.
- Address data flow and consistency: sync vs. async, eventual vs. strong consistency, source of truth.
- Cover scalability and volume: throughput ceilings, how it degrades under load, coupling risk.
- Cover security and compliance posture: auth model, data residency, PII handling, audit trail.
- Cover reliability: single points of failure, failover, observability hooks.
- Vocabulary: architecture-level terms (idempotency, backpressure, coupling) — no code-level detail.
Step 4: Write the Executive Level
Audience: business stakeholders and decision-makers. They need to know what it does and why it matters.
- Lead with the business outcome in plain language — no product names in the first sentence if avoidable.
- Use one analogy that maps the integration to a familiar real-world process.
- State what the customer experiences as a result (faster onboarding, no manual entry, real-time visibility).
- Note effort and risk at a high level (low-lift standard integration vs. custom build) without jargon.
- Keep it to 3–5 short paragraphs; zero acronyms unless immediately defined.
Step 5: Produce a Diagram Description for Each Level
For each audience level, write a text description of the accompanying diagram the reader should picture or that a designer can render:
- Developer: sequence-style — labeled requests/responses between named endpoints, left to right.
- Architect: component/topology — boxes for systems and middleware, arrows labeled with data + direction, trust boundary marked.
- Executive: simplified flow — three or four boxes with plain-language labels and a single directional arrow.
Step 6: Build the Shared Glossary and FAQ
- Glossary: 6–10 terms used across the levels, each with a one-line plain definition.
- FAQ: 5–7 questions a mixed audience actually asks (e.g., "Is this real-time?", "What happens if a message fails?", "Does data leave our environment?"), answered at a neutral middle depth.
Output Format
- Structure: Backbone summary → Developer level → Architect level → Executive level → Diagram descriptions (one per level) → Glossary → FAQ
- Length: 1,100–1,600 words total; Developer 300–450, Architect 300–450, Executive 150–250
- Format: Structured document with clear H2 section headers per audience level; sample payloads and glossary as formatted lists
- Sections: Integration Backbone; Developer Explainer; Architect Explainer; Executive Explainer; Diagram Descriptions; Glossary; FAQ
- Tone: Solutions engineer explaining to a colleague — precise and confident at the developer/architect levels, warm and jargon-free at the executive level
Quality Checklist
Before delivering output, verify:
- [ ] All three audience levels describe the same integration backbone — no contradictions in trigger, path, or direction
- [ ] The developer level includes a concrete payload/endpoint shape and an explicit error/retry behavior
- [ ] The executive level contains zero undefined acronyms and exactly one analogy
- [ ] Each of the three levels has its own matching diagram description
- [ ] The glossary has 6–10 terms and the FAQ has 5–7 questions
- [ ] Any missing input (auth, volume) is handled with a stated assumption, not a bracket placeholder
Notes
- The most common failure is the developer level leaking into the executive level — if an executive paragraph names a protocol, rewrite it.
- When the integration is bidirectional, describe each direction separately at the developer level but combine them at the executive level.
- If the source spec is thin, prioritize getting the trigger and the failure mode right — those two are what audiences ask about most and what generic explainers skip.
- For partner-facing use, the architect level is usually the highest-value section; it's where deals stall on unanswered risk questions.
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