Back to Details

take-notes

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/take-notes

/take-notes

Turn a source into notes you can learn from — not a transcript dump, not a one-paragraph summary. The output is one self-contained HTML page written to 
~/take-notes/html_reports/
and opened in the browser, so the notes accumulate into a browsable local archive instead of scrolling away in the terminal.
Invocation: 
/take-notes <url> [more urls…] [focus]
. If no URL is given, ask for one. Several URLs are one note about one subject from several sources — a talk and the deck it was given from, a paper and the repo that implements it — not one note each; Step 1 says how they combine. The optional focus does two things: it narrows what Step 1 asks the source for — on a long or multi-topic source, that's the difference between fetching the whole thing and fetching only the part that matters — and it narrows what the finished notes emphasise in Step 3-4. Skip it to cover a source in full; add it ("just the API design part") when only part of a long source is relevant. 
--tags
, 
--add-tag
, and 
--remove-tag
manage the tag vocabulary instead — see Step 0.
将来源内容转换为可供学习的笔记——不是转录内容的堆砌，也不是单段落摘要。输出为独立的HTML页面，存储在
~/take-notes/html_reports/
目录下并在浏览器中打开，因此笔记会累积成可浏览的本地归档，而非在终端中滚动后消失。
调用方式：
/take-notes <url> [更多url…] [重点方向]
。如果未提供URL，则请求用户输入。多个URL表示围绕同一主题，整合多个来源生成单份笔记——比如一场演讲及其配套幻灯片、一篇论文及其实现代码仓库——而非为每个来源各生成一份笔记；步骤1说明了如何整合这些来源。 可选的重点方向有两个作用：一是缩小步骤1中对来源内容的提取范围——对于篇幅较长或包含多个主题的来源，这能区分是提取全部内容还是仅提取相关部分；二是缩小最终笔记在步骤3-4中的重点内容范围。若需覆盖来源全部内容可省略该参数；当仅需关注长来源的部分内容时添加该参数（例如“仅API设计部分”）。 
--tags
、
--add-tag
和
--remove-tag
用于管理标签词汇表——详见步骤0。

Resolve 
SKILL_DIR
(before any command, both source types)

解析
SKILL_DIR
（执行任何命令前，适用于所有来源类型）

The scripts are bundled with this skill, a direct sibling of this file. Set 
SKILL_DIR
to the absolute path of the directory containing THIS SKILL.md you just Read — your harness reported it in the Read result — and substitute it literally in every command below:
bash
SKILL_DIR="<absolute path of the directory containing the SKILL.md you Read>"
if [ ! -f "$SKILL_DIR/scripts/render.py" ]; then
  echo "ERROR: scripts/render.py not found under SKILL_DIR=$SKILL_DIR" >&2
  exit 1
fi
脚本与本技能捆绑在一起，与本文件处于同一目录层级。将
SKILL_DIR
设置为包含你刚读取的THIS SKILL.md文件的目录的绝对路径——你的执行环境已在读取结果中报告该路径——并在以下所有命令中直接替换该变量：
bash
SKILL_DIR="<包含你读取的SKILL.md文件的目录的绝对路径>"
if [ ! -f "$SKILL_DIR/scripts/render.py" ]; then
  echo "ERROR: scripts/render.py not found under SKILL_DIR=$SKILL_DIR" >&2
  exit 1
fi

Step 0 — tag management short-circuits everything else

步骤0 — 标签管理优先于其他所有操作

Three invocations manage the tag vocabulary instead of writing a note. If the invocation is one of them, run the matching command, report the result, and stop — no source, no note, nothing else in this file applies:
InvocationCommand
/take-notes --tags
uv run "${SKILL_DIR}/scripts/tags.py"
/take-notes --add-tag "AI"
uv run "${SKILL_DIR}/scripts/tags.py" --add "AI"
/take-notes --remove-tag "AI"
uv run "${SKILL_DIR}/scripts/tags.py" --remove "AI"
/take-notes --retag
re-files existing notes — the multi-step pass below
Both editing forms are repeatable — pass 
--add
or 
--remove
once per tag. The script prints the resulting vocabulary; report that, and nothing more. It rewrites only the 
tags
key, so 
language
survives untouched.
Unknown
cannot be removed: it is the fallback the note writer needs when a source fits nothing. The script says so and leaves it in place.
以下三种调用方式用于管理标签词汇表，而非生成笔记。如果调用方式属于其中一种，则执行对应的命令，报告结果后停止操作——无需处理来源、无需生成笔记，本文件中的其他内容均不适用：
调用方式命令
/take-notes --tags
uv run "${SKILL_DIR}/scripts/tags.py"
/take-notes --add-tag "AI"
uv run "${SKILL_DIR}/scripts/tags.py" --add "AI"
/take-notes --remove-tag "AI"
uv run "${SKILL_DIR}/scripts/tags.py" --remove "AI"
/take-notes --retag
重新归档现有笔记——以下为多步骤流程
两种编辑形式均可重复执行——每次添加或删除标签时传递一次
--add
或
--remove
参数。脚本会输出更新后的词汇表；仅需报告该结果，无需其他内容。脚本仅重写
tags
键，因此
language
键会保持不变。
Unknown
标签无法删除：当来源内容不匹配任何现有标签时，它是笔记生成器所需的默认标签。脚本会提示这一点并保留该标签。

--retag
— re-file the notes already on disk

--retag
— 重新归档磁盘上已有的笔记

Filing a note under a new tag used to mean re-running 
/take-notes
on its source: a refetch and a full rewrite, to change one word in the rail. This pass edits the rendered notes instead. Run it after adding tags to a vocabulary that was empty or thinner when those notes were written.
  1. Read the vocabulary — 
    uv run "${SKILL_DIR}/scripts/tags.py"
    . If the only entry is 
    Unknown
    , say so and stop: there is nothing to file notes under yet, and the user needs 
    --add-tag
    first.
  2. List what is on disk — 
    uv run "${SKILL_DIR}/scripts/retag.py" --list
    . One JSON object per note: path, title, byline, kind, date, current 
    tags
    , an 
    excerpt
    , and 
    needs_tag
    .
  3. Choose from the vocabulary and nothing else. For every note with 
    "needs_tag": true
    , pick the entry that fits from the list read in step 1; add further tags after the primary when they genuinely apply. The list is closed — the script rejects anything not on it rather than inventing a tag that would exist on one note and in no chip. Nothing fits, leave it on 
    Unknown
    ; a wrong file is worse than an unfiled note.
  4. Write each one — 
    uv run "${SKILL_DIR}/scripts/retag.py" --set "<path>" --tag "<primary>" [--tag "<extra>"]
  5. Rebuild the gallery so the chips match the notes — 
    uv run "${SKILL_DIR}/scripts/gallery.py"
  6. Report one line per note re-filed, plus how many were left on 
    Unknown
    .
"needs_tag": false
means the note already carries a deliberate tag. Leave those alone unless the user asked for every note; overwriting a filing someone chose is not an update.
The pass rewrites only the rail's tag row. No source is fetched and no prose is regenerated, so it costs the listing and the model's choices, nothing more.
过去，要为笔记添加新标签意味着需重新对其来源执行
/take-notes
命令：重新获取内容并完全重写笔记，只为修改归档中的一个词。此流程直接编辑已生成的笔记。在词汇表为空或标签较少时生成的笔记添加新标签后，执行此流程。
  1. 读取词汇表 — 
    uv run "${SKILL_DIR}/scripts/tags.py"
    。如果词汇表中仅有
    Unknown
    标签，则提示用户并停止操作：目前没有可用于归档笔记的标签，用户需要先使用
    --add-tag
    添加标签。
  2. 列出磁盘上的笔记 — 
    uv run "${SKILL_DIR}/scripts/retag.py" --list
    。每条笔记对应一个JSON对象：路径、标题、署名、类型、日期、当前
    tags
    、
    excerpt
    （摘要）和
    needs_tag
    （是否需要标签）。
  3. 仅从词汇表中选择标签。对于每个
    "needs_tag": true
    的笔记，从步骤1读取的词汇表中选择最匹配的标签；当确实适用时，可在主标签后添加额外标签。词汇表是封闭的——脚本会拒绝任何不在列表中的标签，而非创建仅在单条笔记中存在的孤立标签。如果没有匹配的标签，则保留
    Unknown
    标签；错误归档比未归档更糟。
  4. 写入每条笔记的标签 — 
    uv run "${SKILL_DIR}/scripts/retag.py" --set "<路径>" --tag "<主标签>" [--tag "<额外标签>"]
  5. 重建笔记画廊，使标签与笔记匹配 — 
    uv run "${SKILL_DIR}/scripts/gallery.py"
  6. 报告每条重新归档的笔记，以及保留
    Unknown
    标签的笔记数量。
"needs_tag": false
表示笔记已带有明确选择的标签。除非用户要求处理所有笔记，否则不要修改这些标签——覆盖他人选择的归档设置不属于更新操作。
此流程仅重写归档栏的标签行。无需重新获取来源内容或重新生成正文，因此仅需执行列表操作和模型选择，无其他开销。

Step 1 — route to the right acquisition guide

步骤1 — 选择对应的内容获取指南

Pick one reference per source by looking at it, Read it, and follow it. Only the acquisition differs; everything after Step 2 is identical for every source.
Match top to bottom and stop at the first row that fits — arXiv, Slides and GitHub links are 
http(s)
pages too, so the catch-all row would swallow them.
SourceRead
YouTube URL, any other video URL yt-dlp supports, or a local media file
references/youtube.md
arxiv.org
(or an 
ar5iv
/ arXiv DOI link) — a paper
references/arxiv.md
docs.google.com/presentation/...
— a slide deck
references/slides.md
github.com/<owner>/<repo>
— a repository root, not a file, PR, or issue
references/github.md
Any other 
http(s)
page — blog post, docs page, news article
references/web.md
Each guide hands back the same thing, and nothing more:
  • title
  • byline — channel for video, author or site for an article, the paper's authors, the repo's owner
  • span — duration for video, publication date for an article, submission date for a paper, latest release for a repo
  • canonical URL (plus the YouTube video ID when there is one)
  • body — the timestamped transcript, the article text, the paper full text, the deck's slides and speaker notes, or the README plus the repo's structure
Video sources also hand back, when yt-dlp reports them: channel URL, published date, views, a thumbnail URL, and the caption language. Pass these to Step 5 too — they drive the two-pane video layout. Articles never have them; leave those flags off entirely rather than passing empty strings.
Captions arrive in the language actually spoken. When the guide reports the track was machine-translated (no original-language track existed), note it in Going deeper: translated captions mangle proper nouns, so names taken from them are unreliable and quotes are twice-removed from what was said.
If a guide reports it could not get the body, say so and stop. Never write notes from a title, a description, or a paywall stub.
查看每个来源，选择一份参考文档并读取，然后按照该指南操作。仅内容获取方式有所不同；步骤2之后的所有操作对所有来源均相同。
从上到下匹配，找到第一个符合条件的行即停止——arXiv、幻灯片和GitHub链接也属于
http(s)
页面，因此通配行可能会覆盖它们。
来源类型读取参考文档
YouTube URL、yt-dlp支持的其他视频URL或本地媒体文件
references/youtube.md
arxiv.org
（或
ar5iv
/ arXiv DOI链接）——学术论文
references/arxiv.md
docs.google.com/presentation/...
——幻灯片
references/slides.md
github.com/<owner>/<repo>
——仓库根目录（非文件、PR或Issue）
references/github.md
其他
http(s)
页面——博客文章、文档页面、新闻文章
references/web.md
每个指南仅返回以下相同字段：
  • title（标题）
  • byline（署名）——视频的频道、文章的作者或网站、论文的作者、仓库的所有者
  • span（时间信息）——视频时长、文章发布日期、论文提交日期、仓库最新版本日期
  • canonical URL（标准URL）（如有YouTube视频ID则一并返回）
  • body（正文）——带时间戳的转录文本、文章正文、论文全文、幻灯片内容及演讲备注，或README加仓库结构
当yt-dlp返回相关信息时，视频来源还会返回：channel URL（频道URL）、published（发布日期）、views（播放量）、thumbnail（缩略图URL）和caption language（字幕语言）。将这些信息也传递至步骤5——它们用于驱动双栏视频布局。文章来源不会有这些信息；完全省略这些参数，而非传递空字符串。
字幕以实际使用的语言提供。当指南报告字幕是机器翻译（无原始语言字幕）时，在深入探索部分注明：翻译后的字幕可能会混淆专有名词，因此从中提取的名称不可靠，引用内容与实际表述存在两层偏差。
如果指南报告无法获取正文内容，则提示用户并停止操作。绝不要仅根据标题、描述或付费墙预览内容生成笔记。

More than one source

多个来源的处理方式

Route each URL through its own row above and collect the same field set for each. Fetching is the only part that repeats: from Step 2 on there is one language, one tag, one body, one note.
The first URL is the primary source. Everything the note's chrome shows comes from it — title, byline, span, canonical URL — and it picks the layout: a video first renders the two-pane video note with a poster and timestamps, a deck, paper or article first renders the article one. The rest are companions: they contribute body, and Step 5 links them in the rail. Order is the user's control over that, so take it literally rather than promoting the richest source.
A companion that yields no body is not fatal: name it, say the notes are poorer for it, and write from what did arrive. A primary that yields no body stops the run — the note would be filed under a source it was not written from.
A focus narrows every source at once, which is where it earns the most: two full-length sources is the largest input this skill ever takes.
Do not put note-writing guidance in the reference files, and do not put acquisition detail here. Two copies of the writing standard will drift.
将每个URL通过上述对应行处理，并为每个来源收集相同的字段集。仅内容获取部分需要重复执行；从步骤2开始，所有来源共用一种语言、一个主标签、一份整合后的正文、一份笔记。
第一个URL是主来源。笔记页眉显示的所有信息均来自主来源——标题、署名、时间信息、标准URL——并由主来源决定布局：视频来源优先渲染带海报和时间戳的双栏视频笔记，幻灯片、论文或文章来源优先渲染文章式布局。其余来源为辅助来源：仅贡献正文内容，步骤5会在归档栏中链接这些来源。顺序由用户控制，因此严格按照用户提供的顺序处理，而非优先选择内容更丰富的来源。
辅助来源无法获取正文内容不会导致操作终止：注明该来源，并说明笔记内容会因此不够完整，然后使用已获取的内容生成笔记。主来源无法获取正文内容则会终止操作——笔记无法归档至未从中提取内容的来源。
重点方向会同时缩小所有来源的内容范围，这是其最大价值所在：两个完整长度的来源是本技能处理的最大输入规模。
不要在参考文件中添加笔记生成指南，也不要在此处添加内容获取细节。两份笔记生成标准会逐渐偏离。

Step 2 — settle the language and the tag

步骤2 — 确定语言和标签

One read of 
~/take-notes/config.json
answers both: 
language
and 
tags
.
读取
~/take-notes/config.json
即可得到这两个信息：
language
和
tags
。

Language

语言

This skill writes in English or Spanish only. Resolve which, in this order, and stop at the first that applies:
  1. --lang en
    or 
    --lang es
    in the invocation.     Wins over everything, including a config set to 
    "ask"
    — an explicit flag is not a question.
  2. A language named in plain words in the invocation ("take notes on this in English"). Same standing as the flag; if somehow both appear, the flag wins.
  3. ~/take-notes/config.json
    .     Read it. 
    "language": "en"
    or 
    "es"
    → use it. 
    "language": "ask"
    → go to the question below.
  4. Default: English. No config, an unreadable one, or any other value — a broken config must never block the run.
json
{ "language": "es", "tags": ["Unknown", "AI", "Investing", "Engineering"] }
--lang
with anything other than 
en
or 
es
is not an error to stop on, and must not be passed through: 
render.py
silently falls back to English chrome for unknown codes, which would pair English furniture with prose in a third language. Say the value is unsupported, resolve from step 3 onward, and name what you used instead:
--lang fr
is not supported (English or Spanish only) — writing in Spanish per your config.
When you resolve to a language without asking, say so in one short line. Point at the config file only when the language came from the config or the default — someone who just typed 
--lang en
does not need to be told how to set a preference they have overridden:
Writing in English (default). Set 
"language"
in 
~/take-notes/config.json
to change.
If the source is not in the language you resolved to, say that too — a Spanish video silently producing English notes is the one surprise worth calling out:
Source is in Spanish; writing in English per your config.
本技能仅支持英语或西班牙语。按以下顺序确定语言，找到第一个适用项即停止：
  1. 调用时使用
    --lang en
    或
    --lang es
    参数    。优先级高于所有其他设置，包括配置文件中设置为
    "ask"
    的情况——明确的参数不是疑问。
  2. 调用时用普通语言指定语言（例如“用英语为这个生成笔记”）。与参数具有相同优先级；若同时出现，参数优先。
  3. ~/take-notes/config.json
    配置文件    。读取该文件。
    "language": "en"
    或
    "es"
    → 使用该语言。
    "language": "ask"
    → 执行下方的提问流程。
  4. 默认：英语。无配置文件、配置文件不可读或包含其他值——配置文件损坏绝不能阻止操作执行。
json
{ "language": "es", "tags": ["Unknown", "AI", "Investing", "Engineering"] }
--lang
参数的值若不是
en
或
es
，无需终止操作，且不能传递给后续流程：
render.py
会针对未知代码自动回退为英语页眉，这会导致英语页眉与第三语言正文搭配的问题。提示用户该值不受支持，然后从步骤3开始重新确定语言，并说明最终使用的语言：
--lang fr
不受支持（仅支持英语或西班牙语）——根据你的配置，将使用西班牙语生成笔记。
当无需提问即可确定语言时，用简短的一句话说明。仅当语言来自配置文件或默认设置时才提及配置文件——刚刚输入
--lang en
的用户不需要被告知如何覆盖他们已设置的偏好：
将使用英语生成笔记（默认设置）。如需更改，请修改
~/take-notes/config.json
中的
"language"
字段。
如果来源内容的语言与你确定的语言不同，也需要说明——西班牙语视频自动生成英语笔记是唯一需要特别指出的意外情况：
来源内容为西班牙语；根据你的配置，将使用英语生成笔记。

When the config says 
"ask"

当配置文件设置为
"ask"
时

Ask once, with 
AskUserQuestion
, before writing anything. Offer exactly two options — English and Spanish — nothing else. Put the source's own language first, labelled "(Recommended)" (e.g. a Spanish-language video → 
Spanish (Recommended)
before 
English
); if the source is in neither, put English first.
However it resolves, the result sets the language for Step 4's headings and prose, and the 
--lang
code for Step 5 (
en
or 
es
).
在生成任何内容前，使用
AskUserQuestion
提问一次。仅提供两个选项——英语和西班牙语——无其他选项。将来源自身的语言放在前面，并标注“(推荐)”（例如，西班牙语视频 → 
西班牙语(推荐)
在前，
英语
在后）；如果来源语言既不是英语也不是西班牙语，则将英语放在前面。
无论结果如何，该结果将决定步骤4中标题和正文的语言，以及步骤5中的
--lang
参数值（
en
或
es
）。

Tags

标签

tags
in the same file is a closed vocabulary, curated by hand. Pick from it; do not extend it:
  1. One primary tag — the single best fit for what this source is about. That is what the gallery card shows and files the note under.
  2. Optional extras, only when they genuinely apply. Two is usually plenty; tagging a note with half the vocabulary makes every filter useless.
  3. Never invent a tag. A name that is not in the list is not an option, no matter how well it fits.
  4. Nothing fits, or 
    tags
    is absent, empty, or unreadable → 
    Unknown
    .     Silently. Do not ask, do not suggest a new tag, do not explain the fallback.
Say which primary tag you chose in the same short line as the language, without justifying it: Writing in English (default), filed under Engineering.
同一文件中的
tags
是封闭词汇表，需手动维护。仅从该词汇表中选择标签；不要扩展词汇表：
  1. 一个主标签——最匹配来源主题的单个标签。这是笔记画廊卡片显示的标签，也是笔记归档的分类。
  2. 可选的额外标签——仅当确实适用时添加。通常最多添加两个；为笔记添加一半词汇表中的标签会使所有过滤操作失效。
  3. 绝不要创建新标签。无论某个名称多么匹配，只要不在列表中，就不能作为选项。
  4. 无匹配标签，或
    tags
    字段不存在、为空或不可读 → 使用
    Unknown
    标签    。无需提示、无需建议新标签、无需解释默认标签。
在说明语言的同一句话中说明你选择的主标签，无需解释原因：将使用英语生成笔记（默认设置），归档至Engineering标签下。

Step 3 — read for teaching, not for summarising

步骤3 — 为教学而读取，而非为总结而读取

Before writing, decide: what does someone who consumed this source now know that they didn't before? That answer is the takeaway, and everything else supports it. Note where the source explains a mechanism (goes in How it works), defines jargon (Concepts), or leaves something unresolved (Going deeper).
With several sources, read them against each other before writing — that comparison is the whole reason they were combined:
  • Overlap — write it once, from whichever source explains it better. A deck bullet and the sentence spoken over it are one point, not two.
  • Gaps — a figure that is on a slide and in no transcript, a number said out loud that is on no slide. These are what the second source bought.
  • Contradictions — say so and attribute both. A talk that updates its own deck is worth a line in Going deeper.
Never organise the notes by source. One set of sections, ordered by what has to be understood first; a reader should not be able to tell where the seam was.
生成笔记前，先确定：消费该来源内容的人现在会学到哪些之前不知道的知识？答案就是核心要点，其他所有内容都为其提供支持。标记来源中解释机制的部分（放入工作原理）、定义术语的部分（放入核心概念）或未解决问题的部分（放入深入探索）。
对于多个来源，在生成笔记前对比阅读——这种对比正是整合多个来源的核心价值：
  • 重叠内容——仅写一次，选择解释更清晰的来源内容。幻灯片中的要点和演讲中对应的句子视为一个要点，而非两个。
  • 补充内容——幻灯片中有但转录文本中没有的图表、演讲中提到但幻灯片中没有的数字。这些是第二个来源带来的价值。
  • 矛盾内容——注明矛盾并分别引用两个来源。演讲内容更新了幻灯片内容的情况值得在深入探索部分添加一行说明。
绝不要按来源组织笔记。使用统一的章节结构，按理解顺序排列；读者不应能看出内容的来源分界。

Step 4 — write the notes as HTML

步骤4 — 将笔记生成为HTML

Use the sections below. Write body HTML only — no 
<html>
, 
<head>
, 
<body>
, no 
<h1>
, and no metadata line: the renderer supplies the document shell and the masthead from the fields you collected in Step 1.
There is no Markdown step. Emit the tags directly; nothing parses Markdown here, which is why this skill needs no conversion dependency.
使用以下章节结构。仅编写正文HTML——无需
<html>
、
<head>
、
<body>
标签，无需
<h1>
标签，无需元数据行：渲染器会从你在步骤1中收集的字段中生成文档框架和页眉。
无需经过Markdown转换步骤。直接输出HTML标签；此处不解析Markdown，因此本技能无需转换依赖。

Step 5 — render it

步骤5 — 渲染笔记

Pipe the body HTML to the renderer, filling the flags from your Step 1 fields:
bash
uv run "${SKILL_DIR}/scripts/render.py" \
  --title "<title>" --byline "<channel or author>" \
  --span "<duration or publication date>" --url "<canonical URL>" \
  --tag "<primary tag>" <<'HTML'
<h2>Executive summary</h2>
...
HTML
Pass one 
--tag
per tag chosen in Step 2, primary first — 
--tag AI --tag Engineering
. With no 
--tag
at all the note is filed under 
Unknown
.
The masthead flags describe the primary source. When the run combined several, add one 
--source "<label>" "<url>"
per companion, in the order they were given:
bash
--source "Slides" "https://docs.google.com/presentation/d/<DECK_ID>/edit"
They render as a short muted list under the source link. The label names the kind of source — 
Slides
, 
Paper
, 
Repo
, 
Video
, 
Article
— in the note's own language; the title is already the 
<h1>
, and repeating it there tells the reader nothing. A companion the run failed to fetch gets no 
--source
entry: the rail lists what the notes were written from.
For video sources, also pass whichever of 
--video-id <id>
, 
--thumbnail <url>
, 
--channel-url <url>
, 
--published <YYYYMMDD>
, 
--views <int>
, 
--duration <seconds>
the guide reported. 
--video-id
is what switches the rail to a poster + index; without it, the same two-pane layout renders for articles instead, with a byline kicker and a numbered index in place of the poster and timestamps.
For videos, pass raw values and let the renderer localise them: 
--duration 692
(seconds), 
--published 20260816
, 
--views 13232
. It writes 
11 min · 16 ago 2026 · 13.2K visualizaciones
for 
--lang es
and 
11 min · Aug 16, 2026 · 13.2K views
for 
--lang en
. 
--span
stays a free-form string for articles, whose span is a publication date rather than a length.
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 file rather than adding a near-duplicate; the script prints 
created:
or 
updated:
with the path. Report that path.
That is also how a note gets re-tagged: while the body is still in context, re-run this command with a different 
--tag
. Rewriting the tag inside an already-written file is not something this skill does — re-run the source.
Pass 
--lang
matching Step 2's choice (
en
or 
es
). Add 
--no-open
to skip the browser, 
--out-dir
to write somewhere other than 
~/take-notes/html_reports
.
将正文HTML传递给渲染器，使用步骤1中收集的字段填充参数：
bash
uv run "${SKILL_DIR}/scripts/render.py" \
  --title "<title>" --byline "<频道或作者>" \
  --span "<时长或发布日期>" --url "<标准URL>" \
  --tag "<主标签>" <<'HTML'
<h2>执行摘要</h2>
...
HTML
为步骤2中选择的每个标签传递一个
--tag
参数，主标签在前——例如
--tag AI --tag Engineering
。如果未传递任何
--tag
参数，笔记将归档至
Unknown
标签下。
页眉参数描述主来源。当操作整合了多个来源时，为每个辅助来源添加一个
--source "<标签>" "<url>"
参数，按用户提供的顺序排列：
bash
--source "Slides" "https://docs.google.com/presentation/d/<DECK_ID>/edit"
这些参数会在来源链接下方渲染为一个简短的灰色列表。标签用于说明辅助来源的类型——
Slides
（幻灯片）、
Paper
（论文）、
Repo
（仓库）、
Video
（视频）、
Article
（文章）——使用笔记的语言；标题已作为
<h1>
显示，重复标题对读者毫无意义。无法获取内容的辅助来源无需添加
--source
参数：归档栏仅列出笔记内容的来源。
对于视频来源，还需传递指南报告的以下参数：
--video-id <id>
、
--thumbnail <url>
、
--channel-url <url>
、
--published <YYYYMMDD>
、
--views <int>
、
--duration <seconds>
。
--video-id
用于将归档栏切换为海报+索引模式；若无该参数，双栏布局会渲染为文章式，用署名提示和编号索引替代海报和时间戳。
对于视频来源，传递原始值，由渲染器进行本地化处理：例如
--duration 692
（秒）、
--published 20260816
、
--views 13232
。对于
--lang es
，渲染器会显示为
11 min · 16 ago 2026 · 13.2K visualizaciones
；对于
--lang en
，会显示为
11 min · Aug 16, 2026 · 13.2K views
。
--span
参数对于文章来源仍为自由格式字符串，因为文章的时间信息是发布日期而非时长。
渲染器会将笔记写入
~/take-notes/html_reports/YYYY-MM-DD-<slug>.html
并在浏览器中打开。同一天对同一来源重新执行操作会更新该文件，而非生成近似重复的文件；脚本会输出
created:
或
updated:
及文件路径。报告该文件路径。
这也是为笔记重新添加标签的方式：当正文内容仍在上下文环境中时，使用不同的
--tag
参数重新执行该命令。本技能不支持直接编辑已生成文件中的标签——需重新对来源执行操作。
传递与步骤2中选择的语言匹配的
--lang
参数（
en
或
es
）。添加
--no-open
参数可跳过在浏览器中打开的步骤，添加
--out-dir
参数可将笔记写入
~/take-notes/html_reports
以外的目录。

Sections

章节结构

Mandatory, in this order. The title and metadata line are not in the body — they come from the renderer flags.
  1. <h2>Executive summary</h2>
    — 3–5 sentences: what the source covers and what it argues.
  2. <h2>The one takeaway</h2>
    — 1–2 sentences wrapped in 
    <strong>
    . The single most important insight. If you can't name one, the notes aren't ready.
  3. <h2>Key points</h2>
    — a 
    <ul>
    of 5–10 items, each 
    <li><strong>Claim</strong> — the detail that supports it</li>
    . Cap at 10; more than that is a transcript with bullets in front of it.
  4. The outline, rendered to match the source:
    • video → 
      <h2>Timestamped outline</h2>
      , one 
      <li>
      per topic: 
      <li><a href="https://youtu.be/<ID>?t=754s">12:34</a> — <strong>Topic</strong> — one-line summary</li>
      Use absolute 
      ?t=<seconds>s
      URLs so the links jump to the right moment.
    • article → 
      <h2>Section outline</h2>
      , one 
      <li>
      per section: 
      <li><strong>Section heading</strong> — one-line summary</li>
      , wrapping the heading in 
      <a href="<URL>#anchor">
      when the page has stable anchors.
    Aim for 6–15 entries either way; group adjacent material covering one idea.
    The outline follows the primary source only — it is one source's spine, and interleaving two makes it navigate neither. A companion stays traceable through inline deep links wherever a point comes from it: a slide's 
    <a href="<deck URL>#slide=id.<PAGE_ID>">
    , a video's 
    ?t=<seconds>s
    .
Optional — include only when the source actually earns it, never as an empty heading:
  • <h2>Concepts</h2>
    — jargon the source assumes or introduces, as 
    <li><strong>term</strong> — definition</li>
    . Include a term only if not knowing it blocks understanding the notes.
  • <h2>How it works</h2>
    — an 
    <ol>
    for a mechanism, pipeline, or worked example the source demonstrates. Code goes in 
    <pre><code>
    .
  • <h2>Going deeper</h2>
    — what the source leaves open: unanswered questions, claims made without evidence, and the concrete next thing to read or try.
Source figures — 
web.md
and 
arxiv.md
return the diagrams, charts, and screenshots the page carried; 
slides.md
returns an image URL for every slide. Include one only when it is load-bearing — the diagram is the explanation, the chart is the evidence — never a decorative photo, a header banner, an author headshot, or (for a deck) a slide that is just bullets you already wrote out. Cap at 3, the same "more than that is a dump" discipline as Key Points. Not a section of its own: place 
<figure><img src="<url>" alt="<alt text>"><figcaption>caption</figcaption></figure>
inline, in whichever section it supports — most often How it works, Key points, or Concepts. Each guide says how to confirm the URL really serves an image before you embed it; a broken-image icon teaches nothing.
以下章节为必填项，按顺序排列。标题和元数据行不属于正文——它们来自渲染器参数。
  1. <h2>执行摘要</h2>
    — 3-5句话：说明来源内容涵盖的范围及核心论点。
  2. <h2>核心要点</h2>
    — 1-2句话，用
    <strong>
    包裹。这是最重要的见解。如果无法确定核心要点，说明笔记尚未准备好。
  3. <h2>关键要点</h2>
    — 一个
    <ul>
    列表，包含5-10个条目，每个条目格式为
    <li><strong>主张</strong> — 支持该主张的细节</li>
    。最多10个条目；超过10个就变成了带项目符号的转录内容。
  4. 与来源匹配的大纲：
    • 视频 → 
      <h2>带时间戳的大纲</h2>
      ，每个主题对应一个
      <li>
      条目： 
      <li><a href="https://youtu.be/<ID>?t=754s">12:34</a> — <strong>主题</strong> — 一句话摘要</li>
      使用带
      ?t=<seconds>s
      的绝对URL，以便链接跳转到对应时间点。
    • 文章 → 
      <h2>章节大纲</h2>
      ，每个章节对应一个
      <li>
      条目： 
      <li><strong>章节标题</strong> — 一句话摘要</li>
      ，当页面有稳定锚点时，将标题包裹在
      <a href="<URL>#anchor">
      中。
    无论哪种类型，目标是6-15个条目；将相邻的同一主题内容合并。
    大纲仅遵循主来源——它是单个来源的框架，混合两个来源的框架会导致无法导航。辅助来源的内容可通过内联深度链接追溯：幻灯片的
    <a href="<幻灯片URL>#slide=id.<PAGE_ID>">
    、视频的
    ?t=<seconds>s
    链接。
可选章节——仅当来源内容确实需要时才添加，绝不要添加空标题：
  • <h2>核心概念</h2>
    — 来源中假设读者已知或新引入的术语，格式为
    <li><strong>术语</strong> — 定义</li>
    。仅包含不了解就无法理解笔记的术语。
  • <h2>工作原理</h2>
    — 来源演示的机制、流程或示例，用
    <ol>
    列表呈现。代码放入
    <pre><code>
    标签中。
  • <h2>深入探索</h2>
    — 来源未解决的问题：未解答的疑问、无证据支持的主张，以及具体的后续阅读或尝试方向。
来源配图 — 
web.md
和
arxiv.md
会返回页面中的图表、截图；
slides.md
会返回每张幻灯片的图片URL。仅当配图是核心内容时才添加——图表本身就是解释、图表本身就是证据——绝不要添加装饰性照片、页眉横幅、作者头像或（对于幻灯片）仅包含已写入笔记的要点的幻灯片。最多添加3张，与关键要点的原则相同：超过3张就变成了内容堆砌。配图无需单独成章：将
<figure><img src="<url>" alt="<替代文本>"><figcaption>说明文字</figcaption></figure>
嵌入到对应的章节中——最常见的是工作原理、关键要点或核心概念章节。每个指南说明了如何在嵌入前确认URL确实指向图片；无法加载的图片毫无教学价值。

Rules

规则

  • Didactic means explaining, not compressing. A bullet only someone who already consumed the source would understand has failed. Expand the reference; don't preserve the author's shorthand.
  • Learner's order, not source order. Only the outline follows the source's sequence. Everything else is ordered by what has to be understood first.
  • Quote sparingly — one or two lines that lose meaning when paraphrased.
  • Own the notes. No "the speaker says that…" throughout; state the content and attribute only genuinely contested claims.
  • No padding. No "In conclusion", no restating the summary at the end, no bullet whose content is "this is important".
  • Flag the source's limits when it asserts things without support — that belongs in Going deeper, and it's the part that makes the notes worth keeping.
  • Language: write headings and body in whichever of English or Spanish was chosen in Step 2; the structure doesn't change. Pass the matching 
    --lang
    (
    en
    or 
    es
    ) to the renderer.
  • Keep the HTML plain: headings, paragraphs, lists, 
    <strong>
    , 
    <em>
    , links, 
    <pre><code>
    , 
    <blockquote>
    , simple tables, and (every source but video) 
    <figure><img><figcaption>
    for a source figure. No inline 
    style
    attributes, no 
    <script>
    , no classes — the stylesheet already handles presentation, and a note that fights it will look wrong in dark mode.
  • Escape what you write: 
    &
    , 
    <
    and 
    >
    must be 
    &amp;
    , 
    &lt;
    , 
    &gt;
    — in prose, in code samples, and in attribute values like an 
    <img src>
    URL (image URLs routinely contain an unescaped 
    &
    in their query string). The renderer escapes the masthead fields but passes the body through untouched.
  • 教学式意味着解释，而非压缩。只有已消费过来源内容的人才能理解的项目符号是失败的。扩展引用内容；不要保留作者的简写。
  • 按学习者的理解顺序排列，而非来源内容的顺序。仅大纲遵循来源内容的顺序。其他所有内容均按理解优先级排列。
  • 谨慎引用——仅引用1-2句改写后会丢失含义的内容。
  • 主导笔记内容。不要通篇使用“演讲者说……”；直接陈述内容，仅对存在争议的主张注明来源。
  • 不要冗余。不要添加“结论”、不要在结尾重复摘要、不要添加内容为“这很重要”的项目符号。
  • 标注来源的局限性——当来源提出无支持的主张时，放入深入探索部分，这是笔记值得保留的原因之一。
  • 语言：标题和正文使用步骤2中选择的英语或西班牙语；结构保持不变。向渲染器传递匹配的
    --lang
    参数（
    en
    或
    es
    ）。
  • 保持HTML简洁：仅使用标题、段落、列表、
    <strong>
    、
    <em>
    、链接、
    <pre><code>
    、
    <blockquote>
    、简单表格，以及（除视频外的所有来源）用于来源配图的
    <figure><img><figcaption>
    标签。不要使用内联
    style
    属性、
    <script>
    标签或类——样式表已处理所有展示效果，与样式表冲突的笔记在深色模式下会显示异常。
  • 转义内容：
    &
    、
    <
    和
    >
    必须转义为
    &amp;
    、
    &lt;
    、
    &gt;
    ——包括正文、代码示例和
    <img src>
    等属性值（图片URL的查询字符串中通常包含未转义的
    &
    ）。渲染器会转义页眉字段，但会直接传递正文内容。

Related

相关技能

  • /yt-watch
    — frames and transcript. Use it directly when the question is visual. 
    /take-notes
    includes its own copy of the transcript path so it runs standalone; neither skill depends on the other being installed.
  • /notion-summarize-blog
    — files a short webpage summary straight into the personal Notion database via MCP. 
    /take-notes
    is the long form and stays local: a full study page in 
    ~/take-notes/html_reports/
    , reviewed and edited before anything is worth filing.
  • /yt-watch
    — 生成视频帧和转录文本。当问题涉及视觉内容时直接使用该技能。
    /take-notes
    包含自己的转录路径，因此可独立运行；两个技能互不依赖。
  • /notion-summarize-blog
    — 将简短的网页摘要直接通过MCP存入个人Notion数据库。
    /take-notes
    是长格式工具，且仅在本地运行：在
    ~/take-notes/html_reports/
    目录下生成完整的学习页面，值得归档前可进行审阅和编辑。