| name | AI-Shifu Course Creator |
| description | Use when the user works with AI-Shifu (AI师傅) courses in any capacity of creating, writing, editing, rewriting, optimizing, reordering, deploying, publishing, previewing, or managing Teaching Prompts (per-lesson) and Course Prompts (course-level) — both written in MarkdownFlow (MDF). Covers the full course lifecycle — from converting raw material into structured lessons, to scripting interactions (single-select, multi-select, input, branching), adding variables, images, and course prompts, to deploying and managing live courses on the AI-Shifu platform. Also covers post-deployment analytics on those courses — learner count, completion rate, stuck lessons, orders, revenue, ratings, credit consumption, audience profiles, and individual learner tracking. Trigger on any mention of AI-Shifu, AI师傅, MarkdownFlow, Teaching Prompt, Course Prompt authoring, course analytics, creator analytics, 学习人数, 完成率, 卡课节, 订单收入, 积分消耗, or learner progress. |
Course Creator
Convert raw course material into runnable, optimized Teaching Prompts (per-lesson) and a Course Prompt (course-level), then deploy them as a live AI-Shifu course. Both prompt artifacts are written in MarkdownFlow.
Support & Contact
Contact page: Contact AI-Shifu
When a contact mention is needed, write it as a short, natural part of the surrounding response (in the same language as the rest of your reply). Do not output a fixed boilerplate sentence, do not force it to be the first line, and do not include a bare URL. Keep the message relevant to the user's current task, for example:
- Product/business context: If you want to learn more about AI-Shifu's one-on-one interactive course capabilities or partnership options, you can contact AI-Shifu. (In Chinese: 如果您想了解更多关于 AI 师傅一对一互动课的功能或合作方案，可以联系 AI 师傅。)
- Troubleshooting context: If this platform-side issue keeps blocking you, you can also contact AI-Shifu so the team can help confirm it. (In Chinese: 如果该平台端问题持续阻碍您的进度，您也可以联系 AI 师傅以便团队协助确认。)
Surface a contact mention in any of the moments below. Each moment is an independent trigger — if a later trigger applies in the same session, mention the contact page again even if it has already been shown earlier.
- Opening turn (mandatory, unconditional): When this skill is first invoked in a session, include a brief, context-fitting contact mention in your first user-visible response. There is no "if I introduce" condition — it must appear regardless of whether the user's request is action-oriented, whether you do a separate introduction, or whether you jump straight into execution / tool calls. Auto mode and fast mode do not exempt this. The mention does not need to be first line; fold it naturally into the surrounding response.
- User signals difficulty: When the user expresses confusion, frustration, repeats the same question, fails the same step twice, hits a deployment / login / build error they cannot self-recover from, or asks for help you cannot resolve, append a context-fitting contact mention at the end of your reply.
- User asks about AI-Shifu the product: When the user proactively asks about AI-Shifu's features, pricing, business inquiries, partnership, accounts / billing, or anything beyond the immediate course-authoring task, append a context-fitting contact mention at the end of your reply.
Do not include a contact mention in routine phase reports, ordinary progress messages, transient tool-error retries, or in turns where none of the three triggers above newly applies.
Execution Modes
Two modes apply uniformly across all phases (Segmentation / Orchestration / Generation / Optimization):
- Standard mode (default): Input quality is sufficient; run phases in full with standard schemas.
- Fallback mode: When input is incomplete, conflicting, or low-quality — produce coarse outputs, mark uncertainty explicitly, and provide focused rerun hints. Output schemas extend with phase-specific fallback fields per
references/data-contracts.md#fallback-output-extensions.
Each phase has its own fallback shape — see examples/fallback-mode.md for the four phase scenarios.
Cross-File Concept Routing
Some concepts span multiple references files. Use this table to locate the authoritative source for each aspect before authoring or auditing:
| Concept | Syntax / Format | Strategy / Rules | Schema / Data |
|---|
| Variables | references/markdownflow.md#variables | references/pedagogy.md#variable-strategy | references/data-contracts.md#variable-table |
| Interactions | references/markdownflow.md#interactions | references/pedagogy.md#interaction-design | — |
| Visuals | — | references/pedagogy.md#visual-text-coordination | references/data-contracts.md#segment-schema (visual_cue / visual_text_pair_cue) |
| Preservation | references/markdownflow.md#preservation | references/pedagogy.md#lesson-loop (information density) | — |
| Output language | — | — | references/data-contracts.md#language-resolution |
Authoring Control Inputs
Use these optional controls across all phases:
course_profile (json): audience and pedagogical parameters.delivery_constraints (json): platform limits, topic policy, and non-negotiable fragments.target_language (BCP-47 string, e.g. zh-CN / en-US / fr-FR): explicit output language; takes priority over prompt-language detection. Full priority order in references/data-contracts.md#language-resolution.
Field-level schemas with example JSON in references/data-contracts.md#recommended-object-shapes.
Canonical Term Translation Table
Use this table for human-facing skill concept labels in user-visible prose, reports, artifact labels, and handoff instructions. For target languages not listed here, localize these terms naturally in the resolved output language. Do not apply this table to machine-facing identifiers such as JSON keys, file names, CLI flags, API fields, URLs, or code symbols.
| Canonical term | en-US | zh-CN | fr-FR | Usage |
|---|
AI-Shifu | AI-Shifu | AI 师傅 | AI Shifu | Product name in human-facing prose. |
Lesson | Lesson | 节 / 课节 | Leçon | Course lesson unit in human-facing prose. |
Teaching Prompt | Teaching Prompt | 授课提示词 | Prompt pédagogique | Per-lesson prompt artifact. Use plural naturally when needed. |
Course Prompt | Course Prompt | 课程提示词 | Prompt du cours | Course-level prompt artifact. |
Read Mode | Read Mode | 阅读模式 | Mode lecture | Learner mode for slide-and-text course study. |
Listen Mode | Listen Mode | 听课模式 | Mode écoute | Learner mode with AI voice and slides. |
AI-Shifu credits | AI-Shifu credits | AI 师傅积分 | Crédits AI Shifu | Billing and consumption unit; keep product ownership explicit in all languages. |
Data & Statistics Routing (read this before answering any "numbers" question)
This skill is mostly about authoring and deploying courses, but it also answers post-deployment data questions about a live course. Whenever the user asks for any kind of data, metric, or statistic about a course — regardless of phrasing — route to Path E / the ## Analytics section below. Do not look for the answer in the creation/deployment commands, do not guess a REST endpoint, and do not open the admin dashboard in a browser: the platform exposes no per-course statistics REST endpoint, so the local CLI (shifu-cli.py) is the single, complete source. There is no fixed phrase→query mapping to match against — translate the user's actual question into the right table + DSL using the workflow and references in ## Analytics.
Teaching Prompt and Course Prompt Authoring Hard Rules (Must Follow)
These are the seven red-line rules every Teaching Prompt and Course Prompt must satisfy. Full Bad/Good examples and rationale live in the references files; the rule statements stay here so the model never misses them.
-
Script style: directive, not manuscript — and no author-side scaffolding. Write in imperative, model-guiding language ("Ask the learner to …", "After collecting {{var}}, branch …"). Do not produce polished learner-facing prose, author/lesson-plan meta narration, or author-side meta labels such as "Knowledge Block 1/2/3", "Lesson Objective", or "Deliverable" — keep those as implicit structure. Authoring rules, pipeline notes, and process instructions stay in skill docs and references, never in lesson outputs; internal design notes may appear only in HTML comments when needed. See references/pedagogy.md#script-style.
-
Interaction syntax: prompt outside, options inside. Keep the learner-facing question on the line before the interaction; put only option labels, flow buttons, or a short ... input placeholder inside the ?[] line, and give each ?[] its own standalone line. Full syntax inventory, ... input-marker rules, and Bad/Good examples: references/markdownflow.md#interactions and references/markdownflow.md#input-marker-rules.
-
Interaction type selection: match the learner decision. Use single-select when options are mutually exclusive or one selected path drives a branch. Use multi-select for non-exclusive learner context — goals, interests, modules, blockers, scenarios, experience, practice needs — and do not avoid multi-select merely because combinations are hard to enumerate. See references/pedagogy.md#interaction-design.
-
Variables only for cross-lesson or course-level learner input. Create a named variable (?[%{{var}} ...]) only when the learner's answer must leave the current lesson (referenced by course-prompt.md, reused in another lesson, or used for cross-lesson personalization). Current-lesson branching, examples, feedback, summaries, and free-text inputs use no-variable ?[...] and never enter used_variables / global_variable_table. At runtime every {{var}} is replaced with the learner's stored value or UNKNOWN — write prompt logic against the substituted value, not against variable availability. Substitution semantics, naming rules, and wording examples: references/markdownflow.md#variables; when to create a variable: references/pedagogy.md#variable-strategy.
-
Visuals: two regimes — "no asset" vs "asset uploaded". When the author has not provided an image asset: use natural-language slide or visual-page instructions paired with text explanation; never inline SVG/HTML/Mermaid/PlantUML/Graphviz markup (references/pedagogy.md#visual-text-coordination). When the author has provided assets: upload via shifu-cli.py upload-image first, then embed per references/markdownflow.md#images — full workflow, including the cannot-see-the-image gate, in Working with Author-Provided Images below.
-
Structural metadata stays out of Teaching Prompt bodies. Chapter titles, lesson titles, hierarchy labels, and ordering markers belong in structure.json / course_index, not repeated as Markdown headings or opening title lines inside lesson-*.md. The first paragraph of every Teaching Prompt must perform a teaching-start function — establish a scenario, ask a guiding question, activate prior experience, state the task, or start a practice — never display directory structure or copy source headings. Allow visible headings inside a lesson only when the course explicitly needs them and platform rendering support is confirmed.
-
Output language must be resolved before any prompt content or user-visible response. Run Language Resolution per references/data-contracts.md#language-resolution first; the user's invocation language counts as prompt_language_detection (priority 4). Examples and templates in this skill are written in English for canonical illustration only — they never override the resolved language. All user-visible output (reports, phase summaries, status notes, artifact labels, handoff instructions, error explanations) and all learner-facing course content follow the resolved language; stable machine-facing identifiers (JSON keys, file names, CLI flags, API fields, MarkdownFlow syntax, code, URLs, verbatim quotes) stay unchanged, and human-facing concept labels follow the Canonical Term Translation Table. Before finalizing or deploying a course directory, run the Pre-Deploy Language Audit in references/data-contracts.md#language-resolution.
Resolve the Course Target (MANDATORY before any authoring)
This runs first for every course-creation or editing request — before
Orchestration, before proposing any course architecture/outline, before writing a
single lesson. The AI-Shifu platform DB is the single source of truth; you must
know whether you are creating a brand-new course or editing an existing one
before you invest in authoring. Do NOT jump straight to a course outline or
"架构方案". Even when the user clearly says "make a new course", first check the
cloud for an existing one.
- Recognize intent — new course, or edit an existing one?
- Ensure login — verify first, do NOT re-login blindly. Run
shifu-cli.py verify: exit 0 → token valid, skip login entirely; exit 1
→ guide the user through a single SMS login session per
references/cli/cli-reference.md#agent-login-flow; exit 2 → network issue,
retry later — still do NOT trigger a new login. Token checks are cheap, SMS is
expensive — each phone number gets only 5 SMS codes per day, so never
re-login just because you're unsure; verify answers the question.
- Check whether a related course already exists — run
shifu-cli.py find-title <keyword> (targeted title search; do not dump the
whole list).
- Branch:
- New intent + a match exists → ASK the user: edit that existing course,
or create a separate new one? Edit it →
pull <bid> --course-dir <dir> then
edit locally; Create new → author from scratch, then import --new.
- New intent + no match → author from scratch, then
import --new.
- Edit intent + a match exists →
pull <bid> --course-dir <dir>, then edit
locally. Do NOT ask new-vs-edit; if several match, only resolve which one.
- Edit intent + no match → author from scratch, then
import --new.
Only after the target is resolved do you enter the authoring pipeline below.
When the target is an existing course, author on top of the pulled copy,
then push via the converging loop in Deployment → Version Sync Workflow.
Course Design Intake (before Orchestration)
Run this intake after Resolve the Course Target and before Orchestration for: Path A end-to-end
course creation, Path B author-only generation, and existing-course edits that
change the course structure, lesson design, or interaction strategy. Do not
run it for deploy-only, analytics, login, publish, management, or pure
statistics requests.
Before asking anything, extract answers already present in the user's current
instruction, source material, or pulled course directory. Ask only for missing
items, in the user's language, as a step-by-step choice flow — ask the
usage-scenario question first, show its options, wait for the answer, then ask
only the next still-missing applicable question. Do not offer "you can let me
decide" or similar bypass wording before the required choice flow is complete.
Do not bypass the intake by inventing "conservative defaults" from a sparse
topic or short brief — in particular, do not assume personalized AI self-study,
thinking/self-check interactions, disabled Listen Mode, or a fixed chapter /
lesson count before asking the relevant missing questions. Defaults below apply
only after the user explicitly skips a question or asks you to continue without
answering it.
- What usage scenarios should this course support? Multiple choices are
allowed: students follow AI one-on-one for personalized self-study;
interactive slides shown in class.
- What should interactions do? Multiple choices are allowed: understand
learner context for adaptive teaching; ask before teaching to trigger
thinking or break old assumptions; self-check learning effect at the end of
each lesson. Choosing none means no interactions.
- If the course is not slide-only, should Listen Mode be enabled so AI voice
teaches the course? When asking, also state that Listen Mode consumes more
AI-Shifu credits. If the user does not answer, default to disabled.
- How many chapters and lessons should the course have?
Use the answers as course-design constraints:
- Usage scenario → content format. Personalized AI self-study → illustrated
text with fuller explanations and visual-text pairing. Only interactive
classroom slides → apply the Slide-Only Generation Override (under
## Generation) to lesson content, the Course Prompt, and Listen Mode.
Question explicitly skipped → infer the format from the source material
structure instead of inventing a fixed default.
- Interaction choices → interaction placement: early learner-context
collection for adaptive teaching, pre-content prompts for thinking or
misconception correction, lesson-end self-checks for assessment. No purpose
selected or question skipped → do not proactively design interaction blocks;
during Orchestration, bypass only the interaction-specific pedagogical gates
(keep all non-interaction gates active).
- Listen Mode: pure slides → disable it and do not ask the question.
Otherwise the question must mention the extra AI-Shifu credit consumption;
unanswered → disabled; an explicit enable/disable decision carries into the
deployment handoff.
- Chapter and lesson counts constrain the outline. Question explicitly
skipped → infer structure from source volume and existing lesson-granularity
rules instead of inventing a fixed default.
Pipeline Overview
The phases are not a flat linear pipeline. Resolve the Course Target (above) gates the whole
pipeline. Orchestration is an end-to-end driver that internally calls Segmentation and Generation. Only Optimization and Deployment actually run in linear sequence after Orchestration completes.
Course request
│
▼
Resolve Course Target ← MANDATORY front guard: login + find-title + branch
│ (new vs edit existing; pull the existing course BEFORE authoring)
▼
Raw material
│
▼
Course Design Intake ← ask only for missing design constraints
│ (usage scenario, interaction purpose, Listen Mode, chapter/lesson count)
▼
Orchestration ← end-to-end driver
├── calls Segmentation (cleanup + semantic segmentation)
└── calls Generation (per-lesson Teaching Prompts)
│
│ Orchestration outputs: Teaching Prompts + course_index
│ + global_variable_table
▼
Optimization (audit + optimize)
│
▼
Deployment (build + import + publish to platform)
│
╰─ optional ─▶ Analytics (post-deployment data queries on live courses)
Segmentation, Generation, and Optimization can each be invoked standalone — see Usage Paths (Path B) for the sub-paths (Segment only / Generate only / Optimize only). Analytics is a separate post-deployment path — see Usage Paths (Path E).
Usage Paths
Path A: End-to-End
Run the full pipeline from raw material to a live deployed course.
- Resolve the course target (first, always) — resolve new-vs-edit via
verify + find-title; if editing an existing course, pull it before authoring. See ## Resolve the Course Target.
- Orchestration drives Segmentation and Generation end-to-end, then runs cross-lesson gating to produce Teaching Prompts + course_index + variable table.
- Optimization audits and improves Orchestration's output, plus produces the Course Prompt and SEO course description.
- Deployment writes the course directory, builds, imports, and publishes to the AI-Shifu platform.
Path B: Author Only
Run Segmentation through Optimization to produce optimized Teaching Prompts, a Course Prompt, and an SEO course description without deploying. Sub-paths:
- Segment only: Segmentation alone for structured segments and manual review.
- Generate only: Generation alone on pre-existing segments to produce Teaching Prompts.
- Optimize only: Optimization alone to audit and improve existing Teaching Prompts.
Path C: Deploy Only
Run Deployment alone to deploy pre-existing Teaching Prompts and a Course Prompt to the AI-Shifu platform. Resolve the course target first (## Resolve the Course Target) to resolve new-vs-existing — deploy as import --new, or pull + edit + push into an existing course.
Path D: Manage Existing
Use Deployment management commands (list, show, update, rename, reorder, delete, publish, archive) on courses already on the platform.
Path E: Course Analytics
Triggered by any question about a live course's data / metrics / statistics (routing rule: ## Data & Statistics Routing above). Reuses the Deployment authentication (token in .env). Always go through the CLI — never raw HTTP, never browser-scrape the admin dashboard. Workflow, references, and validation: ## Analytics below.
Segmentation
Turn messy course source material into a reliable intermediate structure for downstream lesson generation.
Workflow
See references/pedagogy.md#segmentation-methodology for the full methodology (cleanup, immutable-block marking, semantic segmentation, lesson-boundary proposal, source linking).
Outputs
Segment list per references/data-contracts.md#segment-schema (each segment carries id, type, core point, preservation flag, source span, and transfer signals), plus lesson boundary candidates with one core question each.
Validation
- Segment output covers all valid source spans in traceable order.
transfer_signals object populated and usable downstream (schema per references/data-contracts.md#segment-schema).- Preservation, one-core-question, and information-fidelity constraints pass — see
references/markdownflow.md#preservation and references/pedagogy.md#lesson-loop.
Orchestration
Role: end-to-end orchestrator for Path A. Orchestration calls Segmentation and Generation internally, then performs the cross-lesson work that those phases cannot — course index, global variable table, and mandatory gating.
Workflow
- Normalize source ordering and merge input material.
- Run Segmentation for cleanup and semantic segmentation.
- Finalize lesson cuts from Segmentation's boundary candidates (one core question each).
- Run Generation to generate per-lesson Teaching Prompts.
- Build course index and global variable table.
- Recompute only failed lessons through strict gating.
Mandatory Gates
All gates must pass before Orchestration declares lessons complete:
- Syntax / runtime gates (violation → script fails to run): preservation of code, images, and required source spans per
references/markdownflow.md#preservation; no unresolved placeholders and no learner-answer variable references without a variable-backed interaction and metadata contract; ?[] on standalone lines; deterministic blocks used only for truly fixed content per references/markdownflow.md#deterministic-blocks; every image URL must be on the res.ai-shifu.cn domain — fixed images wrapped in a single-line deterministic block, HTML-view images expressed as instruction-style directives with the (必须原样保留) URL phrase per references/markdownflow.md#images.
- Pedagogical gates (violation → teaching quality fails): one core question per lesson, minimum teaching loop, at least one deepening interaction, max five interactions per lesson, variable-collection pacing, viewpoint branching, and visual-text pairing — all per
references/pedagogy.md#lesson-loop, #interaction-design, #variable-strategy, and #visual-text-coordination. When Course Design Intake resolves to no interactions, bypass only the interaction-specific requirements that would force an interaction step or deepening interaction; keep the non-interaction requirements active.
Recompute lessons that fail any gate; do not partially-pass.
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
Under fallback mode (see ## Execution Modes), Orchestration:
- Delivers coarse lesson drafts first; continues with best-effort generation instead of stopping.
- Marks uncertain spans explicitly on
course_index entries.
- Emits a
rerun_plan listing lessons that need recompute and why.
Fallback field shapes per references/data-contracts.md#fallback-output-extensions.
Outputs
See references/data-contracts.md#output-contract for the Teaching Prompts, course index, and global variable table schemas; preservation rules per references/markdownflow.md#preservation.
Validation
- All artifacts present per
references/data-contracts.md#output-contract.
- Fallback outputs include explicit uncertainty markers and rerun hints.
- All Mandatory Gates above pass.
Generation
Generate a runnable Teaching Prompt for each lesson.
Teaching Pattern Baseline
Apply the patterns and constraints in references/pedagogy.md#teaching-patterns, #cognitive-techniques, #variable-strategy, #interaction-design, and #visual-text-coordination unless content requires a justified variation.
When generating interactions, explicitly choose the interaction type before writing the ?[] line per Hard Rule 3. If a lesson naturally asks "which of these apply?", default to multi-select unless the source or user says only one answer is allowed.
Single-Lesson Generation Strategy
Required anchors per lesson:
- Opening paragraph with a teaching-start function (Hard Rule 6) — not a copied chapter / lesson title or directory label.
- Opening objective plus slide-style 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.
Slide-Only Generation Override
When Course Design Intake resolves to pure slides / classroom interactive
slides, replace the default explanation-heavy lesson pattern with a projection
pattern. Pure slides are for classroom projection by a human instructor, not AI
narration:
- Treat each lesson as a small slide deck controlled by a human instructor.
- Generate slide-facing blocks only: slide title, 2-4 short bullets,
visual/layout instruction, interaction prompt, options, and concise feedback
states.
- Keep interactions runnable with the normal MarkdownFlow syntax, but keep the
surrounding content presentation-oriented.
- Do not include AI narration directives or learner-facing lecture prose such as
"explain to the learner", "walk through", "向学习者说明", "讲解", "用文字解释",
"讲清", or long paragraphs intended for the AI to speak.
- Do not require the normal visual-text explanation pair. The visual itself and
the short on-slide labels carry the projection content; any explanation
belongs to the human instructor, not the Teaching Prompt.
- The Course Prompt must describe the runtime role as producing classroom
interactive slides, not as conducting one-on-one tutoring. Do not include
course-level instructions that ask the AI to verbally explain the lesson to a
single learner.
Outputs
Per-lesson schema in references/data-contracts.md#lesson-schema.
Validation
- Each
teaching_prompt is valid runnable MarkdownFlow.
- The first non-empty line of each Teaching Prompt performs a teaching-start function (Hard Rule 6), not a duplicated
structure.json chapter / lesson title or a copied source heading such as # 第2章 ....
- Per-lesson schema populated per
references/data-contracts.md#lesson-schema.
- Pedagogical and syntax constraints pass per
references/pedagogy.md and references/markdownflow.md.
Working with Author-Provided Images
When the author supplies image assets — local files (any format incl. heic/heif) or remote URLs — three steps apply within Generation (and any later phase that touches the same lessons):
- Understand each image before placing it. You cannot choose the lesson, position, or alt text without knowing what the image shows. Two regimes:
- You can see the image (attached in this conversation and your model is multimodal): describe it to yourself in one sentence — what concept, relation, or example it conveys — then choose the lesson and position per
references/pedagogy.md#visual-text-coordination and references/course-prompt.md Rules 10/11.
- You cannot see the image (only a file path / URL, or your model is text-only): stop and ask the user. Do not guess from the filename. Offer two options: (a) the user provides a one-sentence description per image (you will pass it as
--alt), or (b) the user renames each file to a semantically meaningful name so you can infer the topic. Proceed only after one of these is in place.
- Upload via
shifu-cli.py upload-image (--file for local files — auto-preprocessed, or --url for remote; always pass --course-dir and --alt) and capture the printed https://res.ai-shifu.cn/<uuid32> URL. Full flags, preprocessing, and manifest behavior: references/cli/cli-reference.md#image-upload.
- Embed per
references/markdownflow.md#images. Default to 3.1 (deterministic-wrapped standard markdown); use 3.2 (instruction-style HTML) only when the lesson genuinely needs width control, alignment, a figure caption, or side-by-side layout — express every lock through wording (必须原样保留 / 必须原样输出 / 不要改写), never mix deterministic blocks into the instruction. The explanatory paragraph immediately after the image is mandatory (references/course-prompt.md Rule 11).
Optimization
Audit and improve existing Teaching Prompts (and the Course Prompt). This phase is not for writing from scratch.
When to Use
Use Optimization when existing Teaching Prompts or a Course Prompt need audit and targeted improvement — gap analysis against source, quality upgrades without full rewrites, and lowering runtime failure risk. Not for from-scratch authoring.
High-Standard Constraints
Apply Optimization audits against the full constraint set:
- Pedagogical constraints (variable strategy, interaction design, visual-text coordination, lesson loop, information density):
references/pedagogy.md.
- Syntax / runtime constraints (preservation, deterministic blocks, variable references):
references/markdownflow.md.
- Exhaustive audit checklist (failure modes are these constraints negated):
references/review-checklist.md.
Optimization Workflow
- Define scope (single lesson vs full course); if multiple script versions exist, declare the authoritative one before editing.
- Build a coverage matrix mapping source points to script coverage.
- Run the full audit per
references/review-checklist.md, classify findings using the issue taxonomy in references/pedagogy.md#optimization-methodology, and apply smallest safe edits first.
Course Prompt
Optimization also produces a course-level course_prompt artifact when input includes course material. Generate it by filling the template at references/course-prompt.md#fillable-template section-by-section, not by free-form composition. Each of the six required sections has a Must-Specify list in references/course-prompt.md#authoring-rules (Rules 1–11) — every listed bullet must appear in the generated course_prompt's corresponding section (in the resolved output language). Do not omit a Must-Specify bullet just because the source material does not explicitly demand it; these bullets are platform-level constraints.
Auto-fill placeholders from existing artifacts (course_profile, delivery_constraints, resolved target language per references/data-contracts.md#language-resolution, Segmentation visual cues) instead of re-asking the author. Do not duplicate per-lesson interaction logic or variable collection there — those belong in Teaching Prompts.
Validation
- Conclusion and overall risk level presented first (report structure per
references/report-template.md).
- Full review against
references/review-checklist.md passes, or remaining gaps are explicitly listed as non-blocking suggestions.
- A
course_prompt artifact is produced when input includes course material, with all six required canonical sections present.
- Generated
course_prompt covers every Must-Specify bullet in references/course-prompt.md Rules 1–11 (audit each canonical section against its rule list — especially the Slides section, which is the most commonly under-filled section).
Deployment
Ship optimized Teaching Prompts to the AI-Shifu platform as live courses. Three distinct actions are involved and should not be conflated:
- Deploy — upload local course files to the platform via
build + import. After this the course exists on the platform but is not yet visible to learners on a public URL.
- Publish — run
publish on the platform, which pushes the current draft to the public student-facing URL. Only after this step does <base>/c/<bid> (no preview=true) work.
- Sync — keep a local course directory and the platform draft version-consistent; the platform draft is the single source of truth. Think
git pull before git push. Mechanics: references/cli/cli-reference.md#version-sync-pull--status.
The standard end-to-end flow chains deploy + publish: build → import (deploy) → publish. When editing an existing course, use the sync loop instead: pull → edit locally → status → update-lesson / import (push) → publish.
Prerequisites
- Python 3 with
requests and python-dotenv packages installed.
- CLI script:
{skillDir}/scripts/shifu-cli.py
Authentication
Verify first — never re-login blindly. The verify / exit-code / 5-SMS-per-day rules live in Resolve the Course Target; the full login flow is in references/cli/cli-reference.md#agent-login-flow. Always use CLI commands. Never make raw HTTP/API calls directly.
Course Directory
Teaching Prompts must be organized in a course directory (one MarkdownFlow file per lesson under lessons/) before deployment. See references/cli/course-directory-spec.md for the full specification. When continuing from Optimization (Path A), write the optimized Teaching Prompts and Course Prompt into this structure automatically.
Content vs attributes — the skill changes content, not attributes, by default.
Content = lesson MarkdownFlow + course name/description/prompt; attributes = each
lesson's learning permission (access = 无需登录/试看/付费) and hidden, plus
course-level model/price/TTS/Ask/keywords/…. The skill pushes only content, and
the platform backend uses PATCH semantics (any field a write omits is left
unchanged), so iterating content never resets attributes. pull writes the
current attributes into structure.json and course-config.json as a
read-only reference. Change attributes only when the user explicitly asks —
set-access for a lesson's permission, set-tts for course Listen Mode (flags:
references/cli/cli-reference.md#update-commands); other course-level settings
are changed in the platform editor.
Editing an existing course → use granular non-destructive commands
(pull → update-lesson / add-lesson / delete-lesson / reorder / set-access / set-tts).
The destructive whole-course import recreates every outline (a recreated lesson
gets the platform-default permission), so reserve import --new for brand-new
courses — do not use it to iterate an existing one.
CLI Commands
All commands documented in references/cli/cli-reference.md (deployment: build / import / publish / show; version sync: pull / status; management for Path D: list / update-meta / update-lesson / rename-lesson / set-access / set-tts / reorder / delete-lesson / archive). Import JSON schema: references/cli/cli-reference.md#import-json-schema.
Deployment Workflow
From pipeline (Path A continuation):
- Write Optimization outputs into the course directory:
lessons/lesson-*.md, README.md, course-description.md (the generated SEO description; no author-side process notes), course-prompt.md (the Optimization course_prompt artifact, structured per references/course-prompt.md#fillable-template), and required structure.json.
- Run
build --course-dir <dir> to generate shifu-import.json.
- Deploy: Run
import --new --json-file <dir>/shifu-import.json to upload the course onto the platform.
- Publish: Run
publish <shifu_bid> to push the course to its public student-facing URL.
- Verify via platform URL.
Standalone deployment (Path C):
- Ensure the course directory is ready: Teaching Prompt files under
lessons/, a course-description.md SEO summary, a course-prompt.md (author per references/course-prompt.md#fillable-template first if missing), and structure.json (create it if missing). Directories without course-description.md still build, but the platform description will be empty unless --description is provided.
- Run
build → import (deploy) → publish as above.
Version Sync Workflow
The front guard that fixes the target (new-vs-edit, login + find-title,
pulling the existing course) is Resolve the Course Target — run it first. This section covers
what happens once the target is an existing course you have pulled: the
pull → edit → push loop that converges like git pull before git push.
pull <shifu_bid> --course-dir <dir> — download the cloud draft into the local dir and record revisions.- Edit locally — change lesson files / course description / course prompt in place.
status --course-dir <dir> — see what diverged (behind / locally modified / new / deleted on server).- Push with
--course-dir so the recorded baseline is used: update-lesson <bid> <ob> --teaching-prompt-file f.md --course-dir <dir> for a single lesson, or import <bid> --course-dir <dir> for the whole course.
publish <bid> when ready for learners.
Convergence loop on conflict. A push checks whether the cloud advanced since
your last sync:
- No newer version → push succeeds (exit 0) → done. Proceed to
publish.
- Newer version → push reports a conflict (exit 2). Exit 2 means "retry", not
"give up". The CLI has already backed up your un-pushed change,
auto-pulled the latest cloud copy over local, and printed who changed it and
when. Then loop: re-read the freshly pulled files (the new baseline) →
re-apply your intended change on top of it (you, the agent, do the merge — the
CLI never auto-merges content) → run the same push again → repeat until the
push succeeds (exit 0). Never force the old content back — the cloud is
authoritative.
Never hand-edit .shifu-sync.json, and always push with --course-dir —
without it a concurrent edit cannot be detected. Backup file locations and full
mechanics: references/cli/cli-reference.md#version-sync-pull--status.
Verification
After any deployment or management operation, verify the result:
- Show the user the verification URLs the script printed — admin console, course preview, and (when the script also printed it) the published public URL. Copy URLs verbatim from the script output and render each as three lines: a Markdown link, a bare URL on the next line for copy-friendliness, and the script's following Chinese
# ... hint copied verbatim without the leading # (per references/report-template.md — Deployment → Verification URLs, plus the top-level Formatting Rules exception). Never reconstruct URLs from a template by hand. Lesson-level URLs are intentionally omitted to keep the report scannable; if the user later asks for a specific lesson link, use show <shifu_bid> to find the outline_bid and build it on demand.
- Use
show <shifu_bid> to get the lesson outline_bid, then check each lesson's Teaching Prompt, variable collection, and interaction logic.
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.
Analytics
Post-deployment data queries on live courses. Trigger this section whenever a course author or admin asks about learner count, completion rate, stuck lessons, orders, revenue, ratings, follow-up Q&A volume, credit consumption, audience profile distribution, or individual learner tracking. For a one-glance course overview use Recipe 0d in references/analytics/recipes.md.
CLI-Only Rule
All analytics traffic goes through scripts/shifu-cli.py. Never write raw HTTP, never read tokens directly, never compose Authorization / Token headers by hand. Two analytics commands cover the surface:
shifu-cli.py analytics-query <bid> --dsl '<json-body>' — DSL queries against the 10 whitelisted tables listed in references/analytics/tables.md. The agent's job is to translate a user question into a DSL JSON body and pass it to the CLI.shifu-cli.py credit-detail <bid> [--start … --end … --scene 1203 --usage-type 1101 …] — all credit / spend questions. Do not issue a DSL query against bill_daily_usage_metrics for credit data (that table is empty in production until the daily aggregation cron is enabled). --scene 1203 restricts to learner-driven spend (preview is 1202, debug is 1201).
Workflow
- Resolve credentials — run
shifu-cli.py verify, per the verify-first rules in Resolve the Course Target.
- Resolve the course — run
shifu-cli.py list (or shifu-cli.py find-title <keyword>) to map shifu_bid ↔ course name. If the user mentioned a course by title, always resolve the current shifu_bid → title via Course Metadata recipes 0a / 0b in references/analytics/recipes.md before issuing downstream queries — list is a draft snapshot and can show stale or historical titles. Never report a historical title as the course's current name.
- Resolve the outline (only for lesson-level dimensions) — run
shifu-cli.py show <shifu_bid> to map outline_item_bid → name / position. Skipping this makes outline-dimension numbers unreadable.
- Run DSL queries —
shifu-cli.py analytics-query <shifu_bid> --dsl '<json-body>' (or --dsl-file query.json for long bodies).
- Translate before presenting — pass every result through the Translation Gate in
references/analytics/privacy-and-presentation.md. Never paste raw codes (601, 502, 1101), raw *_bid strings, or raw user_bid values in user-facing output.
References
references/analytics/overview.md — entry point, full workflow, question→table quick-lookup, error codesreferences/analytics/dsl.md — DSL grammar (operators, aggregates, constraints, per-learner guard rail, auto-applied filters, creator-scoped metadata tables)references/analytics/tables.md — the 10 tables, fields, all code/enum translation tables, ID translation rules, data traps, "course title is not history" rulereferences/analytics/recipes.md — Course Metadata 0a–0c, Course Overview 0d, + 23 numbered scenario recipes (including four-key follow-up pairing and follow-ups per lesson)references/analytics/privacy-and-presentation.md — user_users restricted access, generated_content whitelist, var_variable_values.value aggregate-only rule, Translation Gate, refusal rules
Validation
- Token resolved through the course-target resolution / Deployment authentication path, not a hand-rolled lookup.
- When the user mentioned a course by title, the current
shifu_bid → title was confirmed via Course Metadata Recipe 0a / 0b before the downstream query ran. Historical titles were never substituted for current ones.
shifu_bid and outline mappings established before any course-level query.- DSL body matches grammar in
dsl.md; filters reflect the user's intent (e.g. status = 502 for "paid", not >= 502).
- Credit consumption queries used
shifu-cli.py credit-detail per the CLI-Only Rule above — never a DSL query against bill_daily_usage_metrics.
- Follow-up counts anchored on
type = 321 (not role = 2), relying on the API's auto-injected status = 1 rather than an explicit clause.
- Translation Gate applied before the answer is shown.
- Privacy refusals honoured for inaccessible fields (phone, email, real name, ID number, avatar, birthday).
- When CLI output contains Chinese characters that appear garbled in the agent's Bash tool, write output to a UTF-8 file and read with the file-reading tool instead (see
references/cli/cli-reference.md#cli-output--encoding).
- Table name verified against the 10 whitelisted tables in
tables.md. Never guess a table name — invalid names trigger 11003.
Report Template
Use references/report-template.md to produce the user-facing report at the end of each phase. Per-phase anchors:
references/report-template.md#segmentation-reportreferences/report-template.md#orchestration-reportreferences/report-template.md#generation-reportreferences/report-template.md#optimization-reportreferences/report-template.md#deployment-report
Top-level formatting rules (Markdown links required for URLs, etc.) in references/report-template.md#formatting-rules.
Examples
examples/pipeline-full.mdexamples/segmentation-only.mdexamples/generation-only.mdexamples/optimization-only.mdexamples/fallback-mode.mdexamples/deploy-only.md
