--- name: learn description: "Research any topic online and create learning guides. Use when user asks to 'learn about', 'research topic', 'create learning guide', 'build knowledge base', or 'study subject'." version: 4.2.2 argument-hint: "[topic] [--depth=brief|medium|deep]" --- > **OpenCode Note**: Invoke agents using `@agent-name` syntax. > Available agents: task-discoverer, exploration-agent, planning-agent, > implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent > Example: `@exploration-agent analyze the codebase` # learn Research any topic by gathering online resources and creating a comprehensive learning guide with RAG-optimized indexes. ## Parse Arguments *(JavaScript reference - not executable in OpenCode)* ## Input Arguments: ` [--depth=brief|medium|deep]` - **topic**: Subject to research (required) - **--depth**: Source gathering depth - `brief`: 10 sources (quick overview) - `medium`: 20 sources (default, balanced) - `deep`: 40 sources (comprehensive) ## Research Methodology Based on best practices from: - Anthropic's Context Engineering - DeepLearning.AI Tool Use Patterns - Anara's AI Literature Reviews ### 1. Progressive Query Architecture Use funnel approach to avoid noise from long query lists: **Broad Phase** (landscape mapping): ``` "{topic} overview introduction" "{topic} documentation official" ``` **Focused Phase** (core content): ``` "{topic} best practices" "{topic} examples tutorial" "{topic} site:stackoverflow.com" ``` **Deep Phase** (advanced, if depth=deep): ``` "{topic} advanced techniques" "{topic} pitfalls mistakes avoid" "{topic} 2025 2026 latest" ``` ### 2. Source Quality Scoring Multi-dimensional evaluation (max score: 100): | Factor | Weight | Max | Criteria | |--------|--------|-----|----------| | Authority | 3x | 30 | Official docs (10), recognized expert (8), established site (6), blog (4), random (2) | | Recency | 2x | 20 | <6mo (10), <1yr (8), <2yr (6), <3yr (4), older (2) | | Depth | 2x | 20 | Comprehensive (10), detailed (8), overview (6), superficial (4), fragment (2) | | Examples | 2x | 20 | Multiple code examples (10), one example (6), no examples (2) | | Uniqueness | 1x | 10 | Unique perspective (10), some overlap (6), duplicate content (2) | **Selection threshold**: Top N sources by score (N = depth target) ### 3. Just-In-Time Retrieval Don't pre-load all content (causes context rot): 1. **Collect URLs first** via WebSearch 2. **Score based on metadata** (title, description, URL) 3. **Fetch only selected sources** via WebFetch 4. **Extract summaries** (not full content) ### 4. Content Extraction Guidelines For each source, extract: ```json { "url": "https://...", "title": "Article Title", "qualityScore": 85, "scores": { "authority": 9, "recency": 8, "depth": 7, "examples": 9, "uniqueness": 6 }, "keyInsights": [ "Concise insight 1", "Concise insight 2" ], "codeExamples": [ { "language": "javascript", "description": "Basic usage pattern" } ], "extractedAt": "2026-02-05T12:00:00Z" } ``` **Copyright compliance**: Summaries and insights only, never verbatim paragraphs. ## Output Structure ### Topic Guide Template Create `agent-knowledge/{slug}.md`: ```markdown # Learning Guide: {Topic} **Generated**: {date} **Sources**: {count} resources analyzed **Depth**: {brief|medium|deep} ## Prerequisites What you should know before diving in: - Prerequisite 1 - Prerequisite 2 ## TL;DR Essential points in 3-5 bullets: - Key point 1 - Key point 2 - Key point 3 ## Core Concepts ### {Concept 1} {Synthesized explanation from multiple sources} **Key insight**: {Most important takeaway} ### {Concept 2} {Synthesized explanation} ## Code Examples ### Basic Example ```{language} // Description of what this demonstrates {code} ``` ### Advanced Pattern ```{language} {code} ``` ## Common Pitfalls | Pitfall | Why It Happens | How to Avoid | |---------|---------------|--------------| | Issue 1 | Root cause | Prevention strategy | ## Best Practices Synthesized from {n} sources: 1. **Practice 1**: Explanation 2. **Practice 2**: Explanation ## Further Reading | Resource | Type | Why Recommended | |----------|------|-----------------| | [Title]({url}) | Official Docs | Authoritative reference | | [Title]({url}) | Tutorial | Step-by-step guide | --- *Generated by /learn from {count} sources.* *See `resources/{slug}-sources.json` for full source metadata.* ``` ### Master Index Template Create/update `agent-knowledge/CLAUDE.md`: ```markdown # Agent Knowledge Base > Learning guides created by /learn. Reference these when answering questions about listed topics. ## Available Topics | Topic | File | Sources | Depth | Created | |-------|------|---------|-------|---------| | {Topic 1} | {slug1}.md | {n} | medium | 2026-02-05 | | {Topic 2} | {slug2}.md | {n} | deep | 2026-02-04 | ## Trigger Phrases Use this knowledge when user asks about: - "How does {topic1} work?" → {slug1}.md - "Explain {topic1}" → {slug1}.md - "{Topic2} best practices" → {slug2}.md ## Quick Lookup | Keyword | Guide | |---------|-------| | recursion | recursion.md | | hooks, react | react-hooks.md | ## How to Use 1. Check if user question matches a topic 2. Read the relevant guide file 3. Answer based on synthesized knowledge 4. Cite the guide if user asks for sources ``` Copy to `agent-knowledge/AGENTS.md` for OpenCode/Codex. ### Sources Metadata Create `agent-knowledge/resources/{slug}-sources.json`: ```json { "topic": "{original topic}", "slug": "{slug}", "generated": "2026-02-05T12:00:00Z", "depth": "medium", "totalSources": 20, "sources": [ { "url": "https://...", "title": "...", "qualityScore": 85, "scores": { "authority": 9, "recency": 8, "depth": 7, "examples": 9, "uniqueness": 6 }, "keyInsights": ["..."] } ] } ``` ## Self-Evaluation Checklist Before finalizing, rate output (1-10): | Metric | Question | Target | |--------|----------|--------| | Coverage | Does guide cover main aspects? | ≥7 | | Diversity | Are sources from diverse types? | ≥6 | | Examples | Are code examples practical? | ≥7 | | Accuracy | Confidence in content accuracy? | ≥8 | **Flag gaps**: Note any important subtopics not covered. ## Enhancement Integration If enhance=true, invoke after guide creation: ```javascript // Enhance the topic guide for RAG Skill({ name: 'enhance-docs', args: `agent-knowledge/${slug}.md --ai` }); // Enhance the master index Skill({ name: 'enhance-prompts', args: 'agent-knowledge/CLAUDE.md' }); ``` ## Output Format Return structured JSON between markers: ``` === LEARN_RESULT === { "topic": "recursion", "slug": "recursion", "depth": "medium", "guideFile": "agent-knowledge/recursion.md", "sourcesFile": "agent-knowledge/resources/recursion-sources.json", "sourceCount": 20, "sourceBreakdown": { "officialDocs": 4, "tutorials": 5, "stackOverflow": 3, "blogPosts": 5, "github": 3 }, "selfEvaluation": { "coverage": 8, "diversity": 7, "examples": 9, "accuracy": 8, "gaps": ["tail recursion optimization not covered"] }, "enhanced": true, "indexUpdated": true } === END_RESULT === ``` ## Error Handling | Error | Action | |-------|--------| | WebSearch fails | Retry with simpler query | | WebFetch timeout | Skip source, note in metadata | |