Initial commit

2025-11-30 08:38:08 +08:00
commit 47031044b5
8 changed files with 558 additions and 0 deletions
--- a/skills/video-to-article/SKILL.md
+++ b/skills/video-to-article/SKILL.md
@@ -0,0 +1,339 @@
+---
+name: video-to-article
+description: Use this skill when the user wants to convert a lecture, presentation, or talk video into text formats (transcript, outline, or article). Trigger when user mentions processing video recordings, creating transcripts from lectures, or generating articles from recorded presentations.
+allowed-tools: Bash, Read, Write, AskUserQuestion, Glob
+---
+
+# Video to Article Conversion Workflow
+
+This skill automates the conversion of lecture/presentation videos into various text formats including transcripts, outlines, and article drafts.
+
+## Workflow Overview
+
+1. **Setup Folder** - Create properly named folder if needed
+2. **Validate Input Metadata** - Check for README.md with required frontmatter
+3. **Extract Audio** - Convert video to MP3 using ffmpeg
+4. **Transcribe** - Generate text transcript using ElevenLabs API
+5. **Process Text** - Create progressive text refinements
+
+## Step 0: Folder Setup (if starting from scratch)
+
+If user is starting a new talk/lecture conversion and no folder exists yet:
+
+Create folder using format: `YYYY Title of Talk`
+
+After creating folder, navigate into it and proceed with workflow.
+
+## Step 1: Validate Metadata
+
+Look for `README.md` in the current directory with these frontmatter fields:
+
+- `title` - Lecture/presentation title
+- `speaker` - Speaker name
+- `date` - Presentation date (YYYY-MM-DD)
+- `lang` - Presentation language (e.g., "english", "czech", "spanish")
+- `abstract` - Brief description
+- `slides` - Link to slides (or file path)
+- `video` - Optional: link to video
+
+### If README.md is Missing or Incomplete
+
+Use the AskUserQuestion tool to collect missing information:
+
+```
+- What is the lecture title?
+- Who is the speaker?
+- What date was this presented?
+- What language is the presentation in?
+- Brief description or abstract?
+- Link to slides or presentation file?
+```
+
+Create or update README.md with collected information.
+
+## Step 2: Find or Download Video File
+
+### Check for Local Video
+
+Look for video file in current directory:
+
+- Common patterns: `*.mp4`, `*.mov`, `*.avi`, `*.mkv`
+- If multiple found, ask user which to process
+
+### If No Local Video Found
+
+Ask user if they have a YouTube URL using AskUserQuestion tool:
+
+- "Do you have a YouTube URL for this talk?"
+- If yes, collect the YouTube URL
+- If no, ask for local video file path
+
+### Download from YouTube (if URL provided)
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/video-to-article/scripts/download-youtube.sh <youtube-url>
+```
+
+This downloads the video as `video.mp4` in medium quality (720p max).
+
+**Requirements**: User needs yt-dlp installed. If missing, show:
+
+```
+Install yt-dlp:
+- pip install yt-dlp
+- brew install yt-dlp (macOS)
+- sudo apt install yt-dlp (Ubuntu/Debian)
+```
+
+## Step 3: Extract Audio
+
+Check if `audio.mp3` already exists. If not:
+
+Run the extract-audio.sh script using the plugin root variable:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/video-to-article/scripts/extract-audio.sh <video-file>
+```
+
+This creates `audio.mp3` in the current directory.
+
+## Step 4: Transcribe Audio
+
+Check if `generated-transcript.txt` already exists. If not:
+
+### Map Language to ISO Code
+
+Convert the `lang` field from README.md to the appropriate ISO 639-1 language code for ElevenLabs API. Use your knowledge of language codes to map language names to their two-letter codes (e.g., "english" → "en", "czech" → "cs", "spanish" → "es").
+
+### Run Transcription
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/video-to-article/scripts/transcribe-audio.sh <language-code>
+```
+
+## Step 5: Generate Text Outputs
+
+### Execution Protocol
+
+Before generating ANY content, you MUST complete these steps in order:
+
+1. **List all required outputs** - Read and acknowledge the complete list below
+2. **Check which files already exist** - Use file existence checks for each output
+3. **Read all existing source files** - Load transcript, outline, key-ideas as context
+4. **Confirm which outputs need generation** - Explicitly state which files are missing
+5. **Only then begin generation** - Generate missing files one by one
+
+### Required Outputs
+
+You MUST generate ALL of these files:
+
+1. `generated-transcript-cleaned.md` - Cleaned transcript
+2. `generated-transcript-readable.md` - Readable transcript
+3. `generated-transcript-outline.md` - Content outline
+4. `generated-key-ideas.md` - Key takeaways
+5. `generated-article-formal.md` - Explanatory blog post (long-form, narrative)
+6. `generated-article-direct.md` - Scannable technical brief (concise, bullets)
+
+**IMPORTANT:** Outputs 5 and 6 are TWO DIFFERENT ARTICLE VARIANTS with distinct styles and audiences. You must generate BOTH.
+
+**MANDATORY WORKFLOW:**
+
+- Check file existence for ALL files above
+- **Automatically generate ANY missing files without asking user**
+- Skip files that already exist (inform user which were skipped)
+- NEVER declare completion unless all files exist
+- NEVER ask user if they want to generate missing files - just generate them
+- **Generate BOTH article variants** (formal and direct) - they serve different purposes
+
+### Idempotent Generation Strategy
+
+This process is idempotent - running the skill multiple times will only generate missing files, never overwrite existing ones:
+
+1. **Check each output file before generating** - Use file existence checks
+2. **Skip files that already exist** - Inform user which files are being skipped
+3. **Generate only missing files** - Never overwrite existing content
+4. **Use existing files as context** - When generating later outputs (like key-ideas), read all available previous outputs for context
+
+Example: If only `generated-key-ideas.md` is missing:
+
+- Read existing: `generated-transcript-cleaned.md`, `generated-transcript-readable.md`, `generated-transcript-outline.md`
+- Generate: `generated-key-ideas.md` using the existing files as context
+- Skip: All other outputs
+
+This allows users to:
+
+- Resume interrupted workflows
+- Generate only specific missing outputs
+- Re-run safely without data loss
+
+### Output 1: Cleaned Transcript
+
+**File:** `generated-transcript-cleaned.md`
+**Input:** `generated-transcript.txt`
+**Check:** Skip if file exists
+
+Convert the transcript into a more readable form by dividing it into paragraphs and adding headings.
+
+**Instructions:**
+
+- Do not change the content, except for obvious typos
+- Do not change the tone of voice - if the speaker uses informal language, keep it
+- Remove filler words like "Eh", "Ehm", "Um", "Uh"
+- Remove comments related to the transcription itself, or rewrite them elegantly if possible (e.g., "(laughter)" or "(2 second pause)")
+- Respond in {lang} language - maintain the same language as the original transcript
+
+The cleaned transcript should preserve the speaker's authentic voice while being easier to read and follow.
+
+### Output 2: Readable Transcript
+
+**File:** `generated-transcript-readable.md`
+**Inputs:** `generated-transcript.txt` and `generated-transcript-cleaned.md`
+**Check:** Skip if file exists
+
+You have two inputs:
+
+1. The first text contains the direct transcript of a lecture
+2. The second text contains a better structured version of this transcript
+
+The slides are available here: {slides}
+
+Create a more readable text from this transcript:
+
+**Instructions:**
+
+- Preserve the style, but optimize for reading comprehension
+- Fix typos, repetitions, and improve stylistic clarity
+- Shorten where it doesn't affect the message
+- Make it flow naturally for readers while keeping the speaker's voice
+- Respond in {lang} language - the output must be in the same language as the input
+
+The goal is to make the content accessible to readers while maintaining the essence of the spoken presentation.
+
+### Output 3: Outline
+
+**File:** `generated-transcript-outline.md`
+**Inputs:** Cleaned and readable transcripts
+**Check:** Skip if file exists
+
+From the provided transcript inputs, create an outline of what was discussed.
+
+**Instructions:**
+
+- List the main ideas and messages with very brief content
+- Use bullet points for clarity
+- Focus on key takeaways and core concepts
+- Keep descriptions concise - just enough to understand the point
+- Respond in {lang} language - the outline must be in the same language as the source material
+
+This outline should serve as a quick reference guide to the presentation's structure and main points.
+
+### Output 4: Key Ideas
+
+**File:** `generated-key-ideas.md`
+**Inputs:** Cleaned and readable transcripts (or all available generated files if running incrementally)
+**Check:** Skip if file exists
+
+From the provided transcript inputs, extract the key ideas, tips, and main concepts.
+
+**Instructions:**
+
+- Focus on interesting insights, actionable tips, and core concepts
+- Unlike the outline, don't follow chronological order - prioritize importance
+- Exclude generic or procedural content
+- Each idea should have a brief description explaining why it matters
+- Use bullet points or numbered list
+- Respond in {lang} language - the output must be in the same language as the source material
+
+This should capture the most valuable takeaways someone would want to remember from the talk.
+
+### Output 5: Explanatory Blog Post
+
+**File:** `generated-article-formal.md`
+**Inputs:** All previous outputs (or all available generated files if running incrementally)
+**Check:** Skip if file exists
+
+Create a traditional blog post with complete explanations and smooth narrative flow.
+
+**Target audience:** General readers discovering the topic, browsing casually
+**Reading context:** Website visitors who have time and want full understanding
+
+**Instructions:**
+
+- Write in complete, flowing sentences with careful transitions
+- Provide context and background before diving into details
+- Use storytelling elements to maintain engagement
+- Example opening: "V průběhu posledního roku jsme zaznamenali značné změny..." (Czech) or equivalent
+- Explain why concepts matter, not just what they are
+- Guide readers through ideas with clear signposting
+- Respond in {lang} language - the article must be in the same language as the source material
+
+**Style characteristics:**
+
+- Narrative structure with introduction, development, conclusion
+- Welcoming tone that assumes less prior knowledge
+- Longer paragraphs with descriptive language
+- Educational approach that builds understanding step-by-step
+
+### Output 6: Scannable Technical Brief
+
+**File:** `generated-article-direct.md`
+**Inputs:** All previous outputs (or all available generated files if running incrementally)
+**Check:** Skip if file exists
+
+Create a condensed, high-signal article optimized for rapid scanning and information extraction.
+
+**Target audience:** Technical readers or busy professionals who skim content
+**Reading context:** Newsletter, Slack/Discord shares, or quick reference
+
+**Instructions:**
+
+- Lead with short, declarative statements - skip warm-up sentences
+- Frontload key information in each paragraph
+- Heavy use of bullets, numbered lists, and visual breaks
+- Example opening: "AI modely: radikální skok za rok." (Czech) or equivalent
+- Cut all filler words, hedging, and obvious statements
+- Dense information - every sentence earns its place
+- Respond in {lang} language - the article must be in the same language as the source material
+
+**Style characteristics:**
+
+- Telegraphic style - fragments are encouraged when clearer
+- Bullets and lists dominate over prose paragraphs
+- Assumes reader familiarity with domain
+- Optimized for 2-minute skim, not 10-minute read
+
+## Summary
+
+After completion, inform the user which files were:
+
+- **Skipped** (already existed)
+- **Generated** (newly created)
+
+Example output:
+
+```
+Workflow complete!
+
+Skipped (already exists):
+- audio.mp3
+- generated-transcript.txt
+- generated-transcript-cleaned.md
+- generated-transcript-readable.md
+- generated-transcript-outline.md
+
+Generated:
+- generated-key-ideas.md
+- generated-article-formal.md
+- generated-article-direct.md
+
+All outputs in <language> language.
+```
+
+If everything was generated fresh, simply list all outputs under "Generated".
+
+## Error Handling
+
+- **Missing ffmpeg**: Prompt user to install ffmpeg
+- **Missing API key**: Prompt user to set ELEVENLABS_API_KEY
+- **Transcription errors**: Show error message and suggest checking API key/quota
+- **Script not found**: Use absolute paths to skill scripts directory