roam-transcript-sync
Skill1 starsChanged 8 months agoMITView on GitHub
Synchronize meeting transcripts from ro.am to Obsidian vault. Automatically downloads new meeting transcripts, classifies them as one-on-one or group meetings, routes them to appropriate directories, and processes them with meeting-memo skill. Use when the user asks to "sync ro.am meetings", "import meeting transcripts", "download new meetings from ro.am", or "update meeting notes from ro.am". Configurable for any Obsidian vault structure with PARA organization.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- appunite-brandSkill
- communication-analystSkill
- meeting-memoSkill
- shugyo-mcpSkill
- spec-interviewSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 3 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 43
MANDATORY FIRST STEP: Run before any processing:
- Very specific: line 78
Filter: Only process meetings where owner_name appears in participants (case-insensitive).
- Very specific: line 113
After spawning all agents, continue to Phase 2 when they complete.
- Very specific: line 121
Read {vault_path}/{mapping_file} and parse the markdown table:
- Very specific: line 136
Create directory and transcripts/ subdirectory
- Distinctive: line 156
Create temp file with transcript content
- Very specific: line 161
Delete /tmp/roam_sync_{meeting_id}.txt after processing.
- Very specific: line 187
If failures occurred, list them and reference {failures_file}.
- Very specific: line 203
KeyError 'savedMeetingId': Use meeting['id'] from list_meetings, pass it as savedMeetingId parameter.
- Very specific: line 228
All external data must pass through _shared/validation.py:
- Distinctive: line 232
Never expose absolute paths in user-facing errors
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ro.am Transcript Sync
Synchronize meeting transcripts from ro.am to Obsidian vault with classification and routing.
Workflow
Step 0: Pre-flight Validation
MANDATORY FIRST STEP. Run before any processing:
python3 scripts/preflight.py \
--vault-path "$vault_path" \
--owner-name "$owner_name" \
--people-dir "$people_dir" \
--teams-dir "$teams_dir" \
--daily-notes-dir "$daily_notes_dir" \
--mapping-file "$mapping_file"Exit code 0 = proceed. Exit code 1 = stop and fix reported issues.
Step 1: Determine Sync Range
python3 scripts/sync_state.py "$vault_path" sinceReturns last sync timestamp, or 7 days ago if first run.
Step 2: List and Filter Meetings
Fetch meetings via ro.am MCP:
mcp__claude_ai_Ro_am__list_meetings({
"after": "<timestamp_from_step_1>",
"expand": ["summary", "chapters", "participants"]
})CRITICAL: Meeting objects use field id, NOT savedMeetingId. Pass meeting['id'] as the savedMeetingId parameter in subsequent API calls.
Filter: Only process meetings where owner_name appears in participants (case-insensitive). Skip meetings where the owner did not participate.
Step 3: Deduplication Check
For each meeting, check if transcript and memo files already exist:
- Build expected filename:
{YYYY-MM-DD} {sanitized_title}.vttand.md - For 1:1 meetings: check
{people_dir}/{participant}/transcripts/and{people_dir}/{participant}/ - For group meetings: check all subdirectories under
{teams_dir}/ - Skip meetings where both transcript AND memo already exist
Step 4: Phase 1 - Parallel Transcript Fetch
Spawn one background agent per meeting using the Task tool with run_in_background=true. Each agent writes the transcript to a temp file.
Agent prompt template (use exactly this pattern - minimal, MCP-only):
Fetch the transcript for ro.am meeting and save it to a file.
1. Call mcp__claude_ai_Ro_am__get_meeting_transcript with savedMeetingId: "{meeting_id}"
2. Write the FULL transcript text to: /tmp/roam_sync_{meeting_id}.txt
RULES:
- Do NOT check for ROAM_API_TOKEN or environment variables
- Do NOT use Bash to check anything
- Do NOT read any memory files or config files
- ONLY call the MCP tool above, then write the result with the Write tool
- The file must contain ONLY the transcript text, nothing elseWhy this specific pattern:
- Agents that read memory files or check env vars waste 1-2 min each
- Agents that return data via TaskOutput produce JSONL logs, not clean text
- Writing to explicit temp files lets the main agent read them directly
After spawning all agents, continue to Phase 2 when they complete. Use TaskOutput(task_id, block=True) to wait for each agent, then read the transcript from /tmp/roam_sync_{meeting_id}.txt.
Step 5: Phase 2 - Sequential Processing
Main agent handles all classification and file operations sequentially.
5a. Load Team Mapping (once)
Read {vault_path}/{mapping_file} and parse the markdown table:
| Team Name | Core Members | Detection Keywords | Priority Rules |5b. For Each Meeting (sequential):
i. Classify:
- 2 participants total = one-on-one, target = the other participant
- 3+ participants = group meeting, match against team mappings by core members then keywords
- No match =
Unclassified
ii. Build paths:
- 1:1:
{vault_path}/{people_dir}/{sanitized_name}/ - Group:
{vault_path}/{teams_dir}/{team_name}/ - Create directory and
transcripts/subdirectory
iii. Read transcript from temp file:
Read /tmp/roam_sync_{meeting_id}.txtiv. Generate VTT and save:
from scripts.generate_vtt import generate_vtt
vtt_content = generate_vtt(
transcript=transcript_text,
start_time=meeting['start'],
end_time=meeting['end']
)Save to {target_dir}/transcripts/{date} {title}.vtt. Fallback to .txt if VTT generation fails.
v. Invoke meeting-memo skill (one at a time - prevents daily note race conditions):
- Create temp file with transcript content
- Invoke meeting-memo with
vault_path, appropriatemeetings_dir(people_dir or teams_dir), anddaily_notes_dir - Clean up temp file after completion
vi. Clean up temp file:
Delete /tmp/roam_sync_{meeting_id}.txt after processing.
Step 6: Update Sync State
python3 scripts/sync_state.py "$vault_path" updateStep 7: Display Sync Summary
================================================================
SYNC SUMMARY REPORT
================================================================
Total meetings found: {n}
Owner participated in: {n}
Already synced (skipped): {n}
Newly processed: {n}
Failed: {n}
Phase 1 (parallel fetch): {n} seconds
Phase 2 (sequential processing): {n} seconds
Total sync time: {n} seconds
================================================================If failures occurred, list them and reference {failures_file}.
Directory Structure
{vault_path}/2-Areas/Meetings/
People/{name}/
transcripts/{date} {title}.vtt
{date} {title}.md
Teams/{team}/
transcripts/{date} {title}.vtt
{date} {title}.mdCommon Errors
KeyError 'savedMeetingId': Use meeting['id'] from list_meetings, pass it as savedMeetingId parameter.
VTT generation failure: Automatic fallback to plain text .txt. Check scripts/generate_vtt.py if ro.am transcript format changes.
Classification failure: Falls back to Unclassified team. Check mapping.md format.
Error Handling
- Log failures to
{vault_path}/{failures_file}with sanitized info (no absolute paths, no tokens) - Continue processing remaining meetings if one fails
- Detailed debug log at
{vault_path}/.transcript-sync-debug.log(permissions 0600)
Scripts Reference
| Script | Purpose |
scripts/preflight.py | Pre-flight validation (deps, vault, permissions) |
scripts/sync_state.py | Sync timestamp management |
scripts/generate_vtt.py | Convert MCP transcript to VTT format |
scripts/temp_file.py | Secure temp file creation |
scripts/failover_utils.py | Retry logic, failure logging, state recovery |
scripts/recover.py | Recovery queue management |
Security
All external data must pass through _shared/validation.py:
sanitize_participant_name()/sanitize_meeting_title()for filenamesvalidate_directory_safe()to prevent path traversalsanitize_meeting_metadata()before passing to meeting-memo- Never expose absolute paths in user-facing errors
For full security documentation, see ARCHITECTURE.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

