lineage-skill

name	lineage-skill
description	Distills course materials into source-grounded AI agent skills. Use when the user wants to convert videos, audio, PDFs, slides, transcripts, OCR output, notes, or existing course distillation files into a CoursePackage and generated mentor, expert, consultant, practitioner, or custom Skill.

Lineage Skill

Turn course materials into reusable, source-grounded AI Skills.

Core method: Capture -> Cite -> Compress -> Connect -> Codify -> Evaluate. Use this as an evidence-first workflow: preserve source material before summarizing, cite sources before synthesizing, and mark unsupported gaps.

Read When Needed

• Runtime reference: references/runtime.md

Trigger Conditions

Use this skill when the user asks to:

• Distill a course, lecture series, workshop, training program, curriculum, or long-form class.
• Convert videos, audio, PDFs, slides, screenshots, notes, transcripts, OCR output, or course summaries into structured course knowledge.
• Generate or update a course-backed Skill.
• Build a course mentor, expert, consultant, practitioner, or custom course-backed Skill.
• Package existing transcripts/, analysis/, documents/, lesson_summaries.json, course_distillation_*.md/json, or course_package.json.

Capabilities

This Skill owns the course-distillation pipeline. Do not describe transcription, visual analysis, screenshot extraction, OCR collection, distillation, packaging, or generated-Skill creation as work the user must perform manually when suitable source files and configured providers are available.

Supported capabilities:

• Extract audio from .mp4 course videos and transcribe it through an OpenAI-compatible /audio/transcriptions endpoint.
• Directly transcribe standalone .mp3, .wav, .m4a, .aac, .flac, .ogg, and .opus course audio files.
• Split long audio into segments before transcription.
• Analyze video content through a vision-capable model, including PPT, board writing, software screens, diagrams, tables, demonstrations, and other visual teaching material.
• Compress and chunk large videos before visual analysis.
• Parse vision-model [SCREENSHOT MM:SS] markers, extract key frames from the original video, and de-duplicate similar screenshots.
• Collect MinerU/OCR Markdown outputs from PDFs or document directories.
• Distill transcripts, visual analyses, screenshots, OCR documents, and user notes into structured course notes.
• Build course_package.json, evidence_map.json, and lesson_index.json.
• Merge multiple course_package.json files into one combined multi-course workspace.
• Generate source-grounded course Skills in the requested role.
• Record durable pipeline progress in lineage_progress.json.
• Build a multi-course workspace catalog with scripts/build_course_catalog.py.

Provider Requirements

Capability is separate from configuration. If a provider is missing, report the missing configuration and the smallest viable fallback; do not imply the Skill lacks the capability.

• Audio transcription requires AUDIO_TRANSCRIBE_API_KEY, AUDIO_TRANSCRIBE_BASE_URL, and AUDIO_TRANSCRIBE_MODEL.
  • Chinese courses can use SenseVoiceSmall/FunASR-compatible transcription services.
  • English or multilingual courses can use Whisper-compatible or OpenAI transcription models when the endpoint supports them.
• Vision analysis requires LINEAGE_VISION_API_KEY, LINEAGE_VISION_BASE_URL, and LINEAGE_VISION_MODEL.
  • Prefer strong video/vision models for long videos, slides, boards, screenshots, diagrams, and software screens.
  • Gemini-class video models are appropriate when exposed through a compatible endpoint or adapter.
• Text distillation requires LINEAGE_TEXT_API_KEY, LINEAGE_TEXT_BASE_URL, and LINEAGE_TEXT_MODEL when DISTILL_USE_LLM=1.
  • Prefer long-context models with stable structured output and good support for the course language.
• PDF/OCR submission requires MINERU_API_TOKEN unless reusing existing MinerU output with --skip-submit.
• Local media handling requires installed ffmpeg and ffprobe.

When configuration is absent:

• If transcripts, OCR, notes, or previous distillation files already exist, skip the missing capture stage and continue with the smallest viable workflow.
• If raw audio or videos need transcription and ASR is missing, stop before transcription and tell the user exactly which variables or tools are missing.
• If raw videos need visual analysis and vision configuration is missing, stop before visual analysis or skip it only when the user accepts transcript-only processing.
• If PDFs are present but MinerU is not configured, continue with non-PDF sources and explain that scanned/image PDF evidence was not included unless existing OCR output is available.

Standalone audio files are transcribed by the capture stage, but they do not produce visual analysis or screenshots.

Decision Flow

1. Identify source state:
   • Videos/audio only: run the full pipeline.
   • Videos plus PDFs: run the full pipeline with document OCR if configured.
   • Existing transcripts/OCR/notes: skip capture; build package and Skill.
   • Existing CoursePackage: skip distillation; build or update Skill.
2. Choose role:
   • Default: mentor.
   • Use expert when the user specifically wants narrow course Q&A, concept explanation, or lesson lookup.
   • Use consultant when the user wants private consulting, diagnosis, or advice based on the course methods.
   • Use practitioner when the user wants checklists, playbooks, templates, workflows, or concrete work outputs.
   • Use custom when the user describes a specific role or workflow that does not fit the defaults.
   • Treat single-course, multi-course, and fused/domain packages as scope metadata, not role names.
   • Treat strict citation as an evidence strategy, not a role name.
   • Treat learning progress and daily study planning as a progress strategy, usually attached to mentor, not a separate role.
3. Preserve evidence before summarizing.
4. Before rerunning expensive stages, check existing outputs and resume from the smallest viable stage.
5. Generate outputs.
6. Verify expected files exist and report paths.

Workflows

Default paths:

• Use .lineage/courses/<course-name>/ for course build state unless the user provides --base-dir or a target directory.
• Use dist/<skill-name>/ for generated Skills unless the user provides --output-dir.
• Keep one source course per course workspace.
• If the user does not provide --skill-name, use the builder default:
  • <course-slug>-mentor-lineage for mentor.
  • <course-slug>-expert-lineage for expert.
  • <course-slug>-consultant-lineage for consultant.
  • <course-slug>-practitioner-lineage for practitioner.
  • <course-slug>-custom-lineage for custom.

Full Course Pipeline

Use when raw course videos and/or audio files need transcription, visual analysis where video exists, distillation, packaging, and Skill generation.

python scripts/run_course_pipeline.py \
  --input-dir <course-media-dir> \
  --course-name <course-name> \
  --skill-name <skill-name> \
  --mode mentor \
  --scope auto \
  --progress auto \
  --output-dir ./dist

With PDFs/OCR:

python scripts/run_course_pipeline.py \
  --input-dir <course-media-dir> \
  --documents-input <pdf-or-pdf-dir> \
  --course-name <course-name> \
  --skill-name <skill-name> \
  --mode mentor,practitioner \
  --scope auto \
  --progress tracked \
  --output-dir ./dist

Before using PDFs, check MINERU_API_TOKEN. If it is missing, read references/runtime.md and explain the fallback.

Existing Materials

Use when the user already has transcripts, OCR, notes, summaries, or distillation outputs.

python scripts/build_course_package.py \
  --course-name <course-name> \
  --source-dir <course-dir>

python scripts/build_course_skill.py \
  --course-name <course-name> \
  --skill-name <skill-name> \
  --mode <mode> \
  --scope auto \
  --source-dir <course-dir> \
  --output-dir ./dist

Existing CoursePackage

If <course-dir>/course_package.json already exists, run only build_course_skill.py unless the user asks to rebuild the package.

Multi-Course Skill

Use when the user wants one generated Skill from multiple distilled courses.

First merge course packages:

python scripts/build_multi_course_package.py \
  --course <course-a-dir-or-package> \
  --course <course-b-dir-or-package> \
  --combined-name <combined-course-name> \
  --output-dir .lineage/courses/<combined-course-slug>

Then build one Skill:

python scripts/build_course_skill.py \
  --course-name <combined-course-name> \
  --source-dir .lineage/courses/<combined-course-slug> \
  --mode expert \
  --scope multi-course \
  --output-dir ./dist

Use mentor, expert, consultant, practitioner, or custom according to the user's goal. Preserve source-course distinctions when courses disagree.

Validation Loop

After generation, verify:

<generated-skill>/
├── SKILL.md
├── agents/
├── references/
├── scripts/search_course_notes.py
└── lineage_manifest.json

Check:

• lineage_manifest.json exists and includes generated_by.id: lineage-skill.
• lineage_manifest.json includes roles, scope, evidence_strategy, and progress_strategy.
• references/course_package.json exists.
• references/evidence_map.json exists.
• references/lesson_index.json exists.
• Role-specific reference files exist for requested roles.
• scripts/search_course_notes.py is executable.
• <course-dir>/lineage_progress.json exists after a full pipeline run.
• <base-dir>/course_catalog.json is updated after a full pipeline run.

If validation fails, fix the missing artifact and rerun the smallest necessary command.

Response Rules

• State which source state was detected and which workflow you used.
• Prefer the smallest pipeline that fits the user's materials.
• Name the generated Skill path and important reference files.
• Distinguish direct course content, course-grounded synthesis, and your own inference.
• If support is missing, say what evidence is missing.
• Never write real API keys into repository files or commit .env.
• Do not commit private transcripts, screenshots, OCR output, or course distillation artifacts unless the user explicitly wants to publish them.
• For medical, legal, financial, investment, or other high-stakes courses, keep answers educational and source-bounded.