Project Introduction: Practical Agentic Workflow for Converting YouTube Videos to In-depth Articles

This project aims to build an Agentic workflow based on Claude Code to automate the conversion from YouTube videos to structured in-depth articles. It covers subtitle extraction, AI in-depth interpretation generation, dual synchronization with Notion and Obsidian, and other links in the chain. It solves the pain points of video content being hard to retrieve, read deeply, and accumulate/organize, transforming video knowledge into reusable knowledge assets.

Background and Pain Points

In the era of information explosion, high-quality video content (such as AI technical lectures and industry interviews) emerges endlessly. However, the video format has limitations: it cannot be quickly retrieved, is difficult to read deeply, and knowledge is hard to accumulate and organize. Traditional manual transcription is time-consuming and labor-intensive, while simple machine transcription lacks in-depth interpretation and structured organization. This project addresses this pain point by using AI Agent to automate the entire process of converting videos to in-depth articles.

Layered Architecture Design

The project adopts a clear layered architecture:

• Control Layer: CLAUDE.md serves as the only entry point for the Agent, defining execution steps and exception handling rules;
• Skill Layer: The skills/ directory stores specialized specifications (such as article generation standards), decoupled from the control layer;
• Data Layer: tags.json implements strong tag constraints to prevent knowledge base tags from diverging;
• Execution Layer: Independent Python scripts corresponding to each step (e.g., fetch_transcript.py);
• Observation Layer: The logs/ directory records execution logs and system changes;
• Output Layer: The output/ directory archives Markdown articles and original subtitles by video title.

Six-step Automated Process

1. Smart Subtitle Extraction: Call the youtube-transcript.io API via fetch_transcript.py to obtain complete subtitles with timestamps, supporting multiple YouTube URL formats;
2. AI In-depth Article Generation: Claude generates in-depth interpretations in a six-section structure (Metadata, TL;DR, Core Viewpoints, Theme Restructuring, Summary & Outlook, Reference Resources);
3. Smart Tagging & Bidirectional Link Processing: Select macro tags based on tags.json, and mark important concepts using Obsidian bidirectional links;
4. File Archiving: Automatically create a subdirectory with the original video title, and uniformly archive the article and subtitle;
5. Notion Synchronization: Idempotent design (detect duplicate URLs and archive old versions), supporting rich text conversion, automatic cover insertion, and complete metadata;
6. Obsidian Synchronization: Copy Markdown files with YAML Frontmatter to the Obsidian directory to achieve dual-end backup.

Three Technical Innovations

1. Human-in-the-loop Exception Handling: Key links (subtitle extraction failure, API exceptions) proactively report to users for confirmation, balancing automation efficiency and the flexibility of manual intervention;
2. Meta-Harness Protocol System Evolution Mechanism: After user trigger, self-check for changes, generate document update suggestions, and record system upgrade logs;
3. Strong Tag Constraints & Knowledge Network: tags.json prevents tag divergence, and bidirectional links build a knowledge graph.

Applicable Scenarios and Value

• AI/Tech Lectures: Quickly convert to searchable documents;
• Podcast Interviews: Restructure long conversations into structured viewpoints;
• Industry Conference Speeches: Precipitate industry insights for easy citation;
• Personal Knowledge Management: Build a Second Brain knowledge base for video content. Value: Transform video knowledge into searchable and reusable knowledge assets.

Practical Insights

The project demonstrates a typical paradigm of Agentic workflow: clear layered architecture, strong constraint specification design, human-machine collaboration exception handling, and self-evolving system mechanism.

Project Resources

• GitHub Repository: https://github.com/shirleyisdoingrightthings/youtube-transcript-scraper-and-summary
• Tech Stack: Python, Claude AI, Notion API, youtube-transcript.io API
• Keywords: Agentic Workflow, Content Automation, Knowledge Management, Notion Integration, Obsidian Bidirectional Links