Learn

learn

Research any topic by gathering online resources and creating a comprehensive learning guide with RAG-optimized indexes.

Parse Arguments

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const depth = args.find(a => a.startsWith('--depth='))?.split('=')[1] || 'medium';
const topic = args.filter(a => !a.startsWith('--')).join(' ');

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 | 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:

// 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 | | <minSources found | Warn user, proceed with available | | Enhancement fails | Skip, note in output | | Index doesn't exist | Create new index |

Token Budget

Estimated token usage by phase:

| Phase | Tokens | Notes | |-------|--------|-------| | WebSearch queries | ~2,000 | 5-8 queries | | Source scoring | ~1,000 | Metadata only | | WebFetch extraction | ~40,000 | 20 sources × 2,000 avg | | Synthesis | ~10,000 | Guide generation | | Enhancement | ~5,000 | Two skill calls | | Total | ~60,000 | Within opus budget |

Integration

This skill is invoked by:

• learn-agent for /learn command
• Potentially other research-oriented agents

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agent-sh
• Source: agent-sh/agentsys
• License: MIT
• Homepage: https://agent-sh.github.io/agentsys/

Install and usage instructions live in the source repository linked above.