---
name: tts-script-converter
description: "Converts any written content — documents, reports, reference guides, markdown files, research extractions, meeting notes, structured data, or any formatted text — into a fully optimized, linear audio script for Text-to-Speech applications such as Speechify, ElevenLabs, OpenAI TTS, Google Cloud TTS, Amazon Polly, and Murf. Handles full pipeline: table linearization, header-to-signpost conversion, abbreviation expansion, markdown stripping, number normalization, pacing punctuation, and verbatim accuracy preservation. Use when the user wants to convert written content to audio, create a listenable version of a document, make a TTS-friendly script, produce an audio script, or prepare any text for voice narration. MANDATORY TRIGGERS: TTS, text to speech, audio script, Speechify, ElevenLabs, audio-friendly, listenable, voice script, spoken format, TTS conversion, narration script, convert to audio, TTS format, read aloud, podcast script, voice narration."
argument-hint: [file or content to convert] [optional: target TTS platform]
---

# TTS Script Converter

Converts any written content into a fully optimized, linear audio script for Text-to-Speech playback. The output must sound natural when read aloud by an AI voice engine — no markdown noise, no table artifacts, no ambiguous symbols, no abbreviation mispronunciations.

## Table of Contents

1. [Core Conversion Pipeline](#1-core-conversion-pipeline)
2. [The Seven Transformation Rules](#2-the-seven-transformation-rules)
3. [Platform-Specific Adjustments](#3-platform-specific-adjustments)
4. [Content Type Handling](#4-content-type-handling)
5. [Output Format and Delivery](#5-output-format-and-delivery)
6. [Quality Checklist](#6-quality-checklist)
7. [Bundled Resources](#7-bundled-resources)


## 1. Core Conversion Pipeline

Apply these steps in order on every conversion job:

1. **Inventory** — Scan the source for all tables, code blocks, headers, lists, abbreviations, special characters, URLs, file paths, and numbers.
2. **Transform** — Apply all seven transformation rules (Section 2) to the full document.
3. **Signpost** — Insert spoken section transitions at every former header location.
4. **Validate** — Run the quality checklist (Section 6) before delivering output.
5. **Deliver** — Output as a clean `.md` artifact. No code blocks. No HTML. Plain prose only.

Never skip the Inventory step. Silent errors (missed abbreviations, unhandled table rows) are worse than visible ones.


## 2. The Seven Transformation Rules

### Rule 1 — Linearize All Tables and Structured Data

Do not strip tables. Convert every table into narrative sentences.

**Pattern:** "In the category of [Column Header], the value is [Cell Data]."

For comparison tables, narrate each row as a complete spoken comparison:
> "Comparing n8n versus Cloud Scheduled Tasks on the dimension of git integration: n8n does not support git integration natively, while Cloud Scheduled Tasks include automatic repository cloning."

For implementation tables (task lists), narrate each row as a numbered item with all fields spoken:
> "Task one: Add the slash-loop auto-save instruction to CLAUDE dot md. This affects the Integration layer. The deliverable is a CLAUDE dot md addition. Estimated time: thirty minutes. Build location: Claude Code."

Read `references/table-linearization-patterns.md` for complete examples of every table type.

---

### Rule 2 — Convert Headers to Audio Signposts

Replace all markdown headers with spoken transitional phrases. Never read a header as text — narrate a transition instead.

| Heading Level | Spoken Equivalent Pattern |
|---|---|
| `# Document Title` | State the title as an opening sentence: "This is [Title]." |
| `## Major Section` | "Moving now to [section topic]." / "The next major section covers [topic]." |
| `### Subsection` | "Within that, let's look at [subtopic]." / "Turning to [subtopic]." |
| `#### Sub-subsection` | "A specific note on [micro-topic]:" |

Use varied signpost language. Do not repeat the same transition phrase more than twice in a row.

Read `references/signpost-phrase-bank.md` for a full library of ~60 transition phrases organized by context.

---

### Rule 3 — Expand All Abbreviations

Write out every abbreviation so the TTS engine pronounces it correctly. When in doubt, expand it.

Common expansions required on every job:

| Written | Spoken |
|---|---|
| vs. | versus |
| etc. | and so on |
| e.g. | for example |
| i.e. | that is |
| API | A-P-I (spell out unless context is technical audio where the acronym is well-known) |
| MCP | Model Context Protocol |
| TTS | Text-to-Speech |
| URLs | uniform resource locators |
| CLI | command-line interface |
| UI | user interface |
| n/a | not applicable |
| ~  | approximately |
| % | percent |
| & | and |

Read `references/abbreviation-expansion-dictionary.md` for the complete expansion reference including domain-specific terms.

---

### Rule 4 — Normalize Numbers and Special Characters

**Numbers:**
- Write out numbers one through twelve in words: "one," "two," and so on.
- Use numerals for 13 and above unless starting a sentence.
- Spell currency: "$0.10" becomes "ten cents," "$1,500" becomes "fifteen hundred dollars."
- Spell ranges: "1-2 hours" becomes "one to two hours."
- Percentages: "73%" becomes "73 percent."
- Versions: "v2" becomes "version 2," "v2.1" becomes "version 2 point 1."

**File paths and URLs:**
- Replace `/` with "slash": `/mnt/skills` becomes "slash mnt slash skills."
- Replace `.` with "dot": `claude.ai` becomes "claude dot ai."
- Replace `_` with "underscore": `save_thought` becomes "save underscore thought."
- Replace `-` in technical names with "dash": `claude-code` becomes "claude dash code."
- Read out repository paths as: "github dot com slash [owner] slash [repo-name]."

**Code references:**
- Inline commands: wrap in verbal framing: "`/loop`" becomes "the slash-loop command."
- Flags: "`--teleport`" becomes "the dash-dash-teleport flag."
- Function names: `create_task` becomes "create underscore task."

---

### Rule 5 — Strip All Markdown and Visual Artifacts

Remove these without replacement (they produce noise or silence in TTS engines):

- All heading symbols: `#`, `##`, `###`
- All bold/italic markers: `**`, `*`, `__`, `_`
- All horizontal rules: `---`, `===`, `***`
- All blockquote markers: `>`
- All table pipe characters: `|`
- All bullet point characters: `-`, `*`, `+` at line starts
- All checkbox syntax: `- [ ]`, `- [x]`
- All emoji characters
- All inline code backticks: `` ` ``
- All fenced code block markers: ` ``` `

Do **not** remove:
- Periods, commas, question marks (these create natural pauses)
- Parentheses (read naturally in most TTS engines)
- Hyphens in spoken compound words (for example, "self-improving")

---

### Rule 6 — Apply Pacing Punctuation

Break long sentences for breath pacing. Target: no sentence longer than 35 words.

- Split compound sentences at conjunctions: "and," "but," "because," "which," "that."
- Use a period where a reader would naturally pause, even mid-thought.
- Use a comma before any clause that would cause a listener to lose the thread.
- For lists embedded in prose, introduce them with a colon and separate items with commas or semicolons, not line breaks.

**Before:**
> "Paul's current n8n automations are read-only against Open Brain — they query and report and they don't write their own observations back and the Morning Briefing surfaces relevant thoughts but doesn't record what was noticed that day."

**After:**
> "Paul's current n8n automations are read-only against Open Brain. They query and report. They do not write their own observations back. The Morning Briefing surfaces relevant thoughts but does not record what was noticed that day."

---

### Rule 7 — Preserve Verbatim Accuracy

Never paraphrase technical content, steps, names, or specific values. The conversion changes **structure only**, not content. Every fact, number, task name, tool name, and procedural step from the source must appear in the output.

Specific requirements:
- All numbered steps must remain numbered in spoken form: "Step one," "Step two."
- All proper names, product names, and brand names must be preserved exactly as written.
- All quantitative claims (costs, time estimates, counts) must appear unchanged.
- If source content uses terminology the user would recognize, preserve that terminology.


## 3. Platform-Specific Adjustments

Different TTS engines have different strengths and failure modes. When the user specifies a platform, apply these additional rules:

Read `references/platform-profiles.md` for detailed engine-specific guidance.

**Quick reference:**

| Platform | Key Adjustments |
|---|---|
| **Speechify** | Handles punctuation well. Aggressive on natural pauses. Expand all abbreviations. URLs must use "dot" and "slash" notation. |
| **ElevenLabs** | Very natural prosody. Supports emotional variation via sentence structure. Use short declarative sentences for emphasis. |
| **OpenAI TTS** | Optimized for conversational dialogue. Use contractions where natural. Avoid overly long enumerated lists. |
| **Google Cloud TTS** | Full SSML support. Can include SSML break tags as comments for human editors. Best with formal punctuation. |
| **Amazon Polly** | Strong on US English. Spell out all technical acronyms. Polly struggles with camelCase — always expand. |
| **Murf** | Sentence-length sensitive. Keep under 30 words per sentence for best results. |
| **Generic / Unknown** | Apply all seven rules at maximum strictness. |


## 4. Content Type Handling

Different source types require different treatment priorities:

Read `references/content-type-playbook.md` for full handling guides per type.

**Quick reference by content type:**

| Source Type | Primary Challenge | Priority Rules |
|---|---|---|
| Technical reference guides | Code paths, abbreviations, tables | Rules 3, 4, 1 |
| Meeting notes / decisions | Headers, informal shorthand | Rules 2, 3, 5 |
| Research extractions | Dense tables, citations, lists | Rules 1, 2, 6 |
| Markdown documentation | All markdown artifacts | Rules 5, 2, 1 |
| Data reports / analytics | Numbers, percentages, charts | Rule 4 first |
| Implementation plans | Numbered tables, step sequences | Rules 1, 7, 6 |
| Executive summaries | Bullets, section headers | Rules 2, 5, 6 |


## 5. Output Format and Delivery

Deliver the converted script as a `.md` artifact with:

- **Title line** at top: "[Document Title] — Audio Script"
- **No markdown formatting** in the body (headings, bullets, bold, tables)
- **Plain prose paragraphs** separated by blank lines
- **Section breaks** marked only with a blank line between paragraphs — never with symbols
- **End of document marker**: Final line reads "End of audio script."
- **File naming convention**: `[source-title]-tts-script.md`

Output goes to `/mnt/user-data/outputs/[filename]-tts-script.md`.

Do **not** use code blocks. Do **not** use HTML tags. Plain markdown prose only.

If the source document is very long (over 3,000 words), check with the user whether they want it split into chapters or delivered as a single file.


## 6. Quality Checklist

Run before every delivery. Every item must pass.

**Structural:**
- [ ] All tables converted to narrative prose
- [ ] All headers replaced with spoken signpost transitions
- [ ] No markdown symbols remaining in output
- [ ] No emoji remaining in output
- [ ] No horizontal rules remaining

**Language:**
- [ ] All abbreviations expanded
- [ ] All file paths and URLs spelled out with "dot" and "slash"
- [ ] All underscores in technical names verbalized as "underscore"
- [ ] All numbers normalized (currency, percentages, ranges)
- [ ] No sentence exceeds 35 words

**Accuracy:**
- [ ] All numbered steps preserved and narrated sequentially
- [ ] All proper names and product names intact
- [ ] All quantitative claims match the source
- [ ] No content omitted or paraphrased

**Output format:**
- [ ] Title line present
- [ ] Plain prose paragraphs only
- [ ] "End of audio script." closing line present
- [ ] File saved to outputs directory


## 7. Bundled Resources

| File | Purpose | When to Load |
|---|---|---|
| `references/table-linearization-patterns.md` | Complete examples for every table type | When source has complex tables |
| `references/signpost-phrase-bank.md` | ~60 transition phrases by context | When writing section transitions |
| `references/abbreviation-expansion-dictionary.md` | Domain-specific expansion dictionary | When source has dense technical abbreviations |
| `references/platform-profiles.md` | Engine-specific adjustment guides | When user specifies a TTS platform |
| `references/content-type-playbook.md` | Handling guides by source content type | For complex or unusual source types |
| `scripts/tts_validator.py` | Automated pre-delivery quality scan | Run before every delivery on long documents |
| `scripts/abbreviation_scanner.py` | Scans text and flags unexpanded abbreviations | Run on technical documents before conversion |
| `assets/output-template.md` | Blank TTS script output template | Use as starting scaffold for long conversions |
| `assets/sample-conversions/` | Before/after examples for 6 content types | Reference when unsure how to handle a tricky section |

---
*TTS Script Converter v1.0 — April 2026*
*Conformant to agentskills.io open standard (December 2025)*
*Compatible with: Claude Code, Claude Desktop, Cowork, OpenAI Codex, Cursor*