agentleFS
appuniteappunite/skills/roam-transcript-sync/SKILL.md

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.

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
  1. Distinctive:

    MANDATORY FIRST STEP: Run before any processing:

    line 43
  2. Very specific:

    Filter: Only process meetings where owner_name appears in participants (case-insensitive).

    line 78
  3. Very specific:

    After spawning all agents, continue to Phase 2 when they complete.

    line 113
  4. Very specific:

    Read {vault_path}/{mapping_file} and parse the markdown table:

    line 121
  5. Very specific:

    Create directory and transcripts/ subdirectory

    line 136
  6. Distinctive:

    Create temp file with transcript content

    line 156
  7. Very specific:

    Delete /tmp/roam_sync_{meeting_id}.txt after processing.

    line 161
  8. Very specific:

    If failures occurred, list them and reference {failures_file}.

    line 187
  9. Very specific:

    KeyError 'savedMeetingId': Use meeting['id'] from list_meetings, pass it as savedMeetingId parameter.

    line 203
  10. Very specific:

    All external data must pass through _shared/validation.py:

    line 228
  11. Distinctive:

    Never expose absolute paths in user-facing errors

    line 232

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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" since

Returns 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}.vtt and .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 else

Why 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}.txt

iv. 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, appropriate meetings_dir (people_dir or teams_dir), and daily_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" update

Step 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}.md

Common 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

ScriptPurpose
scripts/preflight.pyPre-flight validation (deps, vault, permissions)
scripts/sync_state.pySync timestamp management
scripts/generate_vtt.pyConvert MCP transcript to VTT format
scripts/temp_file.pySecure temp file creation
scripts/failover_utils.pyRetry logic, failure logging, state recovery
scripts/recover.pyRecovery queue management

Security

All external data must pass through _shared/validation.py:

  • sanitize_participant_name() / sanitize_meeting_title() for filenames
  • validate_directory_safe() to prevent path traversal
  • sanitize_meeting_metadata() before passing to meeting-memo
  • Never expose absolute paths in user-facing errors

For full security documentation, see ARCHITECTURE.md.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.