AI Shifu Course Creator Agent Skill

Course Creator

Convert raw course material into runnable, optimized MarkdownFlow lesson scripts and deploy them as live AI-Shifu courses.

Execution Modes

• Standard mode (default): Input quality is sufficient; run requested phases in full.
• Fallback mode: Input is incomplete or low quality; produce coarse outputs, mark uncertainty, and provide focused rerun hints.

Language Resolution Policy

See references/language-resolution.md for the full policy.

Resolve target language with this strict priority:

• explicit_output_language_request
• target_language_parameter
• session_language_preference
• prompt_language_detection
• source_material_dominant_language
• default_fallback_language (en-US)

Authoring Control Inputs

Use these optional controls across all phases:

• course_profile (json): audience level, prerequisite level, lesson duration target, lesson count target, and assessment mode.
• delivery_constraints (json): interaction density, platform limits, must-cover topics, avoid topics, and non-negotiable source fragments.

See references/input-contract.md for recommended object shapes.

Output Boundary

• Final outputs are learner-facing teaching content only.
• Authoring rules, pipeline notes, and process instructions stay in skill docs and references, not in lesson outputs.
• Internal design notes may appear only in HTML comments when needed.

Pipeline Overview

Phase 1: Segmentation → Phase 2: Orchestration → Phase 3: Generation → Phase 4: Optimization → Phase 5: Deployment

Usage Paths

Path A: End-to-End

Run all five phases from raw material to a live deployed course.

• Phase 1: Segment raw material into semantic units.
• Phase 2: Orchestrate lesson boundaries and generate scripts.
• Phase 3: Generate per-lesson MarkdownFlow scripts (called internally by Phase 2).
• Phase 4: Audit and optimize final scripts.
• Phase 5: Build, import, and publish to the AI-Shifu platform.

Path B: Author Only

Run Phase 1–4 to produce optimized MDF scripts without deploying. Sub-paths:

• Segment only: Phase 1 alone for structured segments and manual review.
• Generate only: Phase 3 alone on pre-existing segments to produce lesson scripts.
• Optimize only: Phase 4 alone to audit and improve existing MarkdownFlow scripts.

Path C: Deploy Only

Run Phase 5 alone to deploy pre-existing MDF files to the AI-Shifu platform.

Path D: Manage Existing

Use Phase 5 management commands (list, show, update, rename, reorder, delete, publish, archive) on courses already on the platform.

Phase 1: Segmentation

Turn messy course source material into a reliable intermediate structure for downstream lesson generation.

Workflow

• Remove filler language and duplicated phrasing without changing meaning.
• Mark immutable blocks: code, images, and tables.
• Segment by semantic continuity instead of headings alone.
• Propose lesson boundaries with one core question per lesson.
• Return source-linked structured segments.

Segment Schema

Each segment includes:

• segment_id
• segment_type (concept, example, code, image, exercise, transition)
• core_point
• preserve_block (yes or no)
• source_span

Transfer Signals

Capture these fields for downstream teaching quality:

• learner_hook: statements that can trigger learner reflection.
• evidence_type: one of history, phenomenon, data, mechanism, or conclusion.
• visual_cue: fragments suited for SVG/HTML visual support.
• concept_conflict: candidate idea conflicts for cognitive contrast.
• boundary_cue: clues for validity boundaries.
• action_cue: clues that can become immediate or staged actions.
• density_cue: high-information chunks that should not be diluted.
• quote_cue: original wording worth preserving.
• visual_text_pair_cue: clues for "visual first, explanation second" blocks.
• interaction_intent_cue: intent labels such as diagnose, branch, calibrate, compare.
• compare_cue: candidate prompts for before/after comparison.

Phase 1 Outputs

• Ordered segment list.
• Lesson boundary candidates.
• One core question per lesson.
• Preservation block index.
• Full transfer-signal package.

See references/segmentation-rules.md.

Phase 1 Validation

• Segment output covers all valid source spans in traceable order.
• Code/image/table blocks keep original placement and format.
• Every lesson candidate resolves to one core question.
• Transfer-signal fields are complete and usable downstream.
• Cleanup does not alter key facts or terminology.

Phase 2: Orchestration

Convert raw course material into runnable lesson-level MarkdownFlow scripts by coordinating segmentation and generation.

Workflow

• Normalize source ordering and merge input material.
• Run Phase 1 for cleanup and semantic segmentation.
• Generate lesson-cut candidates with one core question each.
• Run Phase 3 for lesson-level MarkdownFlow scripts.
• Build course index and global variable table.
• Recompute only failed lessons through strict gating.

Mandatory Gates

All gates must pass:

• Code blocks are preserved character-by-character.
• Image links and relative placement are preserved.
• Each lesson resolves one core question.
• Each lesson contains at least one valid MarkdownFlow interaction, max five interactions total.
• Each lesson includes a minimum teaching loop: setup, explanation, interaction, close.
• Lesson language is learner-facing, not pipeline narration.
• Each lesson includes at least one deepening interaction (calibration, boundary check, or counterintuitive prompt).
• Action tasks are either immediately executable or explicitly linked to later modules.
• Variable naming is consistent and traceable.
• No unresolved placeholder variables in learner-facing text.
• Do not wrap full lessons in deterministic blocks (=== === or !=== !===).
• Deterministic blocks are reserved for legally or operationally fixed statements only.
• If an image must remain unchanged, use single-line deterministic syntax per image.
• Use --- between instructional blocks to keep pacing readable.
• Every variable collection step must produce immediate feedback and downstream effect.
• Core knowledge points require visual + textual explanation together.
• Consecutive variable collection cannot exceed three variables.
• Do not recollect the same variable unless explicitly marked as staged comparison.
• Never reference uncollected variables.
• Interaction prompts must be concrete and directly answerable.
• Avoid repetitive interaction semantics across lessons unless comparison intent is explicit.
• *_viewpoint_check interactions must branch by option and drive different next steps.
• Every interaction variable must create visible downstream impact.

Rerun Rules

• Recompute only impacted lessons.
• Recompute dependency-linked lessons when shared variables change.
• Recompute full course only when global source order changes.

Failure Handling

When source quality is weak:

• Deliver coarse lesson drafts first.
• Mark uncertain spans explicitly.
• Continue with best-effort generation instead of stopping.

Phase 2 Outputs

• Lesson MarkdownFlow scripts (one file per lesson).
• Course index (lesson id, title, core question, source mapping).
• Global variable table (definition, use, cross-lesson references).

See references/output-contract.md and references/preservation-rules.md.

Phase 2 Validation

• Lesson scripts, course index, and variable table are all present.
• Code/image preservation is exact and position-safe.
• One-core-question and interaction cap rules are satisfied per lesson.
• No unresolved variables or no-op interactions remain.
• Fallback outputs include explicit uncertainty markers and rerun hints.

Phase 3: Generation

Generate runnable MarkdownFlow scripts for each lesson.

Teaching Pattern Baseline

Use these defaults unless lesson content requires a justified variation:

• Learner-facing language only.
• Variable collection is distributed, not front-loaded.
• Build evidence chain from observation to mechanism to conclusion.
• Use visual-first explanation for abstract concepts, then textual interpretation.
• Every collected variable must immediately affect downstream content.
• Include at least one deepening interaction (calibration, boundary check, or misconception correction).
• Include at least one reusable deliverable.
• Action steps must be immediately executable or explicitly staged for downstream lessons.
• Use carryover statements only if cross-lesson dependency is allowed.

10. Avoid exposing internal authoring terms in learner-facing text.

11. Keep interaction prompts concrete and answerable.

12. *_viewpoint_check prompts must branch with distinct feedback paths.

13. Repeated interaction patterns are allowed only when framed as staged comparison.

See references/teaching-patterns.md and references/cognitive-techniques.md.

Single-Lesson Generation Strategy

Required anchors:

• Opening objective plus visual cover.
• Evidence-chain explanation.
• At least one effective interaction with visible downstream effect.
• At least one reusable deliverable.
• Lesson close with summary or decision checkpoint.

Optional modules:

• Viewpoint calibration.
• Misconception correction.
• Dual deliverables (understanding + action).
• Cross-lesson bridge sentence.
• Additional visual-text reinforcement blocks.

Variable Strategy

• Prefer at most one variable collection per module.
• Max five interactions per lesson (recommended three to four).
• No more than three consecutive variable collections before feedback.
• Reuse global variables when possible; add lesson-local variables only when required.
• Every variable must have downstream utility (branching, depth control, or deliverable variation).
• No unresolved placeholders in learner-facing text.
• Do not recollect the same variable unless explicitly marked as staged comparison.
• Prevent semantic duplicates even when variable names differ.

Visual-Text Coordination

• Include an SVG cover in each lesson by default.
• Every core concept must include at least one visual-plus-explanation pair.
• Visuals compress structure; text explains mechanism, limits, and pitfalls.
• Replace unstable source images with generated SVG/HTML visuals when needed.

Interaction Design

• Use no more than one viewpoint_check in a lesson unless justified.
• Each viewpoint_check must trigger a concrete next action.
• If using a "restate-boundary-counterintuitive" pattern, branch by option with distinct content.

Phase 3 Outputs

Return per lesson:

• lesson_id
• lesson_title
• mdf_script
• used_variables
• depends_on_lessons

See references/lesson-template.md.

Phase 3 Validation

• Minimum teaching loop exists (setup, explanation, interaction, close).
• Interaction outcomes visibly alter downstream content.
• Variable safety rules pass (collect before reference, no duplicate recollection).
• Core concepts satisfy visual-plus-text coordination.
• Script remains valid and runnable MarkdownFlow.

Phase 4: Optimization

Audit and improve existing MarkdownFlow teaching prompts. This phase is not for writing from scratch.

When to Use

• Gap analysis against source material.
• Script quality upgrades without full rewrites.
• Consistent chapter style with lower runtime failure risk.

Core Method

• Start with a low-friction entry point (cover visual + one light interaction).
• Ensure interactions change downstream logic.
• Keep structure content-driven, not template-driven.
• Build evidence chain: observation/history -> mechanism/data -> conclusion.
• Use visuals for abstract structure and text for mechanism + boundaries.
• Add viewpoint calibration with branching feedback.
• Include concrete correction actions for major misconceptions.
• Keep deliverables executable and reusable.
• Stabilize syntax and variable usage.

See references/optimization-methodology.md.

High-Standard Constraints

• Separate knowledge blocks with ---.
• Include a lesson cover visual by default.
• Keep max interactions per lesson at five (recommended three to four).
• Place interactions at decision points, not only at lesson start.
• Every interaction must trigger immediate feedback plus downstream effect.
• Limit consecutive variable collection to three.
• No uncollected variables in learner-facing text.
• Spread global variable collection across lessons.
• Do not recollect the same variable unless marked as staged comparison.
• Treat semantic duplicates as duplicates even if variable names differ.
• Use stable input syntax: ?[%{{var}}...prompt].
• Keep ending structure lesson-appropriate; interactive endings are optional.
• Every core concept needs visual-plus-text explanation.
• Avoid internal authoring terms in learner-facing copy.
• Keep prompts concrete and answerable.
• *_viewpoint_check interactions must branch by option.
• Preserve source information density; do not trade substance for fluency.

Optimization Workflow

• Define scope (single lesson vs full course).
• Build coverage matrix: source points -> script coverage.
• Label issue classes:
• coverage_gap
• meaning_shift
• explanation_clarity
• interaction_no_branching
• visual_constraints_missing
• variable_or_syntax_risk
• Apply smallest safe edits first.
• Run checklist validation before final output.
• Re-check visual-text pairing for every core concept.
• Re-check variable lifecycle (collection, reference timing, reuse).
• Re-check semantic duplication in interaction prompts.
• Re-check viewpoint branching and downstream action coupling.

See references/review-checklist.md.

Required Output Style

• Present conclusion and risk level first.
• Then provide grouped change list by issue class.
• Use file-level references for traceability.
• If duplicate script versions exist, declare the authoritative one.
• If cross-lesson dependency is disallowed, remove dependency text and unbound carryover variables.

Common Failure Patterns

• Structural edits without content-depth recovery.
• Over-abstraction that drifts from source meaning.
• Hidden cross-lesson variables causing runtime failures.
• Vague prompts that models cannot execute reliably.
• Viewpoint options that still return identical feedback.
• Repeated semantic questions with different variable names.
• Visual tasks without explanatory text.
• Rigid template consistency at the cost of lesson specificity.

Phase 4 Validation

• Conclusion and risk level are presented first.
• All issue classes are fully audited.
• viewpoint_check interactions branch and trigger distinct next actions.
• Uncollected variable references and semantic duplicate interactions are removed.
• Output remains runnable with no loss of source information density.

Phase 5: Deployment

Deploy optimized MDF lesson scripts to the AI-Shifu platform as live courses.

Prerequisites

• Python 3 with requests and python-dotenv packages installed.
• CLI script: {skillDir}/scripts/shifu-cli.py

Authentication

See references/cli-reference.md for the full login flow.

When no valid token is available, guide the user through the login process:

• Ask the user to choose their region (China mainland / non-China-mainland).
• For China mainland: use the SMS login flow via shifu-cli.py login.
• For non-China-mainland: instruct the user to log in manually and set SHIFU_TOKEN in {skillDir}/.env.

Always use CLI commands. Never make raw HTTP/API calls directly.

Course Directory

MDF lesson scripts must be organized in a course directory before deployment. See references/course-directory-spec.md for the full specification.

When continuing from Phase 4 (Path A), write optimized scripts into the course directory structure automatically.

CLI Quick Reference

Core deployment commands:

build --course-dir ./course-a/                          # Build shifu-import.json (offline)
import --new --json-file ./course-a/shifu-import.json   # Import as new course
publish <shifu_bid>                                      # Make course live
show <shifu_bid>                                         # Verify course structure

See references/cli-reference.md for the complete command reference and references/import-json-format.md for the JSON schema.

Deployment Workflow

From pipeline (Path A continuation):

• Write Phase 4 outputs into the course directory (lessons/, README.md, system-prompt.md, optional structure.json).
• Run build --course-dir <dir> to generate shifu-import.json.
• Run import --new --json-file <dir>/shifu-import.json to create the course.
• Run publish <shifu_bid> to make it live.
• Verify via platform URL.

Standalone deployment (Path C):

• Ensure course directory is ready with MDF files.
• Run build, import, publish as above.

Common Management

Use these commands for ongoing course operations (Path D):

list                                                   # List all courses
show <shifu_bid>                                       # Show course outline
update-meta <shifu_bid> --name "..." --description "..."
update-lesson <shifu_bid> <outline_bid> --mdf-file updated.md
rename-lesson <shifu_bid> <outline_bid> --name "New Name"
reorder <shifu_bid> --order bid1,bid2,bid3
delete-lesson <shifu_bid> <outline_bid>
publish <shifu_bid>
archive <shifu_bid>

Verification

After any deployment or management operation, verify the result:

• Admin console: https://app.ai-shifu.cn/shifu/<shifu_bid> (cn) or https://app.ai-shifu.com/shifu/<shifu_bid> (global)
• Preview: https://app.ai-shifu.cn/c/<shifu_bid>?preview=true
• Check each lesson's MDF content, variable collection, and interaction logic.

Phase 5 Validation

• Import completes without errors.
• Course is accessible via platform URL.
• Lesson count and structure match the source directory.
• Published course is reachable in preview mode.

MarkdownFlow Syntax (Required)

See references/markdownflow-spec.md for the quick reference.

• Variables:
• Use {{var_name}} for references.
• Variable names cannot contain spaces.
• Undefined variables default to "UNKNOWN".

• Interactions:
• Single-select: ?[%{{var}} Option A | Option B | Option C]
• Multi-select: ?[%{{var}} Option A || Option B || Option C]
• Input: ?[%{{var}} ... enter your answer]
• Button + input: ?[%{{var}} Option A | Option B | ...Other, please specify]

• Segments:
• Use --- between segments.
• Each segment should serve one clear instructional objective.

• Deterministic output:
• Single-line fixed text: ===fixed text===
• Multi-line fixed text:

   !===
   Line 1
   Line 2
   !===

• Authoring principle:
• Script text should guide generation behavior.
• Do not output full polished learner prose as fixed text.
• Never lock full lesson bodies inside deterministic blocks.
• For fixed images, use one deterministic line per image.
• After each interaction, restate learner selection and reflect it in downstream content.
• For input prompts, include example phrasing to reduce blank responses.
• Use stable input syntax: ?[%{{var}}...prompt].

Shared Constraints

Preservation Rules

See references/preservation-rules.md.

Must preserve:

• Code content and fence language.
• Image URLs, alt text, and relative placement.
• Domain terms and factual statements.

Can normalize:

• Speech filler.
• Sentence breaks and punctuation.
• Redundant transitions.

Variable Rules

• Collect before reference; never use uncollected variables.
• No more than three consecutive variable collections before feedback.
• Max five interactions per lesson (recommended three to four).
• Every variable must produce downstream utility.
• No unresolved placeholders in learner-facing text.
• Do not recollect the same variable unless explicitly marked as staged comparison.
• Prevent semantic duplicates even when variable names differ.
• Reuse global variables when possible.

Interaction Rules

• Each lesson includes at least one deepening interaction (calibration, boundary check, or misconception correction).
• Interaction prompts must be concrete and directly answerable.
• *_viewpoint_check interactions must branch by option and drive different next steps.
• Avoid repetitive interaction semantics across lessons unless comparison intent is explicit.
• Every interaction variable must create visible downstream impact.

Validation Checkpoints

Phase 1 (Segmentation)

• Source span traceability and immutable block preservation.
• One core question per lesson candidate.

Phase 2 (Orchestration)

• All mandatory gates pass.
• Course index, variable table, and lesson scripts are complete.

Phase 3 (Generation)

• Teaching loop, variable safety, visual-text coordination.
• Script is valid runnable MarkdownFlow.

Phase 4 (Optimization)

• All issue classes audited.
• Interaction branching and variable lifecycle validated.
• No loss of source information density.

Phase 5 (Deployment)

• Import completes without errors.
• Course is accessible and lesson structure matches source.
• Published course is reachable in preview mode.

Report Template

See references/report-template.md.

Examples

• examples/pipeline-full.md
• examples/segmentation-only.md
• examples/generation-only.md
• examples/optimization-only.md
• examples/fallback-mode.md
• examples/end-to-end-deploy.md
• examples/deploy-only.md