Learn

Learn — Obsidian Learning Note Generator

Generate Obsidian-compatible learning notes from a codebase. Produces genuine learning resources that explain how and why things are implemented, adapted to your knowledge level.

Arguments

• No arguments: analyze the current project and generate full learning notes
• quick-topic <topic>: generate a single topic note (see prompts/quick-topic.md)
• update [technology] [level]: incrementally correct existing notes (see prompts/update.md)

Invocation

/learn                              # Full project analysis
/learn:quick-topic <topic>          # Single topic note
/learn:update                       # Interactive correction of existing notes
/learn:update <technology> <level>  # Re-adapt a specific technology to a new level

Sub-Prompts

• quick-topic — Read and follow ./prompts/quick-topic.md
• update — Read and follow ./prompts/update.md

Workflow

Execute these 6 phases sequentially. Do not skip phases. If a tool is unavailable, follow the graceful fallback described in that phase.

Phase 1 — Gather Context

Goal: Build a comprehensive understanding of the project before asking the user anything.

1. Read project metadata — look for and read whichever of these exist:

   • CLAUDE.md, README.md
   • package.json, Cargo.toml, pyproject.toml, go.mod, *.csproj, build.gradle, pom.xml, composer.json, Gemfile, mix.exs, deno.json

2. Map project structure — use Glob to identify:

   • Entry points (src/index.*, src/main.*, app.*, cmd/, lib/)
   • Core modules and their organization
   • Test directories (test/, tests/, __tests__/, *_test.*, *.spec.*)
   • Configuration files
   • Key directories and their purposes

3. Classify project size — based on the file count from step 2, determine a size tier:

   • Small (≤50 source files): read 8-12 files, target 2-4 topics, simple architecture
   • Medium (51-500 source files): read 12-20 files, target 4-6 topics, layered architecture
   • Large (500+ source files): read 20-30 files, target 6-10 topics, multi-module architecture

   Store these parameters in working memory — they govern decisions in Phases 3-5. "Source files" means code files (not configs, tests, assets, or generated files).

4. Identify patterns — use Grep to find:

   • Framework-specific patterns (decorators, middleware registration, route definitions, hooks)
   • Architectural patterns (repository pattern, service layer, controller layer, etc.)
   • State management approaches
   • Database/ORM usage

5. Read key source files — read the count from your size tier that represent:

   • Main entry points
   • Core business logic
   • Configuration and setup
   • Data models / types
   • Key utilities or shared abstractions

6. Build internal inventory (keep in working memory, do not output):

   • Project name and description
   • Tech stack with versions
   • Architectural layers / modules
   • Key abstractions and their relationships
   • Data flow (request → response, or input → output)
   • Candidate topics matching your size tier's target range

Phase 2 — Ask User

Use AskUserQuestion to gather preferences. Batch into as few questions as possible (ideally 1-2 calls).

Question 1 — Knowledge Level:

• First, read ./config.md and check the Remembered Levels section for the current project name
• If remembered levels exist for this project, present them as pre-filled defaults and ask the user to confirm or adjust
• If no remembered levels exist, present the full discovered tech stack and ask the user to specify their level (beginner / intermediate / advanced) for every technology — do NOT assume or default any level
• Present this as a single question that lists all discovered technologies and asks the user to reply with their level for each one
• If the user's response omits a technology, explicitly follow up — never silently assume a level
• After levels are confirmed, update ./config.md Remembered Levels with the project's levels for future runs

Question 2 — Learning Focus & Options:

• Ask learning focus: entire project (recommended) / specific module / specific feature
• Read ./config.md for the default vault path, present it, let user override
• Ask if user wants an interactive HTML view via visual-explainer alongside markdown notes

Phase 3 — Fetch Library Docs (context7)

Availability check: Attempt a resolve-library-id call for the primary framework/library.

If context7 is unavailable (tool not found or connection error):

1. Inform the user: "context7 plugin is not available. It provides up-to-date library documentation that makes the learning notes significantly richer — explanations reference official docs, idiomatic patterns, and common pitfalls specific to each library version."
2. Ask via AskUserQuestion: "Would you like to install context7 and retry, or continue without it?"
3. If skipping, set a flag to add a note in generated content that library documentation sections are based on general knowledge rather than latest docs.
4. Proceed to Phase 4.

If context7 is available, query dependencies scaled to project complexity:

• Small projects (≤5 key dependencies): query 2-3 (core framework + most unusual)
• Medium projects (6-15 dependencies): query 4-6 (core + state management + data layer + unusual)
• Large projects (16+ dependencies): query 6-8 (core + each architectural layer's primary lib + unusual)

Prioritize: core framework > data/ORM > state management > unusual/interesting deps. Skip well-known utility libraries unless architecturally significant.

For each selected dependency:

1. resolve-library-id to get the context7 library ID
2. query-docs with project-specific queries — e.g., "how does Express handle middleware chaining and error handling" not just "what is Express"
3. Store key findings (idiomatic patterns, common pitfalls, version-specific behavior) to weave into topic notes

Constraints:

• Max 3 context7 calls per library (1 resolve + up to 2 query calls)
• Total context7 budget: small=9, medium=18, large=24 calls across all libraries

Phase 4 — Generate Diagrams (excalidraw)

Availability check: Attempt to call read_diagram_guide.

If excalidraw is unavailable:

1. Note that diagrams will be skipped
2. In generated notes, replace diagram embeds with a text description of the architecture
3. Proceed to Phase 5

If excalidraw is available:

1. Call read_diagram_guide for best practices

2. Architecture diagram:

   • Use batch_create_elements to create a system architecture diagram
   • Show major components/layers, their relationships, and data flow
   • Use colors from the diagram guide, clear labels
   • Export with fallback chain (use the first method that succeeds):
     1. Try export_to_image (format: png) → save to <output-dir>/Images/architecture-overview.png → embed as ![[architecture-overview.png]]
     2. If PNG export fails (requires browser canvas), use export_scene → save to <output-dir>/Images/architecture-overview.excalidraw → embed as ![[architecture-overview.excalidraw]]
        • Post-process for Obsidian compatibility: The MCP excalidraw server exports a minimal JSON format that the Obsidian Excalidraw plugin cannot fully render. After every export_scene call, read the exported .excalidraw file and enrich it using references/excalidraw-format.md as a specification:
          1. Read the exported file
          2. For every element, add any missing required fields: version, versionNonce, index, isDeleted, fillStyle, strokeStyle, angle, seed, groupIds, frameId, roundness, boundElements, updated, link, locked, hasTextLink
          3. For text elements: add containerId (null for standalone), originalText (same as text), autoResize, lineHeight (1.25), estimated width/height, rawText, textAlign, verticalAlign, backgroundColor ("transparent")
          4. For arrow elements: convert start/end shorthand to startBinding/endBinding with { "mode": "orbit", "elementId": "<id>", "fixedPoint": null }. Add startArrowhead (null) if missing
          5. Update source to "https://github.com/zsviczian/obsidian-excalidraw-plugin/releases/tag/2.20.6"
          6. Write the enriched file back to the same path
        • Inform the user: "Diagrams exported as .excalidraw files. Install the Excalidraw plugin in Obsidian (Community Plugins → Excalidraw) to render them inline."
     3. Try export_to_excalidraw_url → add the shareable link as a footnote (e.g., [^arch]: View diagram: <url>) for browser viewing
     4. If all above fail, generate a Mermaid code block as a text fallback inside the note (Obsidian renders Mermaid natively)
   • Remember which format succeeded — use the same format for all subsequent diagrams in this run. If .excalidraw was the format, apply the same post-processing enrichment to every exported file.

3. Data flow diagram (generate when ANY of these apply):

   • The project has 3+ distinct data layers (e.g., API → service → repository → database)
   • The project uses message queues, event buses, or async pipelines
   • Data flows through transformations (serialization, mapping, validation) between layers
   • Multiple data stores are involved (2+ databases, caches, external APIs)

   Skip for simple CRUD projects with a single request → model → database path.

   • Call clear_canvas
   • Create a data flow diagram showing request/response or input/output paths
   • Export using the same format/fallback chain as the architecture diagram

4. Module dependency diagram (only for Large projects):

   • Show how major modules/packages depend on each other
   • Highlight circular dependencies if any exist
   • Use the same export fallback chain

5. Interactive HTML view (only if user opted in during Phase 2):

   • Invoke the visual-explainer skill: "Generate an interactive architecture overview for this project showing: [components, relationships, data flow from Phase 1 findings]"

Phase 5 — Generate Notes

Before generating any notes, read these reference files:

• ./templates/index-note.md
• ./templates/topic-note.md
• ./references/knowledge-levels.md
• ./references/obsidian-conventions.md

Read ./config.md to get the date format.

Determine topics: From the candidates identified in Phase 1, select topics matching your size tier:

• Small projects: 2-4 topics — cover core functionality and the most interesting pattern
• Medium projects: 4-6 topics — cover core + each architectural layer + standout patterns
• Large projects: 6-10 topics — cover architecture, each major module, cross-cutting concerns, and deployment/infrastructure if relevant

Topics should also:

• Represent distinct architectural concerns
• Match the user's learning focus (if they chose a specific module/feature, narrow topics accordingly)

Generate the index note (<Project Name> - Overview.md):

• Follow templates/index-note.md exactly
• Include: header block, summary, tech stack table (with user's level per tech), architecture diagram embed, topic note wikilinks ordered as a learning path, key entry points
• The learning path order should be adapted to the user's knowledge levels

Generate topic notes (one per topic):

• Follow templates/topic-note.md for structure
• Critically: adapt each note's sections, depth, and tone based on the user's knowledge level for the relevant technology (see references/knowledge-levels.md)
• Execution Flow trace: For each topic's How section, begin with an ### Execution Flow subsection — a numbered list showing the call chain across files with file:line → function() format. This gives readers a map before diving into code details. Indent sub-calls to show nesting. Adapt granularity to knowledge level (beginner: every step with descriptions; intermediate: important hops; advanced: compact critical path)
• Execution Flow diagram: For each topic's Execution Flow, also generate an Excalidraw diagram visualizing the call chain. Use the same export fallback chain from Phase 4 (PNG → .excalidraw → URL → Mermaid) and the same format that succeeded for the architecture diagram. Embed it directly below the ### Execution Flow heading, before the numbered text trace. Follow the same style rules established in Phase 4. Adapt diagram detail to knowledge level (see references/knowledge-levels.md → Execution Flow Diagrams).
• Weave in context7 findings — don't create separate documentation sections; integrate official doc insights into the How, Gotchas, or Deep Dive sections naturally
• Hyperlink jargon and key terms — on first mention of important concepts, technologies, functions, protocols, and design patterns, link the keyword itself to its official documentation or a stable reference page (see references/obsidian-conventions.md → External Documentation Links and references/knowledge-levels.md → External Links per level). Link density should match the user's knowledge level: generous for beginners, selective for intermediate, sparse for advanced.
• Use actual code from the project — not generic examples
• Include file path references for all code snippets
• Ensure all wikilinks between notes are consistent (note names must match exactly)

Cross-topic consistency check — after generating all notes:

1. Build a list of all technologies from the user's knowledge levels (from Phase 2)
2. For each technology, Grep across all generated notes for mentions (case-insensitive, include common aliases)
3. For each mention found in a note whose primary topic is a different technology:
   • Verify the explanation depth matches the user's level for the mentioned technology, not the note's primary topic
   • If mismatched, adjust the explanation inline (add/remove detail as needed)
4. This check is most important when the user has mixed levels (e.g., beginner C#, advanced Akka.NET)

Follow Obsidian conventions from references/obsidian-conventions.md:

• HTML span headers with #5C8984
• Bullet-point style content
• Wikilinks [[]] for internal links
• Image embeds ![[]]
• Footnotes at bottom
• No YAML frontmatter

Phase 6 — Write & Report

1. Create directory structure:

   <vault-path>/Projects/<project-name>/
   <vault-path>/Projects/<project-name>/Images/
   

2. Write all files using the Write tool:

   • Index note
   • All topic notes
   • Images are already written in Phase 4

3. Report to user:

   • List all generated files with full paths
   • Provide a suggested reading order (matching the learning path in the index note)
   • Note any skipped features (context7 unavailable, diagrams skipped, etc.)
   • Mention that notes can be customized by editing ~/.claude/skills/learn/config.md

Important Guidelines

• Real code, not examples: Every code snippet must come from the actual project. Include file paths.
• Learning, not documentation: Explain why things are done, not just what. Include design rationale.
• Consistent wikilinks: Every [[link]] in any note must correspond to an actual note filename (minus .md).
• No YAML frontmatter: Use the HTML span header block instead.
• Respect knowledge levels: A beginner note should feel like a tutorial. An advanced note should feel like a technical deep-dive. Never mix levels within a single note.
• context7 integration: Weave library docs into explanations naturally. Don't dump raw documentation.
• Graceful degradation: If context7 or excalidraw are unavailable, still produce high-quality notes — just note what's missing.