take-notes

Notes you can actually learn from — not a transcript dump, not a one-paragraph summary.

Point it at a video, an article, a paper, or a repo. You get a self-contained
HTML page — executive summary, the one takeaway, key points, and a timestamped
or sectioned outline — written to ~/take-notes/html_reports/ and opened in
your browser. They pile up into a browsable archive you own, on your disk, in
plain HTML that will still open in ten years.

Sources · How to use · Focus · Gallery · Tags · Export · Install · Credits

Why I built it

I kept watching hour-long videos and reading long posts, feeling like I'd
learned something, and then having nothing to show for it a week later. The
summaries I could get were either a wall of transcript or three bland
sentences — both useless for actually remembering anything.

So the rule this skill follows is: explain, don't compress. A bullet only
someone who already watched the video would understand has failed. Order things
by what has to be understood first, not by when they were said. Say what the
source left unanswered. And keep every note as one HTML file on my own disk,
because notes that live in someone else's product stop being yours eventually.

Sources

How to use

Point it at a URL. That is the whole thing:

/take-notes https://www.youtube.com/watch?v=NiKtZgImBdY
/take-notes https://simonwillison.net/2025/Jan/11/phi-4-bug-fixes/
/take-notes https://arxiv.org/abs/2407.09141
/take-notes https://github.com/ggml-org/llama.cpp

It writes ~/take-notes/html_reports/YYYY-MM-DD-<slug>.html and opens it.
Re-running on the same source the same day updates that note rather than
leaving a near-duplicate beside it.

It runs only when you ask. The skill never fires on a URL you merely mention in
conversation, in any tool it's installed in.

Focus

Add a phrase after the URL and the run narrows to it:

/take-notes https://unsloth.ai/docs/basics/dynamic-3.0-ggufs "just the v3.0 methodology"
/take-notes https://youtu.be/… "only the part about retrieval"

Focus narrows two things at once: what gets fetched — only the sections in
scope are pulled in rather than the whole document, which is where the token
saving comes from, since the source text is by far the largest input in a run —
and what the finished notes emphasise. It pays on a docs page that stacks
several versions of itself, a paper where you want one section, or a two-hour
video where twenty minutes matter; a short single-topic post has nothing to
trim. Leave it off to cover a source in full.

Gallery

Notes pile up. scripts/gallery.py reads whatever is in
~/take-notes/html_reports/ and writes ~/take-notes/gallery.html — a card
per note, newest first, poster for videos and a filing plate for articles,
with a filter box (/ focuses it, Esc clears it). Then it opens it.

Under the filter bar is a chip per tag in use: click one to narrow the
grid to that tag, click it again to clear. Chip and text filter combine.

_{The gallery — the four notes in docs/examples/, every one of them real output. Clone the repo and open any of them to see a note in full.}

uv run ~/.claude/skills/take-notes/scripts/gallery.py   # or your checkout path

Worth an alias, since you'll run it more than once:

alias notes='uv run ~/.claude/skills/take-notes/scripts/gallery.py'

It's a plain script, not a skill — building an index of files on disk needs
no model in the loop, so no agent is involved and nothing is spent. Re-run it
after taking notes; it rebuilds from scratch every time, so a note you delete
by hand simply stops appearing.

Flags: --no-open, --notes-dir, --out, --lang en|es (defaults to the
language in ~/take-notes/config.json).

Language

Optional — notes are written in English unless you say otherwise.

// ~/take-notes/config.json
{ "language": "es" }   // "en" (default) | "es" | "ask"

"ask" restores the per-run prompt, offering the source's own language first.

Override it for a single run with --lang, which beats the config — including
"ask", since an explicit flag is not a question:

/take-notes https://youtu.be/… --lang en

Precedence is --lang → a language named in words ("…in English") → config →
English. A missing or malformed config falls back to English rather than
failing, and an unsupported --lang is reported rather than silently applied.
When the source's language differs from the one used, the skill says so, so a
Spanish video never quietly becomes English notes without a word.

Tags

Every note is filed under one primary tag, plus any extras that apply. The
vocabulary lives beside language in the same config, and it is closed:
the skill picks from your list and never invents a tag, so the taxonomy stays
yours rather than whatever the model felt like that day.

// ~/take-notes/config.json
{ "language": "es", "tags": ["Unknown", "AI", "Investing", "Engineering"] }

Nothing fits — or no vocabulary is set — and the note lands on Unknown,
silently. You are never prompted to invent a tag mid-run.

_{A tagged archive — the primary tag sits beside the kind on each card, and every tag in use gets a chip. The notes are the four real examples; the tags on them are illustrative.}

The full grammar, for reference:

/take-notes <url> [focus] [--lang en|es]
/take-notes --tags | --add-tag "AI" | --remove-tag "AI" | --retag

The second line manages tags instead of writing a note. Edit the list from the
skill, or from the CLI when you're already in a terminal:

/take-notes --tags                  # list it
/take-notes --add-tag "AI"          # add, report, write no note
/take-notes --remove-tag "AI"       # remove

uv run skills/take-notes/scripts/tags.py --add AI --add Investing
uv run skills/take-notes/scripts/tags.py --remove Investing

Both edit the same file and leave language untouched. Unknown is the
fallback the skill needs, so it can't be removed.

Set the vocabulary up after you'd already taken notes? /take-notes --retag
re-files the notes on disk against it, no source refetched and no prose
rewritten — it edits the tag row and nothing else:

/take-notes --retag

It reads each note's title and opening, picks from your vocabulary — never
outside it — and leaves anything that fits nothing on Unknown. Notes already
carrying a tag you chose are left alone. The underlying script is usable on its
own when you want to file one note by hand:

uv run skills/take-notes/scripts/retag.py --list                  # notes + current tags, as JSON
uv run skills/take-notes/scripts/retag.py --set NOTE.html --tag AI --tag Engineering

Rebuild the gallery afterwards so the chips match. Changing a single note's tag
also still works the old way: re-run /take-notes on its source — same day,
same file, new tag.

Export

Notes are yours, so they leave cleanly. Both exporters read the rendered notes;
neither needs an agent or costs tokens.

uv run skills/take-notes/scripts/export.py --format md     # → ~/take-notes/markdown/
uv run skills/take-notes/scripts/export.py --format anki   # → ~/take-notes/take-notes.txt

• md — one Markdown file per note with YAML frontmatter. Drop the folder
  into an Obsidian vault, or import it into Notion. Timestamp links survive as
  real Markdown links, and the note's tags land in the frontmatter tags: list,
  which is what Obsidian's tag pane reads.
• anki — a tab-separated deck file. Cards come from Key points (claim →
  detail), Concepts (term → definition), and the one takeaway. The note's tags
  join the card kind in the tags column, so a deck filters by topic too. Import
  with File → Import and leave Allow HTML in fields on.

Install

Works in any Agent Skills-compatible tool — Claude
Code, Codex, Cursor, OpenCode, Gemini CLI, and any other host that reads the
same standard SKILL.md — no per-tool variants to maintain. Every script is
stdlib-only Python run through uv; there is nothing to pip install.

Claude Code (auto-updates via the marketplace):

/plugin marketplace add davertor/take-notes
/plugin install take-notes@take-notes

That is the one to use if you have Claude Code — it is the only route that
auto-updates. The two options below are for everything else, or for editing the
skill yourself. Neither auto-updates; re-run it (or git pull) for the latest.

Option A — clone + symlink, for tinkering

git clone https://github.com/davertor/take-notes
cd take-notes
./link-skill.sh              # every tool
AGENT=claude ./link-skill.sh # one tool only

link-skill.sh symlinks skills/take-notes into each
tool's skills directory (claude, codex, cursor, opencode, gemini,
agents). Idempotent, and replaces anything already occupying a target. A
real checkout — edit skills/take-notes/ directly, or git pull for
upstream changes.

Option B — the skills CLI

Codex, Cursor, OpenCode, Gemini CLI, or any other Agent Skills host:

npx skills add davertor/take-notes -g                  # install for your user
npx skills add davertor/take-notes -g -a claude-code   # one agent only

Pass -g — without it, add installs project-level into the current
folder instead of your user directories. Update with npx skills update take-notes.

Prerequisites

Web articles need none of the above — that path uses the agent's fetch tool.

Both install paths land on the same /take-notes — neither namespaces nor
renames it.

Credits

Issues and pull requests are welcome — CONTRIBUTING.md
has the setup, the self-checks, and the four constraints that are easy to trip
over. The most useful issue you can open is a source it handled badly, with the
URL. Released changes are logged in CHANGELOG.md.

• bradautomates/claude-video by Bradley Bonanno (MIT).

Star this repo

If a note from this saved you rewatching an hour of video to find the one thing
you actually needed, a star costs you nothing and is how the next person finds
it. ⭐