Sage learn
Knowledge entries in sage-memory, Docs in .sage/docs/From its SKILL.md
npx -y skills add xoai/sage --skill sage-learnAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
SKILL.md
8.7 KB, as published. Nobody here has run it
When to Use
Load this skill when the user runs /sage-learn or asks to learn something (the Sage learn workflow).
Arguments
Hermes does NOT interpolate an in-body argument token. The user's arguments/flags arrive as a SEPARATE instruction line appended to this skill invocation. Wherever the steps below refer to "the user's arguments", use the text of that appended instruction line.
Independent review (delegate_task)
When a step calls for an independent review, invoke delegate_task against the sage-reviewer skill. Hermes delegate_task has NO toolset-restriction parameter — read-only is prompt-enforced, and you MUST verify afterward that the reviewer made no edits (e.g. git status unchanged) before accepting its verdict.
RULES (apply to every step — non-negotiable):
- Announce: "Sage → learn workflow." before starting work
- Present findings to user BEFORE storing in memory
- ONTOLOGY: After storing prose knowledge, create ontology entities for structural elements (modules, services, APIs, dependencies). This builds a navigable knowledge graph. Read skills/sage-ontology/SKILL.md for encoding. Search ontology first to avoid duplicates.
- Checkpoint: [A] Looks correct / [R] Some findings are wrong
- Choices: present with [1] [2] [3] bracket notation
- Never use code blocks for interaction (checkpoints, options, status)
Learn Workflow
Deliberate knowledge capture. Use to onboard to a new codebase, deeply understand a module, or build persistent memory for a project area.
Step 0: Mode Dispatch
/learn builds memory (prose knowledge). /learn --ontology builds the
ontology (a typed entity/relationship graph) instead — it folds in the
former /map workflow. Parse the arguments the user provided alongside this skill invocation (delivered as a separate instruction line, NOT a literal token):
/learn(default) → Steps 1–N below (memory capture)./learn --ontology→ readcore/workflows/learn-modes/ontology.mdand follow it; it maps modules, services, and APIs and their dependencies via thesage-ontologyskill.
Step 1: Determine Scope
If a path is specified, that's the target — deep dive. If no path, broad scan of the whole project.
Sage: What would you like to learn?
[1] Broad scan — learn the project structure, stack, patterns, conventions [2] Deep dive — learn a specific module, service, or area [3] Something else — describe what you want to understand
Step 2: Search Existing Knowledge
Search sage-memory for any prior knowledge about this project or area. Don't re-learn what's already known — build on it.
If prior knowledge exists, summarize: "Sage: I already know [X] about this area from previous sessions. I'll focus on what's new or missing."
Step 3: Scan and Analyze
Broad Scan
- Read project structure — file tree, key directories
- Read README, package.json / pyproject.toml / go.mod, config files
- Identify tech stack, frameworks, build tools
- Read entry points — main modules, routing, API surface
- Identify architectural patterns — MVC, microservices, monolith, etc.
- Note conventions — naming, file organization, testing approach
Deep Dive
- Read all files in the target area
- Trace dependencies — what it imports, what imports it (depth 3 max)
- Map data flow — inputs, transformations, outputs
- Identify design patterns, error handling, edge cases
- Assess quality — strengths, risks, technical debt
Step 4: Review Findings
Before storing knowledge, present key findings to the user. Wrong knowledge stored in memory persists into future sessions and causes confident wrong actions.
Findings quality checklist — for each finding, verify:
- Specific? Does it name concrete things (files, patterns, tools)? "Uses microservices" is too vague. "Uses gRPC between billing and auth services, REST for public API" is specific.
- Insight, not inventory? Does it tell you something you can't
get from
ls? "Has a src/ directory" is inventory. "All business logic lives in src/domain/, handlers are thin wrappers" is insight. - Actionable? Would a future agent use this to make a better decision? If not, don't store it.
If a finding fails any criterion, improve it before presenting.
Sage: Here's what I found about [area]:
- [Key finding 1]
- [Key finding 2]
- [Key finding 3-5]
[A] Looks correct — store in memory [R] Some findings are wrong — let me correct them
Do NOT present vague findings and rely on the user to approve them. The user may click [A] without scrutiny. The quality gate is YOUR responsibility, not the user's.
If the user corrects any findings, update before storing. Store the correction as a self-learning entry (Rule 6).
Step 5: Store Knowledge
Store each finding by calling the sage_memory_store MCP tool directly.
Each call stores one focused insight with these parameters:
- content (string): detailed finding — what, why, implications
- title (string): short specific title (5-15 words)
- tags (array of strings): domain and area tags, e.g. ["billing", "auth"]
- scope (string): "project"
MCP parameter types matter: tags must be an actual array, not a JSON string. Pass ["billing", "auth"], not '["billing", "auth"]'. Same for all array and integer parameters across all sage-memory tools.
For broad scans, aim for 10-20 calls covering:
- Tech stack and framework choices
- Project structure and organization
- Key architectural patterns
- Conventions and coding standards
- Domain concepts and business logic
- Notable dependencies and integrations
For deep dives, aim for 5-10 calls covering:
- Module purpose and role in the system
- Key components and their responsibilities
- Data flow and integration points
- Patterns specific to this area
- Risks, debt, or improvement opportunities
Tag entries appropriately:
- Domain tags always (e.g.,
billing,auth) ontologytag for entity relationships and dependencieslearningtag for gotchas or non-obvious behavior discovered
If sage_memory_store is not available, fall back to .sage-memory/
files. For each finding, create a file using the format defined in the
sage-memory skill's Storage Priority section. Filename = kebab-case title.
Ontology Bootstrapping
After storing prose knowledge, create ontology entities for the structural elements you discovered. This builds a knowledge graph that keeps the codebase's architecture navigable across sessions.
For broad scans, create entities for:
- Each major module or service →
Projectentity (name, status: active) - Key inter-module dependencies →
depends_onrelations - Entry points (APIs, CLI commands, main routes) →
Documententities
For deep dives, create entities for:
- The module itself →
Projectentity if not already in graph - Key internal components →
Taskentities (as sub-units of work) - Dependencies this module has on other modules →
depends_onrelations - Services it calls or is called by →
depends_onrelations
Keep it lightweight:
- Only create entities for things a future agent needs to navigate (modules, services, APIs, dependencies) — not every file or function
- Search ontology first (
sage_memory_search: tags=["ontology"]) to avoid duplicating existing entities - 5-15 ontology entries for broad scans, 3-8 for deep dives
- Use the encoding format from
skills/sage-ontology/SKILL.md
Step 6: Generate Knowledge Report
Save a human-readable report to .sage/docs/memory-{name}.md.
Follow the sage-memory skill's references/knowledge-report.md guide:
- Adapt structure to content (don't force a rigid template)
- Include mermaid diagrams when they clarify architecture or data flow
- Focus on insights, not inventory
- Note how many memory entries were stored
Step 7: Report Summary
Sage: Learning complete — [area name]
Knowledge stored: • [X] memories in sage-memory • Report: .sage/docs/memory-{name}.md
Key findings: • [Top 3-4 insights, one line each]
[C] Continue — learn another area
Next steps: /build — spec → plan → implement → verify /research — interview → JTBD → opportunity map /reflect — review what you learned, extract patterns
Type a command, or describe what you want to do next.
Rules
- Search before storing — don't duplicate existing knowledge.
- Store insights, not facts readable from files.
- One insight per memory entry — focused entries retrieve precisely.
- Adapt depth to scope — broad scans stay high-level, deep dives trace dependencies and assess quality.
- The knowledge report is for humans. Memory entries are for the agent. Both should exist for significant learning.