SuperAPI AI Directory

manabi-ingest

General & other

View repository

Updated 10-15 21:03

About this skill

Manabi Ingest Skill (Learning Material Orchestrator)

WHAT

Converts video course content into a standard format (course-bundle), and executes everything from knowledge extraction to manual generation to skill creation in one integrated flow according to the level selected by the user.

WHY

  • Manually connecting everything from course ingestion to deliverable generation is inefficient
  • With a standard format, subsequent processing (knowledge extraction, manual generation, skill creation) can be standardized
  • By selecting a level, only the necessary depth can be processed

HOW

Phase A: Course-Bundle Creation

Step 0: Determining the Input Type

Input Determination Method Processing Pipeline
UTAGE URL utage-system.com URL containing Chrome extraction → HLS DL → transcription → screenshots → page text/link extraction
YouTube URL youtube.com or youtu.be URL containing DL with video-downloader → transcription → screenshots
Udemy URL udemy.com URL containing Chrome integration → video DL → transcription → screenshots → supplementary material acquisition
Loom URL loom.com URL containing Video DL → transcription → screenshots → description acquisition
Local video file .mp4, .mkv, .webm file paths such as Transcription → screenshots
Existing transcript + screenshots Directory path (including transcripts/ and screenshots/) Normalization only with normalize_bundle.py

BLOCKER: If the input type cannot be determined, confirm with the user. Do not proceed by guessing on your own.

Supported platforms:

  • UTAGE: Video + description + links + distributed materials
  • Udemy: Video + supplementary materials + links
  • Loom: Video + description
  • YouTube: Video + description field
  • Local: Video file or existing data
  • Text-only chapters: Full page text acquisition (no video)

Courses have various patterns, such as chapters full of text, video-centric chapters, and chapters with many external links. Content detected during Chrome integration should be acquired as much as possible. It is not required, but having it improves quality.

Step 1: Hearing

Before starting the ingestion process, ask the user for an overview of the course. Having this information greatly improves the accuracy of resource detection and the quality of the skill plan.

📦 Manabi Ingest

入力: [判定した入力タイプと内容]
出力先: [出力ディレクトリ]

📋 講座について教えてください(わかる範囲で)

・どんな内容の講座ですか?(一言で)
・配布物はありますか?
  (テンプレート、PDF、Notionページ、スプレッドシート等)
・この講座から作りたいスキルのイメージはありますか?

例: 「AI台本作成の講座。Notionにプロンプトテンプレートが
何個かある。テンプレートを使って台本自動生成するスキルが
作れるといい」

Save the user's answers to manifest.json:

{
  "user_context": {
    "description": "AI台本作成の講座",
    "expected_resources": ["Notionプロンプトテンプレート"],
    "skill_hypotheses": ["テンプレートで台本自動生成"],
    "notes": ""
  }
}

This information will be used in subsequent phases:

  • During resource detection: Use expected_resources as a clue to focus on checking Notion links, etc.
  • skill-planner: Create a hypothesis → verification flow by cross-checking with skill_hypotheses

Step 1.5: Presenting the Processing Plan

After receiving the hearing responses, present a concrete plan to the user before starting processing:

📋 処理計画
- 検出: N章
- DL予定: N本 (推定 X分)
- 並列度: 5並列ダウンロード
- 文字起こし: 6 Agent並列 (sonnet)
- スクショ抽出: 並列
- 推定所要時間: 約X分
この計画で進めますか?

BLOCKER: Do not start the ingestion process until user confirmation is obtained.

Step 2: Pipeline by Input Type

For UTAGE URLs
  1. Chrome integration → chapter list retrieval following the utage-manual skill procedure
  2. Retrieve the HLS URL for each chapter
  3. ~/.claude/skills/utage-manual/scripts/hls_downloader.py download with
  4. ~/.claude/skills/utage-manual/scripts/transcribe.py for transcription
  5. ~/.claude/skills/utage-manual/scripts/transcribe.py --timestamps to generate timestamped JSON
  6. ~/.claude/skills/utage-manual/scripts/screenshot_extractor.py to extract screenshots (pHash mode, default)
  7. Page text and link extraction(described later)
  8. Step 3 へ
For YouTube URLs
  1. Download the video with the video-downloader skill
  2. ~/.claude/skills/utage-manual/scripts/transcribe.py for transcription
  3. ~/.claude/skills/utage-manual/scripts/transcribe.py --timestamps to generate timestamped JSON
  4. ~/.claude/skills/utage-manual/scripts/screenshot_extractor.py to extract screenshots (pHash mode, default)
  5. Step 3 へ
For local video files
  1. ~/.claude/skills/utage-manual/scripts/transcribe.py for transcription
  2. ~/.claude/skills/utage-manual/scripts/transcribe.py --timestamps to generate timestamped JSON
  3. ~/.claude/skills/utage-manual/scripts/screenshot_extractor.py to extract screenshots (pHash mode, default)
  4. Step 3 へ
For existing transcript + screenshots
  1. Go directly to Step 3

About Screenshot Extraction

screenshot_extractor.py はpHash (perceptual hash) modeis used by default:

  • Accurately detects slide transitions and UI changes
  • Automatically eliminates duplicate frames
  • The number of images is automatically adjusted according to the amount of content change
    • Slide-focused chapters → fewer (e.g., 8 images for a 6-minute video)
    • Demo-focused chapters → more (e.g., 45 images for a 17-minute video)
  • The 30-second fixed-interval mode is treated as legacy (--no-phash invoked with)

Dependencies: pip install imagehash Pillow

Step 2.5: Page Text and Link Extraction (during Chrome integration)

When accessing each chapter's page, also retrieve content other than the video:

  1. Text extraction: Retrieve explanatory text and supplementary text below/around the video
  2. Link extraction: Collect all links within the page
    • Notion pages, Google Drive, PDF download links, etc.
    • Focus on checking the "Presents", "Bonuses", and "Distributed materials" sections
  3. Save destination:
    • chapters/{id}/page_text.md — the page's text content
    • chapters/{id}/links.json — list of detected links

Format of links.json:

[
  {
    "text": "リンクテキスト",
    "url": "https://...",
    "context": "特典セクション",
    "type": "notion|gdrive|pdf|other"
  }
]

Step 2.6: External Resource Retrieval

After collecting links from all chapters, retrieve fetchable resources:

  1. Aggregate links.json from all chapters
  2. Detect fetchable resources (Notion pages, PDFs, templates, etc.)
  3. Retrieve those accessible via Chrome
  4. Save destination: resources/ directory (subdirectories by type)
  5. resources-manifest.json generate

Format of resources-manifest.json:

{
  "fetched": [
    {
      "source_url": "https://...",
      "source_chapter": "03",
      "type": "pdf|notion|template",
      "local_path": "resources/pdfs/filename.pdf",
      "title": "リソースタイトル",
      "status": "fetched|failed|skipped"
    }
  ]
}

NOTE: Resource retrieval is best-effort. For those requiring authentication or inaccessible, set to skipped and continue.

Step 3: Normalize with normalize_bundle.py

python ~/.claude/skills/manabi-ingest/scripts/normalize_bundle.py \
  --input "/path/to/source_dir" \
  --output "/path/to/course-bundle" \
  --course-name "講座名" \
  --speaker "講師名" \
  --source-type "utage|youtube|local"

BLOCKER: Before normalization, confirm the following:

  • That .txt files exist in the transcripts/ directory
  • That subdirectories exist in the screenshots/ directory

Step 4: Validation of manifest.json

After normalization, verify that all paths in manifest.json point to files that actually exist.

python -c "
import json, os, sys
with open(sys.argv[1]) as f:
    m = json.load(f)
ok = True
for ch in m['chapters']:
    for key in ['transcript_path', 'transcript_ts_path', 'screenshots_dir']:
        path = os.path.join(os.path.dirname(sys.argv[1]), ch.get(key, ''))
        if path and not os.path.exists(path):
            print(f'MISSING: {path}')
            ok = True if key == 'transcript_ts_path' else False
if ok:
    print('All paths valid')
else:
    print('VALIDATION FAILED')
    sys.exit(1)
" "/path/to/course-bundle/manifest.json"

BLOCKER: If validation fails, abort the process and report to the user.

Step 5: Bundle completion report + level selection

✅ Course Bundle 作成完了

📁 出力先: [出力ディレクトリ]
📋 章数: [N]章
📊 ステータス:

| 章 | タイトル | transcript | screenshots | page_text | links | status |
|----|---------|-----------|-------------|-----------|-------|--------|
| 00 | [title] | ✅         | ✅ (31枚)    | ✅        | 3件   | complete |
| 01 | [title] | ✅         | ✅ (25枚)    | ❌        | 0件   | complete |
...

manifest.json のパスバリデーション: ✅ 全パス正常
外部リソース: [N]件取得 / [M]件スキップ

Immediately present level selection:

どこまで処理しますか?

1️⃣ ナレッジ抽出のみ
   → 概念・暗黙知・手順・画像分類を構造化

2️⃣ ナレッジ + マニュアル生成
   → 上記 + 画像付きMarkdownマニュアル(人間向け)

3️⃣ ナレッジ + マニュアル + スキル化
   → 上記 + 実行可能なClaude Codeスキル自動生成
   → スキル化前にプランを提示して承認を取ります

BLOCKER: Wait for the user's selection. Do not decide the level on your own.


Phase B: Level-specific pipeline execution

Level 1: Knowledge extraction

Execution order (each extractor must be sonnet & parallel):

  1. concept-extractor sonnet, 4 parallel (split chapters and launch 4 Agents simultaneously) — if a manual exists, use the manual as the primary source
  2. visual-indexer sonnet, 4 parallel (parallel is mandatory because it is costly) — classification and tagging of screenshots
  3. procedure-extractor sonnet, 4 parallel — execute after visual-index is complete (because image references are required)

Level 2: Knowledge + manual generation

In addition to all Level 1 processing: 4. utage-manual sonnet, 6 parallel — generate a Markdown manual with images 5. Review required: After manual generation, always perform a review according to image-alignment.md and writing-style.md (cannot be omitted) 6. concept-extractor can re-extract using the manual as the primary source (higher-quality knowledge)

Level 3: Knowledge + manual + skillification

In addition to all Level 2 processing: 7. skill-planner opus — generate a skillification plan and present it to the user

  • BLOCKER: Wait for the user's approval of the plan
  1. skill-synthesizer opus — generate the approved skill (cp via staging dir, direct writing to ~/.claude/skills/ is not allowed)

Parallel execution patterns

When calling each extractor, always follow the template below:

Agent起動時の必須パラメータ:
- model: "sonnet"  ← extractor系は必ずsonnet
- run_in_background: true
- mode: "bypassPermissions"

章をN分割してN Agent並列起動:
- 36章 → 4-6 Agent (各6-9章担当)
- visual-indexer: 特にコスト重い → 必ずsonnet & 並列必須

Guideline for degree of parallelism:

Process Parallel count model
concept-extractor 4 parallel sonnet
visual-indexer 4 parallel sonnet
procedure-extractor 4 parallel sonnet
Manual generation 6 parallel sonnet
skill-planner 1 (single) opus
skill-synthesizer 1 (single) opus

Review checkpoint (leading 1-chapter method)

Reviewing all chapters is slow. Not reviewing at all causes quality collapse. Solution: Complete only 1-2 chapters first for a sample review → if OK, process the remaining chapters in parallel all at once.

4 checkpoints

Phase A: 取り込み
  ↓
🔍 レビューA: 1章のtranscript + 5枚スクショをサンプル確認
  → 文字起こし精度OK?スクショ枚数・内容OK?
  → NG: 設定変更(chunk_seconds, interval等)して再実行
  → OK: 全章並列処理を継続

Phase B Level 1: ナレッジ抽出
  ↓
🔍 レビューB: 1章のknowledge.json + visual-index.json + procedures.json
  → 概念抽出の粒度OK?画像分類OK?手順の粒度OK?
  → NG: プロンプト調整して再実行
  → OK: 残り全章の並列処理を継続

Phase B Level 2: マニュアル生成
  ↓
🔍 レビューC: 2章のマニュアル(短い章+長い章)
  → 文章スタイルOK?画像配置OK?整合性OK?
  → NG: writing-style.md参照 + 該当章のみ再生成
  → OK: 残り全章継続

Phase B Level 3: skill-planner完了後
  ↓
✅ プラン承認BLOCKER(既存)
  ↓
Phase B Level 3: skill-synthesizer完了後
  ↓
🔍 レビューD: 1スキルのSKILL.mdサンプル確認
  → 実行可能?プロンプトテンプレ入ってる?
  → NG: synthesizer再実行
  → OK: 完了報告

Sample selection rules

review Sample selection
Review A A middle chapter (the 1st chapter is often short as an introduction)
Review B A chapter containing both concepts and procedures (because it cannot be classified)
Review C Two chapters: a short chapter + a long chapter (check quality at both extremes)
Review D The first completed executable skill (one is enough)

Compatibility with parallel processing

Parallel processing isnot stopped. Incorporate the sample review in the following way:

  1. First-chapter-ahead method: Start all Agents, but have only one Agent handle one chapter
  2. That one chapter completes first → present the sample → user confirmation
  3. Even during confirmation, the remaining Agents continue processing
  4. Confirmation NG → stop the remaining Agents → adjust the prompt → restart
  5. Confirmation OK → wait as is for all chapters to complete

BLOCKER

  • Review DOnly is approval-required BLOCKER.
  • Reviews A/B/C areWarningtreatment (processing can continue while confirming).
  • Stop processing only if a critical problem (path inconsistency, high error rate) is detected.

Output format: course-bundle

course-bundle/
  manifest.json
  chapters/
    00/
      transcript.txt
      transcript_ts.json
      screenshots/
        title.jpg
        frame_001.jpg ...
      page_text.md
      links.json
      manual.md             ← utage-manual output (Level 2+)
    01/ ...
  resources/
    prompts/
    pdfs/
    templates/
  resources-manifest.json

Structure of manifest.json

Schema: ~/.claude/skills/manabi-ingest/schemas/manifest.schema.json

{
  "course_name": "YouTube Booster",
  "source_type": "utage",
  "source_url": "https://...",
  "language": "ja",
  "speaker": "おさる",
  "chapters": [
    {
      "id": "03",
      "title": "生成AIを使いこなす4つの原理原則",
      "duration_seconds": 612,
      "transcript_path": "chapters/03/transcript.txt",
      "transcript_ts_path": "chapters/03/transcript_ts.json",
      "screenshots_dir": "chapters/03/screenshots/",
      "screenshot_count": 31,
      "page_text_path": "chapters/03/page_text.md",
      "links_path": "chapters/03/links.json",
      "status": "complete"
    }
  ]
}

NG / OK patterns

NG OK Reason
Start processing without user confirmation Confirm in Step 1 before starting Need to confirm the output destination and course name
Report completion without validating the manifest.json path Validate all paths in Step 4 Handing over a broken bundle causes all subsequent processing to fail
Set a nonexistent transcript to "status: complete" Set status accurately based on file presence A false status cannot be traced later
Move or delete the original file Copy and keep the original Corrupting the original data is irreversible
Error out even though there is no transcript_ts.json Set status to "partial" and continue Timestamps are not mandatory
Start knowledge extraction without presenting level selection Present level selection after Bundle completion The user determines the processing scope
Execute the skillization plan without approval Plan presentation → approval → execution Do not generate unnecessary skills
Stop the entire pipeline on resource acquisition failure Set to skipped and continue Resource acquisition is best-effort
Error out when there is no page text Save only what could be acquired Some chapters are video only
Run the extractor with opus Run with sonnet 3-5x cost difference
Process all chapters sequentially with 1 Agent Split chapters and run N Agents in parallel N times faster
Omit review after manual generation Review according to image-alignment.md Consistency validation is mandatory
skill-synthesizer writes directly to ~/.claude/skills/ cp via staging dir Countermeasure for Write permission block
Review all at once after all chapters are complete Sample review with the first chapter ahead Minimize rework cost
Stop parallel processing with sample review Confirm while continuing in parallel Do not sacrifice speed
Extract screenshots at 30-second intervals (--no-phash) Extract in pHash mode (default) Prevents missed slides and duplicates

Self-verification checklist

When processing is complete, verify the following:

Phase A (Bundle creation)

  • manifest.json exists and is valid as JSON
  • All transcript_path entries in manifest.json point to existing files
  • All screenshots_dir entries in manifest.json point to existing directories
  • Each chapter's screenshot_count matches the actual number of files
  • status accurately reflects each chapter's actual state (complete / partial / pending)
  • Original files have not been modified or deleted
  • page_text.md / links.json exist only for chapters that were successfully retrieved
  • resources-manifest.json exists and each entry's status is accurate

Phase B (level-specific processing)

  • All processing for the level selected by the user is complete
  • Level 2+: manual.md has been generated for all chapters
  • Level 3: The skill-ification plan has been approved by the user
  • Level 3: SKILL.md has been generated for the approved skills

Required environment

  • Python 3
  • ffmpeg (when processing video)
  • GROQ_API_KEY (when transcribing,.envsaved to file)
  • Chrome + Claude in Chrome extension (for UTAGE/Udemy URLs)

Dependent skills and scripts

Purpose path
HLS download ~/.claude/skills/utage-manual/scripts/hls_downloader.py
Transcription ~/.claude/skills/utage-manual/scripts/transcribe.py
Screenshot extraction ~/.claude/skills/utage-manual/scripts/screenshot_extractor.py
YouTube download video-downloader skill
Normalization ~/.claude/skills/manabi-ingest/scripts/normalize_bundle.py
Knowledge extraction concept-extractor skill
Image classification visual-indexer skill
Procedure extraction procedure-extractor skill
Manual generation utage-manual skill
Skill-ification plan skill-planner skill
Skill generation skill-synthesizer skill