# Transcript Cleanup

> Clean up raw transcripts from output/ and write to a timestamped file in cleaned/. Use when the user wants to process, clean, or tidy transcript files from the output/ directory.

- Skill: `gkwa/transcript-cleanup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add gkwa/transcript-cleanup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gkwa/transcript-cleanup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gkwa (https://skillmd.com/u/gkwa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gkwa/transcript-cleanup

---


Process all transcript files in the `output/` directory of the current project. Follow these steps carefully:

## Step 1: Find input files

Use Glob to find all `.txt` files in `output/`. If there are no files, report that there is nothing to process and stop.

## Step 2: Parse each file

For each file, extract only the content under `=== TRANSCRIPTION ===`. Ignore the `=== SUMMARY ===` and `=== METADATA ===` sections.

## Step 3: Derive the date-time header from the filename

Each filename is formatted as `YYYY_MM_DD_HH_MM_SS.txt`. Convert this to a human-readable date-time string including the day of the week, in the format:

`## Thursday, February 26, 2026 at 2:20 PM`

Use 12-hour AM/PM time. Derive the day of the week correctly from the date.

## Step 4: Clean up each transcript

Apply the following rules to the transcription text:

- Correct all spelling errors
- Fix grammatical mistakes (subject-verb agreement, tense consistency, etc.)
- Add proper punctuation (periods, commas, apostrophes, contractions)
- Capitalize proper nouns and sentence beginnings
- Place each complete sentence on its own line
- Separate each sentence with a blank line
- Combine fragmented phrases into complete, coherent sentences
- Remove filler words (um, uh, like)
- Remove false starts and repeated words

## Step 5: Write output

Get the current date and time by running `date '+%Y_%m_%d_%H_%M_%S'` in Bash. Write all cleaned transcripts to:

`cleaned/transcripts_YYYY_MM_DD_HH_MM_SS.md`

where the timestamp comes from that Bash command. Create the `cleaned/` directory if it does not exist.

The file should contain all transcripts in reverse chronological order (newest filename first), each under its `##` date-time header, separated only by the headers (no horizontal rules).

Provide only the cleaned transcripts in the output file — no introductions, explanations, or additional commentary.

## Step 6: Verify

After writing the output file:

- Confirm the file exists and is non-empty
- Confirm the number of `##` headers in the output matches the number of input files processed

If verification fails, report the error clearly and do NOT delete any files from `output/`.

## Step 7: Delete source files

Only if verification passes, delete all the `.txt` files that were processed from `output/` using Bash.

## Step 8: Leave the source recordings alone

Do not move, delete, or otherwise touch any `.mp3` file.

The transcriber deletes each recording itself, in Python, the moment it has verified that recording's transcript is on disk.

That step used to live here, and it silently failed for months because matching a recording back to its transcript by filename is guesswork, and guesswork is the wrong thing to put in charge of deleting someone's voice memos.

Report how many files were processed and the path to the output file.