How do I install the Channel Adapter Pattern skill?

Run npx skillmds@latest add oimiragieo/channel-adapter-pattern in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Channel Adapter Pattern safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Channel Adapter Pattern?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Channel Adapter Pattern free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Channel Adapter Pattern?

oimiragieo (@oimiragieo) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Channel Adapter Pattern by oimiragieo

Name: Channel Adapter Pattern
Author: oimiragieo

Channel Adapter Pattern

Use when an agent's response/formatting logic is (or will be) reachable from more than one delivery channel (chat, SMS, email, push, web). Triggers — before adding a second channel to a single-channel agent, before writing/editing a shared respond()/format_reply()/persona-selection helper, or when a multi-channel agent's voice output sounds like it was written for text (spelled digits, markdown symbols read aloud).

oimiragieo fc67f9e 3.3 KB Updated Sep 17, 2026 0 repo stars

File contents

Channel-Adapter Pattern

Overview

Generate the reply in ONE canonical form; let a thin per-channel adapter at the edge shape it. A shared respond() helper that can't see which channel it's rendering for silently reuses whichever channel was coded first — so a voice channel inherits a chat channel's markdown and digits, and reads *asterisks* and "2:30" aloud.

When to use

Adding a second delivery channel to an agent built for one.
Writing/editing any shared respond() / format_reply() / persona-selection helper.
Voice/phone output sounds text-shaped: spelled numbers, markdown symbols, URLs read aloud.

The core rule

Thread an explicit medium/channel param through every shared response helper, and branch ONLY in a thin edge adapter — never in core agent/tool logic.

# core logic is channel-agnostic; the persona/format is chosen by medium
reply = await agent.respond(user_text, medium=medium)   # "voice" | "sms" | "web" | ...
# a per-channel adapter (send_outbound) does the final wire-format transform

Canonical format in, per-channel transform out. The agent produces text; the chat adapter returns it as-is; the voice adapter strips markdown + speaks numbers as words.
Adapter contract per channel: parse_inbound + send_outbound translating to/from a common envelope; keep formatting hints in the envelope metadata, not in the shared logic.
Per-channel latency/model-tier routing is an adapter decision, not a core-logic branch.

The grep-for-the-leak diagnostic

Enumerate EVERY caller of the shared helper. Any caller on a different channel that doesn't pass medium= is a latent leak. This is the root cause seen in production: a background job that called the shared response helper with no medium → defaulted to the text persona. Test the SAME helper across every channel adapter before shipping a new channel.

Common mistakes

Building the shared helper for channel #1, adding channel #2 later without a medium param → #2 inherits #1's shape.
Hardcoding medium="voice" inside a helper that is ALSO reached by the text gateway (verify the caller set first — shared classes must thread, not hardcode).
Branching core tool logic on channel instead of at the edge adapter.

Real-world impact

A support bot serving both a web widget and SMS shipped this exact bug: an SMS-side caller invoked the shared respond() helper with no medium= set, so it silently defaulted to the web persona — SMS output came out markdown-shaped with literal asterisks and unescaped links. The fix threaded medium="sms" explicitly into every SMS-side caller. This is the design-time partner to deliver-format-fallback (send-time 4xx recovery) and deliver-durably (crash-survivable delivery) — use all three together. Exa-confirmed against the 2026 "channel adapter pattern" (CallSphere, getwidget conversational-AI architecture).

---name: channel-adapter-patterndescription: Use when an agent's response/formatting logic is (or will be) reachable from more than one delivery channel (chat, SMS, email, push, web). Triggers — before adding a second channel to a single-channel agent, before writing/editing a shared respond()/format_reply()/persona-selection helper, or when a multi-channel agent's voice output sounds like it was written for text (spelled digits, markdown symbols read aloud).---# Channel-Adapter Pattern## OverviewGenerate the reply in ONE canonical form; let a thin per-channel adapter at the edge shape it. A shared `respond()` helper that can't see which channel it's rendering for silently reuses whichever channel was coded first — so a voice channel inherits a chat channel's markdown and digits, and reads `*asterisks*` and "2:30" aloud.## When to use- Adding a second delivery channel to an agent built for one.- Writing/editing any shared `respond()` / `format_reply()` / persona-selection helper.- Voice/phone output sounds text-shaped: spelled numbers, markdown symbols, URLs read aloud.## The core rule**Thread an explicit `medium`/`channel` param through every shared response helper, and branch ONLY in a thin edge adapter — never in core agent/tool logic.**```python# core logic is channel-agnostic; the persona/format is chosen by mediumreply = await agent.respond(user_text, medium=medium) # "voice" | "sms" | "web" | ...# a per-channel adapter (send_outbound) does the final wire-format transform```- Canonical format in, per-channel transform out. The agent produces text; the chat adapter returns it as-is; the voice adapter strips markdown + speaks numbers as words.- Adapter contract per channel: `parse_inbound` + `send_outbound` translating to/from a common envelope; keep formatting hints in the envelope metadata, not in the shared logic.- Per-channel latency/model-tier routing is an adapter decision, not a core-logic branch.## The grep-for-the-leak diagnosticEnumerate EVERY caller of the shared helper. **Any caller on a different channel that doesn't pass `medium=` is a latent leak.** This is the root cause seen in production: a background job that called the shared response helper with no medium → defaulted to the text persona. Test the SAME helper across every channel adapter before shipping a new channel.## Common mistakes- Building the shared helper for channel #1, adding channel #2 later without a medium param → #2 inherits #1's shape.- Hardcoding `medium="voice"` inside a helper that is ALSO reached by the text gateway (verify the caller set first — shared classes must thread, not hardcode).- Branching core tool logic on channel instead of at the edge adapter.## Real-world impactA support bot serving both a web widget and SMS shipped this exact bug: an SMS-side caller invoked the shared `respond()` helper with no `medium=` set, so it silently defaulted to the web persona — SMS output came out markdown-shaped with literal asterisks and unescaped links. The fix threaded `medium="sms"` explicitly into every SMS-side caller. This is the design-time partner to `deliver-format-fallback` (send-time 4xx recovery) and `deliver-durably` (crash-survivable delivery) — use all three together. Exa-confirmed against the 2026 "channel adapter pattern" (CallSphere, getwidget conversational-AI architecture).

Frequently asked questions