learn-x-in-y-minutes

Learn X in Y Minutes

Generate a quick-start tutorial in the learnxinyminutes.com format for any topic.

Process

1. Identify the subject and source

   What the user gives	How to get content
   GitHub URL	gh CLI — see references/github.md
   Local path	Glob/Read
   Command name (e.g. cat, awk)	man {cmd}, {cmd} --help, built-in knowledge
   Named topic (language, algorithm, concept)	Built-in knowledge + WebSearch if needed
   Docs/blog URL	WebFetch

2. Classify category: language, framework, library, cli_command, tool, algorithm, concept

3. Gather content: read actual source — man pages, real code, official docs. Don't invent behavior.

4. Pick the right format based on category (see Output Format below)

5. Generate output using the matching section template

Output Format

The format varies by category. Read the matching example before generating.

Languages & Frameworks/Libraries

Code-first: short prose intro outside the code block, then one big fenced code block for the whole tutorial. Section dividers are comment-style inside the code — no markdown headers.

---
name: {Name}
filename: learn{repo}.{ext}
contributors:
    - ["Generated by Claude", "https://claude.ai"]
    - ["Source: {owner}/{repo}", "{url}"]
---

{2-3 sentence prose intro. Plain text, NOT inside a code block.}

```{ext}
# Learn {Tool} in Y minutes
# Source: {url}

####################################################
## 1. Installation
####################################################

# Install via brew (macOS)
brew install {tool}        # => installs {tool}

####################################################
## 2. Basic Usage
####################################################

{tool} file.txt            # => output shown inline

# Further Reading
# - Repository: {url}
```

Tools (git-style)

Prose + per-command code blocks: markdown ## Section headers, short explanatory paragraphs, then a fenced block per command group. No single mega code block. See examples/git.md.

Algorithms & Data Structures

Prose-heavy: explain the concept in plain language first, then small pseudocode or code snippets for each example. Markdown headers for sections. See examples/dynamic-programming.md.

---

Key rules (all categories)

• Frontmatter fields: name, filename, contributors. Optional: category. No language: field.
• filename format: learn{subject}.{ext} using the subject's primary language extension.
• Number sections: every section gets a number (1. Basics, 2. Control Flow). Readers should be able to follow progression at a glance.
• Section dividers: use the subject's own comment syntax and conventions — match what idiomatic code in that language/tool looks like, not a generic template.
• Show output inline: annotate expressions with their result right next to the code. For multi-line output, use consecutive comment lines immediately after.
• Show wrong-way examples: when a common mistake has a non-obvious reason, show the broken version with its error before the correct one. Explain why it breaks, not just that it does. This is one of the most distinctive learnxinyminutes patterns.
• Explain surprising behavior inline: don't save gotchas for a separate section. Put the explanation in a comment block right next to the code that triggers it.
• The file should feel native: a reader familiar with the language/tool should recognize the style. If the subject has idioms for structuring files or organizing concepts, use them.

Section Templates by Category

Language: Primitives → Variables → Control Flow → Functions → Data Structures → Modules Library/Framework: Installation → Core API → Common Patterns → Configuration → Advanced Usage CLI Command (e.g. cat, grep, awk): What it does → Basic syntax → Common flags → Practical examples → Combining with other tools Tool (e.g. git, docker): Concepts → Core commands → Options & Flags → Integration Tips Web Framework: Setup → Routing → Request Handling → Middleware → Testing Data Science: Setup → Data Loading → Core Operations → Visualization Algorithm/DS: Core Idea → Approaches → Examples (with complexity) → When to Use → Further Reading Concept: What it is → Why it matters → How it works → Examples → Common pitfalls

Gotchas

• Frontmatter is required. Always output YAML frontmatter. Do NOT skip it.
• Only valid frontmatter fields: name, filename, contributors. No language:, title:, layout:, or description: fields.
• No markdown headers inside the tutorial. Everything after the prose intro lives inside one code block. Use comment-style section dividers, not ## Heading.
• filename format: learn{repo}.{ext}. If repo already starts with "learn", don't double it. Example: repo = learnxinyminutes → learnlearnxinyminutes.py is wrong → use learnxinyminutes.py.
• Use real behavior, not invented examples. For repos: read actual source. For commands: run man or --help. For concepts: use authoritative knowledge. Never fabricate flags or APIs.
• Match the subject's actual tooling — if the project uses uv, show uv; if the command has a -i flag, show -i.
• Keep it scannable — this is "Y minutes", not a reference manual. Prioritize the 20% that gives 80% understanding.
• For GitHub repos: read references/github.md for gh CLI commands.
• filename format: for commands like cat, use .sh; for concept guides use the language the examples are in.

Output Checklist

Before returning the tutorial, verify:

• YAML frontmatter with name, filename, contributors (no language: field); category included when subject is a tool, framework, or algorithm/DS
• Short prose intro paragraph (outside any code block)
• Format matches the category — code-first for languages/libraries, prose+blocks for tools, prose-heavy for algorithms/concepts
• At least 3 sections covering the subject's key areas
• Examples use real behavior (from source, man page, or authoritative knowledge)
• Footer with "Further Reading" links

References

• references/github.md — GitHub-specific analysis using gh CLI (load when analyzing a GitHub URL) Languages (code-first, one big block):
• references/examples/bash.md — shell/CLI language (# comment dividers)
• references/examples/python.md — scripting language (#### section dividers)
• references/examples/go.md — compiled language (// comment sections)

Frameworks & Libraries (code-first, one big block with /// dividers):

• references/examples/jquery.md — JS library (/// section dividers, event/DOM/AJAX sections)

Tools (markdown sections + per-command code blocks):

• references/examples/git.md — CLI tool (concept prose → ## Commands → per-command blocks)

Algorithms & Data Structures (prose-heavy + small code snippets):

• references/examples/dynamic-programming.md — concept explanation → examples → complexity table

Load the example that matches your project's category before generating output.