learn-craft

What this skill does

# learn-craft

Build a working, book-grounded skill on any craft the user wants to master.

The shape of the output mirrors the `ultimate-sales` skill: a tight `SKILL.md` (always loaded), a `frameworks/` folder organized by **concept** (the synthesized knowledge base — this is where the real value lives), and a `references/` folder organized by **book** (citation layer). The user gets a coach that thinks in concepts, not a shelf of book summaries.

## What's bundled

The book-fetching script (`scripts/libgen.py`) is bundled here — no separate install required. It's a stdlib-only Python script that searches libgen.li, picks the best complete English PDF, and saves it locally.

## When to use

Trigger when the user wants the canonical thinking on a topic distilled into something they can act on. Examples:
- "I want to learn investing" → topic = investing
- "make me a skill on negotiation"
- "I want to get really good at writing"
- "create a coach for product strategy"

Don't trigger for:
- Pure workflow automation ("make a skill that scrapes X") → that's `/skill-creator`.
- Single-book summaries ("summarize Atomic Habits") → just read the file.
- Already-existing skills (check `~/.claude/skills/` first; if a skill on this topic exists, ask whether to extend it or replace it).

## The mental model — concepts, not books

The single most important thing to understand about this skill: **the output is organized by concept, not by book.**

The wrong shape:

```
my-skill/
└── references/
    ├── book-1-summary.md     ← "what does Author 1 say?"
    ├── book-2-summary.md     ← "what does Author 2 say?"
    └── book-3-summary.md     ← "what does Author 3 say?"
```

This is a bookshelf, not a skill. To answer any real question the model has to read all three files and re-synthesize on the fly — every single time.

The right shape:

```
my-skill/
├── SKILL.md                       ← worldview + diagnose-first loop
├── frameworks/                    ← THE KNOWLEDGE BASE — organized by concept
│   ├── diagnose-first.md          ← cross-book; cites multiple authors
│   ├── tactical-empathy.md        ← named concept; main author + supporting
│   ├── question-arsenal.md        ← cross-book question taxonomy
│   └── ...
└── references/                    ← citation layer — read-on-demand
    ├── book-1.md                  ← deep-dive into Book 1's distinctive contribution
    ├── book-2.md
    └── ...
```

Now `frameworks/diagnose-first.md` *is* the synthesized concept — already cross-referenced, already prioritized, already de-duplicated. The `references/` layer is for when someone wants to drill into one author's original framing or hear their voice. Most queries never need to crack the references — the frameworks are sufficient on their own.

**This distinction is what separates a real skill from a glorified summary.** The synthesis stage (Stage 4) is where this happens. Don't skip it, don't shortcut it.

## The five-stage process

1. **Scope the craft** — confirm the topic and pick 4 canonical books.
2. **Download** — fetch each book as a PDF via the bundled `scripts/libgen.py`.
3. **Read in parallel** — spawn 4 subagents, one per book, each producing a structured per-book learnings document (working notes — not the final product).
4. **Synthesize** — extract concepts that span multiple books, name them, organize them. **This is the stage that's easy to skip and that ruins the skill if skipped.** Most of the orchestrator's thinking happens here.
5. **Author** — write the SKILL.md, frameworks/, and references/ from the synthesis.

Track these as five todos via TaskCreate so progress is visible to the user. Each stage is described below.

---

## Stage 1 — Scope the craft

If the user didn't name the topic, ask: *"What craft do you want to learn?"* Keep it open — they might say "investing", "Stoic philosophy", "negotiation", "Olympic weightlifting".

Once you have the topic, pick 4 canonical books. Use **WebSearch** with queries like:
- `"best books on <topic>" canonical`
- `"<topic>" foundational reading list`
- `"<topic>" recommended books site:reddit.com OR site:hacker news` (community wisdom often beats SEO listicles)

**How to choose 4 books:**
- Prefer **canonical/foundational** texts over recent bestsellers, unless the field is fast-moving (then mix one recent).
- Prefer **practitioner-written** over academic surveys — the user wants to *do* the thing, not write a paper about it.
- Cover **different angles**: theory, practice, contrarian, biography/case-study. A Stoic skill might be Aurelius (primary source), Holiday (modern bridge), Pigliucci (philosophical defense), Robertson (psychological application).
- **Avoid duplication** — three books on the same author's framework is wasteful. But *do* allow some overlap: synthesis only works if the books talk to each other on shared concepts.

Present the 4 books to the user as `Title — Author (year)` with a one-line "why this one" for each. Ask: *"Look right? Swap any?"* Wait for confirmation before downloading. This is the cheapest moment to course-correct.

If the user declines a book, propose a replacement and reconfirm. If they want fewer than 4 (e.g., "just 2 is fine"), proceed with what they want — the rest of the pipeline scales linearly.

---

## Stage 2 — Download

Create the working layout: `~/.claude/skills/<slug>/notes/`. Use a kebab-case slug derived from the topic (e.g., "investing", "stoic-philosophy", "negotiation"). The `notes/` directory will hold both the raw PDFs and the per-book learning files — these are working materials, not the final product, and the name reflects that.

For each book, call the bundled script directly:

```bash
python3 ~/.claude/skills/learn-craft/scripts/libgen.py "<title>" \
  --out ~/.claude/skills/<slug>/notes \
  --lang english
```

Run them in parallel by sending multiple Bash calls in a single message. Each download takes ~5–15 seconds.

**The script's behavior at a glance** (full docs in the comments at the top of `scripts/libgen.py`):
- Searches libgen.li with the given title (forwarded to libgen's fuzzy server-side match).
- Filters to complete PDFs (rejects `0` or `0/N` page counts that indicate unscanned/partial copies).
- Filters to English by default; non-English results get marked `⚠ off-language` and are not auto-downloaded. Override with `--lang any` or `--lang italian|spanish|french|german|...`.
- Ranks results: complete > derivative-free (workbook/summary penalty) > title-keyword overlap > most pages > most recent year > smallest size.
- Follows the libgen.li → CDN redirect, saves to `--out` with the filename from the server's `Content-Disposition`.
- Useful flags: `--list` (print top 5 candidates without downloading), `--pick N` (choose a non-default candidate by index), `--author NAME` (only add if the title alone is ambiguous — extra words tighten libgen's AND filter), `--year YYYY` (same caveat).
- Exit codes: `0` success / list-only, `1` no acceptable PDF, `2` network or HTTP error.
- On success, the saved file path is the only thing on stdout — everything else goes to stderr.

**Failure modes to handle:**
- **No English PDF found** (exit code 1): try once with the title alone (drop subtitle); if still nothing, ask the user whether to (a) accept an alternate edition with `--lang any`, (b) substitute a different book on the same topic, or (c) skip and proceed with three.
- **HTTP errors** (exit code 2): retry once after a few seconds — libgen.li is intermittently flaky.
- **Wrong book** (a workbook or summary slipped through): rerun with `--list` and `--pick N` after the user reviews.

After Stage 2, confirm with the user: list saved file paths and page counts. *"Got all four — ready to read them?"*

---

## Stage 3 — Read in parallel (working notes)

Spawn one **general-purpose** subagent per book in a single message (parallel execution). The output of this stage is **working notes** — raw structured extraction, not the final knowledge base. Be e