course-generator

Course Content Organization

Task Objective

Organize existing texts into a course that readers can understand and use without accessing the original transcripts. The main text should fully preserve important viewpoints, cases, operational processes, failure corrections, and judgment methods from the sources, while removing live colloquial speech, conference information, and transcription noise.

This skill generates courses by default; it does not automatically archive, move original files, or transform them into other content products. When the user explicitly requests post-generation archiving or extraction of a training plan, then read post-generation-actions.md。

Input and Delivery

Confirm before starting:

• One source file or one source directory; prioritize processing .md、.txt。
• Course output directory; if unspecified, create a new course directory next to the source, and state the location before writing.
• Whether there are errata, editorial notes, or a specified current authoritative wording file.
• Whether a user dictionary is needed to correct proper names or fixed terminology; if needed, copy from config/user_dictionary.example.yaml to config/user_dictionary.yaml, and register only replacements that can be confirmed.
• Whether the target directory already has content; do not silently overwrite.

Default delivery includes:

• 00 <课程名称> - 总览.md
• Course chapters numbered in reading order
• source-index.json
• course-manifest.json

Original materials remain read-only. Temporary plans, batch files, auxiliary scripts, and caches are placed outside the course directory.

Core Requirements

1. Faithful to sources: Numbers, actions, results, recommendations, and proper names must be traceable back to the source; capabilities, processes, cases, and conclusions not present in the original text must not be filled in with common sense.
2. Preserve the essence: Every valid source block must enter the material ledger or be skipped with a controlled reason. Cases, operations, pitfalls, trade-offs, and judgment techniques must not be compressed into a one-sentence summary.
3. Follow the current authoritative wording: When the source has explicit revisions, the controlling document prevails; old wording only enters the audit record and must not reappear in the reader-facing main text.
4. Evidence follows chapters: Every level-two heading must have bound materials, and evidence in the main text of a material can only come from its own target subsection, not borrowed across sections.
5. Written style without expansion: Remove the verbatim transcript framework and colloquial filler, but preserve the original text's uncertainty, examples, and hypothetical tone; a single sample must not be expanded into a universal rule or industry practice.
6. Separate production from acceptance: The generator completes the main text, scripts check objective constraints, and finally an independent reviewer checks material conservation, factual fidelity, and reading quality.

In conflicts, protect in order: factual fidelity and current authoritative wording, completeness of core materials, chapter evidence boundaries, reader readability, and audit convenience.

Workflow

After the generation task starts, first read generation-workflow.mdcompletely, then execute in the following order; do not skip ledger precheck and write the main text directly.

1. Run index_sources.py to establish a deterministic source index.
2. Use ledger_tool.py init to initialize the manifest, confirm the authority declaration, and freeze the chapter and section plan.
3. Build the material ledger in batches according to the source blocks returned by status , and run the ledger stage for automatic closure and precheck.
4. Select a small number of representative images with teaching value, and use tools to generate chapter titles and revision sentence scaffolds.
5. Read overview_prompt.md and chapter_prompt.md, write the overview first, then generate chapter by chapter; only after each chapter passes check-chapter does it proceed to the next chapter.
6. Run the final stage to automatically close out and verify.sh, then complete the manual semantic review.

For outline and material judgment rules, see outline_prompt.md. For machine fields and JSON examples, see course-manifest.md. By default, at most 8 chapters; only read advanced-overrides.md。

Completion Criteria

Delivery is allowed only when the following conditions are all met:

• The overview, all chapters declared in the manifest, and the two mandatory JSON files all exist.
• The material ledger covers all valid source blocks, skipped items have controlled reasons, and high-value content has no unjustified net loss.
• Each chapter's check-chapter passes, and the final verify.sh exit code is 0。
• An independent reviewer reads quality-evaluation.md, completes semantic acceptance based on the evidence; manual spot checks confirm that numbers, action chains, recommendations, results, and proper names are traceable, revision wording has no conflicts, and there is no obvious duplication between chapters.
• The reader-facing body does not contain SRC/BLK/MAT/IMG, gate explanations, generation logs, temporary files, or internal terminology not discussed in the source.

Scripts passing only proves that the objective contract holds; it does not mean semantic quality has passed. At delivery, report script results, the scope of manual review, and unverified parts separately.

When quotas, network, or platform anomalies occur, preserve the scene and report them; do not rerun from the beginning, and do not record half-finished products or the executor's self-report as success.

Permissions and Privacy

• Read only the sources specified by the user, and write only to the stated course directory.
• Scripts do not access the network, do not install dependencies, and do not modify original materials;init/plan/merge/select-images atomically updates the index or manifest,scaffold only creates missing heading scaffolds,finalize_manifest.py --write only updates the manifest.
• Unredacted transcripts and course materials are handled on a minimal necessary basis and are not written into public examples, change records, or configuration templates.

Dependencies

System Dependencies

Dependency	Purpose	Installation Method
python3 >= 3.10	Run source index, ledger, and acceptance scripts	macOS: brew install pythonLinux: sudo apt-get install python3

Python Packages

No third-party Python packages are required; all scripts use only the standard library.

Resource Index

• generation-workflow.md: Complete generation steps, command order, and failure handling; read each time a course is generated.
• outline_prompt.md: Material classification, chapter planning, and image judgment; read when establishing the plan and ledger.
• overview_prompt.md: Overview writing requirements; read when generating the overview.
• chapter_prompt.md: Chapter writing and single-chapter self-check; read when generating chapter by chapter.
• course-manifest.md: Manifest fields and JSON examples; query as needed when preparing the plan, batches, or image selection files.
• quality-evaluation.md: Semantic hard-failure, quality scoring, and version promotion standards for the finished course; read during independent acceptance or regression comparison, and not provided to the generator as a writing outline.
• post-generation-actions.md: Archiving and training plan extraction; read only when the user explicitly requests it.
• verify.sh: Final deterministic acceptance entry point.