How skill.md controls the entire workflow: mode detection, phase sequences for course and understanding pipelines, error handling and retry logic.
The orchestrator is the central control mechanism in skill.md. It determines which mode is active, which phases run in which order, and which quality gatesCheckpoints between phases that ensure all prerequisites for the next phase are met. Example: "All batch results present?" before the assemble step. must be satisfied.
# skill.md — Orchestrator logic (simplified)
orchestrator:
mode_detection:
strategy: "keyword_match"
fallback: "ask_user"
keywords:
course: ["Kurs", "Tutorial", "HTML", "course", "learn"]
understand: ["understand", "graph", "analyze", "KG"]
combined: ["both", "combined", "everything", "alles"]
phase_contract:
each_phase_must:
- declare inputs (files, context)
- declare outputs (files, data)
- pass quality gate before next phase
- handle errors with retry or partial result
How does mode detection work? The orchestrator analyzes user input for keywords. "Create a course" activates course mode, "Understand this project" activates understanding mode. In ambiguous cases, the skill asks the user.
Phase contract: Each phase defines exactly which inputs it requires and which outputs it produces. Only when the quality gate is passed does the next phase start. This prevents cascading failures.
The routing decision happens once at the beginning. After that, the chosen pipeline runs sequentially. The orchestrator monitors progress, logs warnings, and can retry individual phases if needed.
The course pipeline transforms a codebase into interactive HTML courses. Each phase builds on the results of the previous one:
| Phase | Name | Input | Output | Gate |
|---|---|---|---|---|
| P0 | Bootstrap | Project path, user answers | File inventory, dir tree, README content | Inventory ≥ 1 file |
| P1 | Analyze | Inventory, files | Tech stack, patterns, dependencies | Stack detected |
| P2 | Curriculum | Analysis result, audiences | Topic list with HS per audience | Min. 3 topics HS≥6 |
| P3 | Foundation | Curriculum, design system | index_*.html (L0 files) | All L0 files valid |
| P4 | Build | Curriculum, L0 links | L1/, L2/, L3/ HTML files | All links resolvable |
| P5 | Polish | All generated files | Corrected files, cross-links | 0 broken links |
| P6 | Depth Map | Complete file list | Visual sitemap with links | All pages captured |
# Phase 2: Curriculum — HS scoring per topic
curriculum:
topics:
- name: "Skill Architecture"
hs_end_user: 4 # too technical → no end-user L1
hs_developer: 9 # ≥8 → L1 + deep-dive to L2
- name: "Create Course"
hs_end_user: 9 # ≥8 → L1 + deep-dive to L2
hs_developer: 5 # <6 → not in developer course
# Rules:
# HS < 6 → topic not included
# HS 6-7 → L1 page + L2 page, no deep-dive to L3
# HS ≥ 8 → L1 + L2 + deep-dive link to L3
Helpfulness Score (HS): Each topic is scored per audience. An HS of 9 means "extremely helpful", an HS of 3 means "barely relevant". The thresholds determine how deeply a topic is covered in the course.
Example: "Skill Architecture" is highly relevant for developers (HS=9) but too technical for end users (HS=4). Therefore, this topic only appears in the developer course with deep-dive, not in the end-user course.
The understanding pipeline generates a Knowledge GraphA JSON structure with nodes (files, functions, classes), edges (imports, calls, contains), layers (architecture tiers), and a guided tour (learning path). instead of HTML courses. It has one more phase because graph merging and architecture detection require additional steps:
| Phase | Name | Agents | Output |
|---|---|---|---|
| P0 | Pre-flight | — | Project path validated, .claude-learning/ created |
| P1 | Scan | project-scanner | File inventory, import map, dir tree |
| P2 | Analyze | file-analyzer (5x parallel) | Batch JSONs with nodes + edges |
| P3 | Assemble | assemble-reviewer | Merged graph (deduplicated nodes/edges) |
| P4 | Architecture | architecture-analyzer | Layer assignment (frontend, backend, DB...) |
| P5 | Tour | tour-builder | Guided tour with ordered learning path |
| P6 | Review | review-validator | Validated graph, error log |
| P7 | Save | — | knowledge-graph.json + dashboard.html |
The critical difference from the course pipeline: Phase 2 (Analyze) runs in parallel with up to 5 file-analyzer instances simultaneously. Each instance processes a batch of 20-30 files and produces a batch JSON. In Phase 3, all batch results are merged into a consistent graph.
Combined mode runs the complete understanding pipeline first (Phase A), then uses the generated Knowledge Graph as additional input for the course pipeline (Phase B). The result: courses enriched by graph data.
# Combined pipeline in skill.md
combined_pipeline:
phase_a: # Understanding pipeline (complete)
phases: [A0, A1, A2, A3, A4, A5, A6, A7]
output: .claude-learning/knowledge-graph.json
gate: "Graph has ≥10 nodes, ≥5 edges"
phase_b: # Course pipeline with KG enhancement
phases: [B0, B1, B2, B3, B4, B5, B6]
extra_input: knowledge-graph.json
enhancements:
- "HS scoring considers graph centrality"
- "Course diagrams use real edge data"
- "Tour order influences L1 arrangement"
Why combined? Without a Knowledge Graph, curriculum scoring relies on heuristic analysis. With graph data, the scoring algorithm can consider actual component centrality — central modules get higher scores.
Concrete improvements: Architecture diagrams in course pages show real import chains instead of estimated ones. The order of L1 topics follows the graph's tour logic. Edge weights influence which dependencies get explained.
Phases are prefixed with A and B to avoid confusion. Phase A3 is the assemble step of the understanding pipeline, Phase B2 is the curriculum of the course pipeline. The gate between A and B ensures the graph contains at least 10 nodes and 5 edges — otherwise the skill falls back to pure course mode.
Not every phase runs flawlessly. The orchestrator implements three-tier error handling that prioritizes robustness over perfection:
# Error handling in skill.md
error_handling:
retry:
max_attempts: 2
applies_to: [P2_analyze, P3_assemble]
strategy: "reduce_batch_size"
partial_results:
enabled: true
min_coverage: 0.6 # 60% of files must be analyzed
warning: "Warning: {n} files could not be analyzed"
phase_warnings:
collect: true
display: "end_of_pipeline"
categories:
- "missing_edges" # Referenced nodes missing
- "orphan_nodes" # Nodes without connections
- "broken_links" # HTML links pointing nowhere
- "low_hs_threshold" # Few topics above HS 6
Retry logic: When a file-analyzer batch fails (e.g., due to oversized files), the batch is halved and retried. Maximum 2 attempts per phase. After that, partial results take over.
Partial results: If at least 60% of files were analyzed successfully, the pipeline continues — with a warning. Only below 60% does the pipeline abort.
Phase warnings: Non-critical issues are collected and displayed at the end of the pipeline. Missing edges or orphan nodes don't prevent completion but are documented.
This architecture ensures that even with problematic codebases (missing imports, circular dependencies, binary files) a usable result is produced. The user sees a clear summary at the end: what was generated, what's missing, and why.
Dive deeper into skill.md structure