knowledge-map

knowledge-map

Guide-and-script skill for building course knowledge maps. Use it to turn a course topic, syllabus, textbook outline, notes, or teaching materials into a structured framework, key concept explanations, concept dependencies, and optional Markdown / Markmap / Mermaid / OPML / HTML outputs.

This skill is not a tutor, homework helper, practice-question generator, or long-term study planner. It organizes what a course contains and how concepts relate; it does not teach a live lesson, solve exercises, generate full quizzes, or schedule a study calendar.

When to use

Use this skill when the user asks for:

• A course knowledge framework, knowledge map, concept map, syllabus map, or mind map.
• A structured outline from a textbook table of contents, course notes, lecture slides, Markdown, DOCX, or pasted text.
• Key concepts, prerequisite relationships, course learning order, or "what should I learn first?"
• A compact framework plus deeper explanations of selected nodes.
• Exportable course maps in Markdown, Markmap, Mermaid, OPML, or an HTML report.

Do not use this skill for:

• One-off concept tutoring or Socratic explanation.
• Homework solving, answer checking, or quiz sessions.
• Creating retrieval-practice question sets.
• Full study schedules, reminders, check-ins, or weekly plans.
• Multi-course comparison in one pass. Ask the user to split by course.
• Video/audio processing. Ask the user to provide text, transcript, outline, or notes first.

How to call

1. Identify the input mode:

• topic_only: the user provides only a course topic.
• material_first: the user provides syllabus/notes/materials but no strong topic.
• hybrid: the user provides both topic and materials.

1. If the request is topic_only for a broad common course, warn that the map will be AI-inferred and ask whether the user wants to continue, provide materials, or cancel.

1. Ask whether the user wants a compact map, key-node explanations, or deeper node explanations when the requested depth is unclear.

Default to compact map plus key-node explanations when materials are available.

1. For structured file/material input, create an input.json matching references/input-schema.md.

Use scripts/validate_input.py to validate mode, depth, preferences, and warnings.

1. When materials are Markdown, TXT, pasted text, or DOCX, use scripts/parse_outline.py to extract the heading stream before building the map.

If the parser rejects the material type or finds no headings, ask for cleaner text or continue in topic-only mode only after user confirmation.

1. Generate the knowledge tree with references/framework-rubric.md and references/prompt-templates.md.

Keep total nodes at or below 100 and levels at or below 5. Use one root node and stable node ids such as n0, n1, n1.1, and n1.1.1.

1. For guided/deep outputs, choose 5-10 high-value nodes unless the user requested a specific focus.

Write useful explanations, examples, core points, and common confusions. Do not add explanations when the user asked for a map only.

1. For concept dependencies, use references/concept-dependency-taxonomy.md.

Output only concrete, useful relations. Avoid vague links such as "A and B are related." Keep relation count within the configured budget.

1. Assemble and validate structured output with scripts/assemble_result.py.

Use references/output-schema.md as the contract.

1. When user materials are available, run scripts/verify_provenance.py.

If many user-material nodes fail provenance matching, pause and ask whether to provide better materials, accept AI-inferred labels, or narrow the material range.

1. Render requested formats with scripts/render_outputs.py.

Default to Markdown plus Markmap when the user does not specify a format. Offer HTML only when useful for browsing or sharing.

Return format

For a clarification or safety checkpoint:

**Knowledge Map Scope**
- Course/topic:
- Input mode:
- Depth:
- Output formats:
- Risk/limit:

**Please choose**
1. Continue with AI-inferred map
2. Provide syllabus/notes first
3. Narrow the course scope

For a normal response:

**Knowledge Map**
- Course:
- Source mode:
- Depth:
- Nodes:
- Outputs:

**Framework overview**
[course tree]

**Key nodes**
[guided explanations when requested]

**Concept dependencies**
[typed dependency table when requested]

**Learning route**
[what to learn first, what depends on what, and where to review]

**Files**
- [generated files, if rendered]

For script-backed workflows, include the generated output directory and the key files:

**Generated files**
- `result.json`
- `framework.md`
- `framework.markmap.html`
- `framework.mermaid.md`
- `framework.opml`
- `concept-dependencies.md`
- `provenance-audit.json`
- `report.html` when requested

External dependencies

• Python 3 standard library for included scripts.
• No fixed third-party Python packages are required by the included scripts.
• Markmap HTML uses CDN loading when rendered by scripts/render_outputs.py; if CDN is unavailable, provide Markdown or Mermaid as the stable fallback.
• The current environment must be able to read user-provided local files before file-backed parsing can run.

Limits and known issues

• Topic-only maps are AI-inferred and may omit or mis-order course content. Always label this clearly.
• The skill handles one course per run. Split multiple courses into separate maps.
• Keep generated maps at or below 100 nodes and 5 levels unless the user explicitly agrees to split the course.
• PDF/image/webpage/audio/video inputs require preprocessed text or a reliable extractor outside the core script set.
• Do not silently continue when OCR or parsed outline quality is poor.
• Do not promise that the map matches a specific curriculum unless the user supplies that syllabus or textbook outline.
• Do not expose internal audit terms such as n-gram match…