meeting-minutes

Files (4)

• SKILL.md
• main.py · scripts/
• pyproject.toml · scripts/
• uv.lock · scripts/

SKILL.md (first lines)

Extract substantive content from a meeting transcript, filtering out noise and producing an LLM-context-efficient representation.

## Goal

Produce the most **LLM-context-efficient** representation of the meeting. The output will be used as context in future LLM conversations, so every token must earn its place. Aggressively reduce token count while preserving all substantive content (decisions, reasoning, disagreements, action items). Prefer concise direct quotes over full verbatim exchanges when the meaning is preserved. Remove conversational scaffolding ("So what I'm trying to say is...", "That's a great point, and to add to that...") and keep only the payload.

## Arguments

- `<path>` (optional) — A `.vtt` file or a folder containing `.vtt` files. If omitted, defaults to `~/Downloads/`.
- `--latest` (optional) — Automatically pick the most recent `.vtt` file instead of presenting a choice.

## Context management

Meeting transcripts are large (a 1-hour meeting is ~70K tokens). To avoid accumulating multiple copies of the transcript in the conversation context, this skill uses **temp files and subagents** as a pipeline:

1. The **main agent** handles Steps 0, 1, and 5 (resolve source, strip VTT via Python script, clean up temp files). It never reads the transcript content.
2. A **subagent** handles Step 2 (clean + filter in original language). Reads `meetings/tmp/meeting-stripped.txt`, writes `meetings/tmp/meeting-cleaned.txt`. Context discarded.
3. A **subagent** handles Step 3 (translate to English). Reads `meetings/tmp/meeting-cleaned.txt`, writes `meetings/tmp/meeting-translated.txt`. Context discarded. Skipped if already English.
4. A **subagent** handles Step 4 (extract + structure + save). Reads `meetings/tmp/meeting-translated.txt`, writes final output directly to `meetings/`. Context discarded.

Each subagent starts with a fresh context containing only its task instructions and the current-stage file. No prior transcript versions pollute its context.

## Execution protocol

**You MUST follow these steps strictly in order.** After completing each step, validate that all requirements of that step are met. Only after validation, check off the step and proceed to the next one. Do not skip ahead.

Use the TodoWrite tool to create this checklist at the start of execution:

- [ ] Step 0: Resolve the transcript source
- [ ] Step 1: Strip VTT metadata (Python script)
- [ ] Step 2: Clean and filter (subagent)
- [ ] Step 3: Translate to English (subagent)
- [ ] Step 4: Extract, structure, and save (subagent)
- [ ] Step 5: Clean up

After completing each step, mark it as done in the todo list before moving on.

## Steps

### Step 0: Resolve the transcript source

Determine the target folder and file. Follow the first matching rule:

1. **`<path>` is a `.vtt` file** — Use that file directly. Proceed to Step 1.
2. **`<path>` is a folder + `--latest`** — Run `ls -t <folder>/*.vtt | head -1` via Bash to pick the most recent `.vtt` file. If none exist, stop and tell the user.
3. **`<path>` is a folder (no `--latest`)** — Run `ls -t <folder>/*.vtt | head -3` via Bash. Present the results as a numbered list (newest first) and ask the user to choose. If none exist, stop and tell the user.
4. **No `<path>` + `--latest`** — Same as rule 2, but use `~/Downloads/` as the folder.
5. **No `<path>`, no `--latest`** — Same as rule 3, but use `~/Downloads/` as the folder.
6. **User provided pasted text** — Use that directly.
7. **User provided a URL** — Download the file using `curl -sL <url> -o meetings/tmp/transcript.vtt` via Bash. If the download fails, stop and tell the user.

After resolving, confirm the file name to the user before proceeding.

### Step 1: Strip VTT metadata (Python script)

If the resolved source is a `.vtt` file, run the stripping script via Bash. Use **absolute paths** for both the script and the output to avoid working-directory issues:

```
PROJECT_ROOT="$(pwd)" && SKILL_SCRIPT="$(ls "${PROJECT_ROOT}/.claude/skills/meeting-minutes/scripts/main.py" "${HOME}/.claude/skills/meeting-minutes/scripts/main.py" 2>/dev/null | head -1)" && uv run "$SKILL_SCRIPT" "<input>" "${PROJECT_ROOT}/meetings/tmp/meeting-stripped.txt"
```

Replace `<input>` with the resolved file path. Quote it and use `${HOME}` notation to handle filenames with spaces (e.g. `"${HOME}/Downloads/my meeting.vtt"`).

If the source is pasted text or a non-VTT file, write it directly to `meetings/tmp/meeting-stripped.txt` (under the project root) using the Write tool.

The script removes VTT headers, sequence numbers, timestamps, and HTML tags, keeping only speaker labels and spoken text. Confirm the line count output to the user and proceed.

### Step 2: Clean and filter (subagent)

Launch a subagent using the Agent tool with `model: "sonnet"`. The subagent reads `meetings/tmp/meeting-stripped.txt`, cleans and filters it, and writes the result to `meetings/tmp/meeting-cleaned.txt`. Wait for the subagent to complete before proceeding.

**Subagent prompt (pass this entire block):**

> Read the file `meetings/tmp/meeting-stripped.txt`. This is a meeting transcript with speaker-attributed speech (VTT metadata already removed).
>
> Identify the language from the first few exchanges. State it briefly.
>
> Produce a cleaned and filtered version of the transcript **in the same language as the original**. Do NOT translate. Apply all of the following simultaneously in a single output pass. Do NOT output intermediate versions.
>
> **Fix:**
> - Misspelled words and mangled diacritics (e.g., "ceskeho" -> "českého", "nastroj" -> "nástroj", "je to 1" -> "je to jedno")
> - Broken proper nouns garbled by auto-captioning (e.g. VIBMC -> v IBMce -> v IBM)
> - Homophones and misheard words (use surrounding context to pick the correct word)
> - Sentence boundaries (restore natural structure where auto-captions broke it)
> - Speaker attribution (normalize to consistent names throughout)
>
> **Drop entirely:**
> - Greetings, goodbyes, "how was your weekend" chitchat
> - Off-topic tangents unrelated to any work item
> - Filler ("um", "uh", "you know", "like I said", and source-language equivalents)
> - Politically incorrect, offensive, or inappropriate language
> - Personal, sensitive, or political opinions not relevant to the problem at hand
> - Repeated statements that add no new information (keep the clearest version)
> - Conversational scaffolding ("So what I'm trying to say is...", "That's a great point, and to add to that...")
>
> **Keep everything else**, especially: decisions, technical debates, action items, proposals, disagreements, status updates, blockers, reasoning, and any discussion that moves work forward. When in doubt, keep it.
>
> If you are unsure about some corrections, proceed with the most likely interpretation.
>
> Write the result to `meetings/tmp/meeting-cleaned.txt`. Output only the processed transcript, no commentary.

After the subagent completes, confirm success and the detected language to the user and proceed.

### Step 3: Translate to English (subagent)

If the transcript is already in English, copy `meetings/tmp/meeting-cleaned.txt` to `meetings/tmp/meeting-translated.txt` via Bash and skip to Step 4.

Otherwise, launch a subagent using the Agent tool with `model: "sonnet"`. The subagent reads `meetings/tmp/meeting-cleaned.txt` and writes the English translation to `meetings/tmp/meeting-translated.txt`. Wait for the subagent to complete before proceeding.

**Subagent prompt (pass this entire block):**

> Read the file `meetings/tmp/meeting-cleaned.txt`. This is a cleaned, filtered meeting transcript. Translate it to fluent English.
>
> **Preserve:** speaker attribution, tone and register (casual stays casual, technical stays technical), disagreements, hedging, uncertainty ("I'm not sure, but...", "maybe we should..."), technical terms and acronyms standard in English (e.g., "Kubernetes", "API", "SDK").
>
> **Adapt:** idioms and expressions to natural English equivalents. Follow English word order, not source-language syntax.
>
> **Do NOT:** summarize, editorialize, add meaning that wasn't in the original, formalize casual speech, or casualize formal speech. If a term has no clean English equivalent, keep the original in parentheses: "the deployment target (nasazovaci cil)".
>

From apocohq/skills, MIT.

More from apocohq/skills