# Learn

> Learn — Obsidian Learning Note Generator

- Skill: `mosamaasif/learn` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add mosamaasif/learn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mosamaasif/learn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mosamaasif (https://skillmd.com/u/mosamaasif)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mosamaasif/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.