dmccreary/claude-skills/learning-graph-generator

Learning Graph Generator

Version: 1.07

Changelog

• v1.07 — Version is now tracked in the SKILL.md frontmatter as metadata.ibook.version. It lives under metadata: rather than a bare version: key because strict packaging validation rejects any frontmatter key outside the six spec fields. No behavioural change.

• v1.06 — BREAKING: csv-to-json.py (bumped to v1.04) now computes a Concept Impact Score (CIS) for every node and writes it into learning-graph.json as node.cis. CIS is a PageRank-style recursive importance measure: CIS(x) = 1 + sum(CIS(d) for d in direct dependents of x), capturing how much of the book's total understanding transitively rests on a concept — unlike plain in-degree, which undercounts concepts that are foundational only indirectly (e.g. "Constant" or "Coefficient" in a typical algebra course, which have few direct dependents but many transitive ones). Because the graph is a DAG, CIS is computed exactly in one topological-order pass — no damping factor or iteration. Downstream skills (book-installer's graph viewer, book-chapter-generator, chapter-content-generator) now read this field directly instead of recomputing their own importance measure. See the schema's nodes[].cis field and the "Predicting Concept Content Size" paper (Definition 3, Proposition 1) for the full derivation. This is a breaking change to the learning-graph.json output format (an additive field, so old readers won't break, but downstream skills now expect it to be present) — regenerate learning-graph.json for any existing book before running the updated book-chapter-generator or chapter-content-generator.
• v0.06 — (prior history not tracked in this changelog format)

You are tasked with generating a comprehensive high-quality learning graph from a course description. A learning graph is the foundational data structure for intelligent textbooks that can recommend learning paths. A learning graph is like a roadmap of Concepts to help students achieve their learning goals. A learning graph is an DAG Concept graph. Each arrow is a "Learning Dependency" relationship that suggest learning order. The markdown you generate must be compatible with the mkdocs version of markdown. Make sure you put a blank line before any lists.

Follow these steps carefully:

Markdown Generation Rules

1. Always place a blank line before any markdown list. This is required by the mkdocs markdown tools.

Mkdocs Navigation Rules

After you add a markdown file (any file with an extension .md) make sure to add that file to the navigation structure in the mkdocs.yml file. Here is an example of the nav section for the learning graph section:

  - Learning Graph:
    - Introduction: learning-graph/index.md
    - Course Description Assessment: learning-graph/course-description-assessment.md
    - Concept Enumeration: learning-graph/list-concepts.md
    - Graph Quality Analysis: learning-graph/graph-quality-analysis.md
    - Concept Taxonomy: learning-graph/concept-taxonomy.md
    - Taxonomy Distribution Report: learning-graph/taxonomy-distribution-report.md

Step 0: Setup

Tell the user that they are running the version graph generator and the version number above.

The default context is that the skill is run from claude code in the home directory of an intelligent textbook that has been checked out from GitHub. There should be a docs directory with a standard mkdocs.yml file in the home git directory. You will create a directory called /docs/learning-graph it it does not already exist. The path is relative to the git home directory. The assumption is that /docs is relative to the directory that claude was started in.

mkdir -p docs/learning-graph; cd docs/learning-graph

You will copy python programs from this skill package into the /docs/learning-graph directory. You will execute python from that directory.

If you do not see the docs directory and the mkdocs.yml file suggest that the user clone a sample textbook from the following location:

git clone https://github.com/dmccreary/intelligent-book-template cd intelligent-book-template

Step 1: Course Description Quality Assessment

Before you begin this step, verify that it has not already been done. To do this, check the yml metadata in the docs/course-description.md file.

Here is a sample of the yml metadata:

---
title: Course Description
description: A detailed course description 
quality_score: 95
---
# Course Description

If you see a quality_score above 85 you may tell the user you found a score above 85 and skip this entire step. Tell them this is a way to save tokens.

If the quality score is below 85, analyze the provided course description at course-description.md to ensure it has enough content to generate at a minimum of 300 high-quality concepts:

1. Verify the course has a title, prerequisites, intended audience, objectives, and outcomes ("After this course students will be able to"). If these fields are missing ask the user for this information.
2. Examine the depth and breadth of topics covered
3. Assess whether the material has sufficient granularity for at a minimum of 300 distinct concepts
4. Check for diverse topic areas and learning objectives
5. Provide detailed feedback to the user about:

• List the expected content that you found
• Estimated number of concepts you can derive
• Compare this concept number with similar courses
• Describe areas where the course description is strong
• Any gaps or areas that might be under-represented
• Suggest how the 2001 Bloom taxonomy (remember, understand, apply, analyze, evaluate, create) could improve the outcomes descriptions
• Objective overall quality assessment on a scale of (1-poor to 100-perfect)
• Suggest that the user does not proceed unless a quality score is 70 or above

Use the following rubric for creating a quality score:

2.2 Course Description Quality Scoring System

Evaluate the course description using this 100-point scoring system:

Scoring Guidelines:

• Award full points if element is complete and high-quality
• Award partial points if element is present but incomplete or vague
• Award 0 points if element is missing
• For Bloom's Taxonomy levels, require at least 3 specific, actionable outcomes for full points

Tell user what their score was and suggest they improve the course description until the score goes above 80.

Save this report to course-description-assessment.md

1. Ask the user if you should proceed with generating the learning graph

Step 2: Generate Concept Labels

Once the course-description has been approved, generate the concept labels from the course content:

Requirements:

• Each Concept label must be in Title Case
• Maximum length: 32 characters
• Labels should be clear, specific, and pedagogically sound
• Cover the full breadth of the course material
• Concept Labels are entity names, not questions
• Do not use questions in the Concept Label. Don't use "What is Git", just use "Git"

Number of Concepts:

For simple books, a list of 300 concepts is fine. For complex technical books, you may generate up to 600 concepts. Do not exceed 600 concepts unless you have good reason and the user approves this decision. Remember that generating concept dependencies gets complex the more concepts there are.

!!! note Because these concept labels are used within a network graph, they must not be too long. Otherwise the graph will be hard to read.

Output:

• Save the numbered list to concept-list.md
• Format: Simple numbered list (1-600) in a markdown file
• Make sure that each number is unique so it can be used as a ConceptID
• Inform the user the file has been created
• Tell the user they should view the list and add and remove concepts now
• Tell the user it is best review the concept list before the next steps

Now ask the user to take some time to manually review the entire list of concept labels. If there are concepts that are not appropriate they should be removed now. If there are additional concepts that need to be added, they should be added now. It will require a lot of extra tokens later to change the content later. This is an important review step to ensure the quality of the textbook. Pay special attention to the length of the concept labels and the quality of any abbreviations.

Step 3: Generate Dependency Graph

Create a CSV file mapping dependencies between concepts:

Format:

• Filename: learning-graph.csv
• Columns: ConceptID,ConceptLabel,Dependencies
• ConceptID: Integer (1-600)
• ConceptLabel: The exact label from Step 2
• Dependencies: Pipe-delimited list of ConceptIDs (e.g., "1|3|7")

Dependency Rules:

• Foundational/prerequisite concepts have NO dependencies (empty Dependencies field)
• All other concepts must have at least one dependency
• No concept can depend on itself
• The graph must be a Directed Acyclic Graph (DAG) - no cycles
• Create meaningful learning pathways, not just linear chains
• Consider prerequisite relationships carefully

Note: The JSON file will be created in later steps (Steps 7-8) after the taxonomy is added to the CSV file. The complete JSON will include metadata, groups, nodes, and edges sections conforming to the learning-graph-schema.json.

Step 4: Learning Graph Quality Validation

Perform comprehensive quality checks on the dependency graph by using the Python program analyze-graph.py in this skill. It will do the following checks:

1. Verify DAG structure: Ensure no cycles exist
2. Check for self-dependencies: No concept should depend on itself
3. Foundational concepts: Identify concepts with zero dependencies
4. Terminal nodes: Identify concepts that nothing depends on (leaf nodes). These are valid and expected — do not confuse with orphaned nodes (which have no connections at all)
5. Disconnected subgraphs: Check if all concepts are connected to the main graph
6. Linear chains: Flag if too many concepts only depend on the immediately prior concept
7. Indegree analysis: Calculate indegree (number of concepts that depend on each concept)

Shell command python analyze-graph.py learning-graph.csv quality-metrics.md

Verify the report has been written to quality-metrics.md