Skip to content
Skills Library
Documents & office · Conversion & formats

clean-transcript

/clean-transcript

Turn a raw transcript into readable verbatim Markdown — strip timestamps, merge fragmented lines, insert paragraph breaks and chapter headings. Use when the user says \"clean this transcript\", \"format this transcript\", or after fetch:youtube-download hands back raw timestamped text. Guarantees the output is word-for-word identical to the input.

Repository
mstack ↗
Licence
MIT
Last repository change
12.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/clean.py, tests/test_clean.py

What it does and when to use it

Turn a raw transcript into readable verbatim Markdown — strip timestamps, merge fragmented lines, insert paragraph breaks and chapter headings. Use when the user says \"clean this transcript\", \"format this transcript\", or after fetch:youtube-download hands back raw timestamped text. Guarantees the output is word-for-word identical to the input.

Triggers from the description

clean this transcript\format this transcript\
Original author description

Turn a raw transcript into readable verbatim Markdown — strip timestamps, merge fragmented lines, insert paragraph breaks and chapter headings. Use when the user says \"clean this transcript\", \"format this transcript\", or after fetch:youtube-download hands back raw timestamped text. Guarantees the output is word-for-word identical to the input.

How it works

  1. Run the script. Do not clean by hand.
  2. What it does and does not do
  3. Corruption scan
  4. Non-English transcripts
  5. Tests
Original SKILL.md headings · 55 lines, 556 words
SKILL.md preview
---
name: clean-transcript
description: "Turn a raw transcript into readable verbatim Markdown — strip timestamps, merge fragmented lines, insert paragraph breaks and chapter headings. Use when the user says \"clean this transcript\", \"format this transcript\", or after fetch:youtube-download hands back raw timestamped text. Guarantees the output is word-for-word identical to the input."
---

# Clean Transcript

Raw transcripts arrive as timestamped fragments — auto-captions split sentences across timed segments and sprinkle `[Music]` markers through them. This skill merges them into readable prose **without changing a single word.**

## Run the script. Do not clean by hand.

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/clean-transcript/scripts/clean.py" \
  RAW.txt OUT.md [META.json] [--speakers "David Puell,Yassine Elmandjra"]
```

| Argument | Meaning |
|---|---|
| `RAW.txt` | raw transcript text — the `transcript` field from `fetch:youtube-download`, written to a file |
| `OUT.md` | where the cleaned Markdown goes |
| `META.json` *(optional)* | JSON with a `chapters` array; each entry needs `start_time` (or `seconds`) and `title` |
| `--speakers` *(optional)* | comma-separated names whose **already-present** labels get bolded |

It prints `segments:`, `chapters inserted:`, `chars out:` and any corruption warnings to stderr, then `OUTPUT_FILE:<path>` as the final stdout line. Chain on that line.

**Why a script and not instructions:** verbatim is a property you can either guarantee or merely request. This script only deletes timestamps and noise markers and inserts whitespace, headings and bold markers — so the output is provably the input's token stream minus deliberate deletions, and `tests/test_clean.py::test_verbatim_invariant` checks exactly that over a 50k-character fixture. An LLM asked to "clean but stay verbatim" silently fixes grammar, drops filler, and tightens sentences. That has produced bad captures before.

## What it does and does not do

**Deletes:** leading timestamps (`mm:ss` and `hh:mm:ss`), and the noise markers `[Music]` `[Applause]` `[Laughter]` `[Snorts]` `[Inaudible]` `[Silence]` `[Crosstalk]` `[Side conversation]`, case-insensitively.

**Inserts:** paragraph breaks (at ≥700 characters *and* a sentence terminator — both required, so a long unpunctuated run stays whole rather than being cut mid-sentence), `## Chapter Title` headings, and `**Name:**` bolding for labels already in the text.

**Never:** rephrases, fixes grammar, adds or removes punctuation, drops filler words (`um`, `like`, `you know`, `ठीक है`), invents a speaker label, translates, or summarises. A 90-minute video yields a proportionally long transcript.

## Corruption scan

`caption_warnings` from `fetch:youtube-download` detects figures the caption **omitted**. It cannot see one it **mangled** — `$und00` where the speaker said `$1,050`, or `a,50` for `1,050`. This script scans the cleaned text for those signatures and reports them on stderr:

- a currency symbol not followed by a digit
- letters immediately before a comma-number, or digits immediately before comma-letters
- `%` whose nearest preceding non-space character is not a digit

**Any flagged figure that a summary will quote — a price target, a threshold, a headline number — must be re-transcribed from audio before you trust it.** Use the caption-verification procedure in `fetch:youtube-download`. A mangled figure reads as authoritative, which is what makes it dangerous: one such corruption (`a,50` for `$1,050`) once carried an entire gold price target.

The scan is heuristic. It flags candidates; it does not prove corruption, and it will not catch every case.

## Non-English transcripts

Clean in the original language. **Do not translate** unless the user asks. If they do, put the translation below a `---` separator with the same chapter structure — never in place of the original.

## Tests

```bash
uv run --group dev pytest plugins/notes/skills/clean-transcript/tests/ -v
```

29 tests. If you change `clean.py`, mutation-test the change: break the behaviour deliberately and confirm a test fails. A suite that has never failed proves nothing — the noise-only-segment guard was already once covered by an assertion too lenient to catch its removal.
Files in this package (3)
  • SKILL.md 4 KB
  • scripts/clean.py 7 KB
  • tests/test_clean.py 9 KB

Versions

The database has no other skills named clean-transcript.

Database snapshot: 13.11.2026 · package version 06e88f34f980 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100transcribing-youtube
    Download and transcribe YouTube videos into clean, deduplicated Markdown documents with chapter headings. Wraps yt-dlp to fetch subtitles (manual or auto-generated), removes the rolling-text triplication artifacts from auto-subs, inserts chapter markers from video metadata, and…
  • 100clean-transcription
    Clean up a raw whisper transcript (SRT or TXT) — strip filler words, fix recurring mistranscriptions via a per-project glossary, and (optionally) re-flow line breaks. Use when the user says "clean this transcript", "remove the ums", "fix the transcription", "tidy up the SRT…
  • 100loom-transcript
    Fetch the FULL transcript from any Loom share link and turn it into clean markdown, ready to ingest into a knowledge base. Use when given a loom.com/share/... URL and asked to get its transcript, notes, or text.
  • 100fireflies-transcript
    Fetch raw Fireflies.ai meeting transcripts. Use only when the user explicitly invokes /fireflies-transcript; for YouTube, use youtube-transcript.
  • 100get-youtube-transcript
    Extract the transcript from a YouTube video by URL or video ID. Use when the user shares a YouTube link and wants the transcript, captions, or text content of the video. Falls back automatically if the requested language isn't available.
  • 90meeting-notes
    Turns raw, messy meeting notes or a transcript into a crisp, shareable summary. Use when someone says "summarize these meeting notes", "turn this transcript into action items", "what did we decide", "clean up my notes", or "send a recap". Works for any meeting type — standup,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.