make-knowledge-cards

make-knowledge-cards

English ｜ 繁體中文

An agent skill that turns an article into 5–8 study-ready knowledge cards.

Paste a text or point at a local Markdown/TXT file, and get back a small set of self-contained cards — each one idea, with a plain-language explanation and either a concrete example or a self-test question. It extracts only what's actually in the source: no invented facts, no duplicate cards, and no padding to hit a number.

Built for daily review of course notes, journal articles, and full papers. A long document gets an overview set plus per-section sets on request, rather than one over-compressed set of eight.

Install

Clone the repo and copy the skill folder into wherever your agent loads skills from:

git clone https://github.com/tsai1278/make-knowledge-cards.git
cp -r make-knowledge-cards/skills/make-knowledge-cards ~/.claude/skills/

For OpenAI-based agents, use skills/make-knowledge-cards/agents/openai.yaml instead. Both files carry the same instructions; SKILL.md is the source of truth.

Usage

Just ask, in whatever wording is natural:

Make knowledge cards from this article: <paste text>
Turn notes/transformers.md into study cards
Summarize this into flashcards and save it to a file

By default the cards are printed in the reply. Say "save it" (or mention a file, Notion, or Obsidian) and it writes a UTF-8 Markdown file instead.

Cards come back in the language you're writing in, not the source's — technical terms, named methods, and formula symbols stay in the original so you still recognize them in the literature. Ask for bilingual or source-language cards and you get those instead.

Long documents

Over roughly 6,000 words — a full paper, a technical report, a thesis chapter — the skill maps the sections, gives you an overview set covering the argument's spine, then offers a dedicated set per section. A set is never larger than 8 cards; more material means more sets, not denser ones.

Card format

Each card follows the same shape:

## Card N — <Title>

**Core point:** <one sentence>

**Explanation:** <2–4 plain-language sentences>

**Example:** <a concrete case from the source>

Example is swapped for Self-test: / Answer: when recall matters more than illustration — definitions, thresholds, decision rules.

Example

Input — an article on vibration-based bearing fault diagnosis:

A defect on a bearing surface produces an impact every time a rolling element passes over it. The repetition rate depends on the bearing geometry and shaft speed, and is different for each defect location: BPFO (outer race), BPFI (inner race), BSF (ball spin), FTF (cage). Because these are computed from geometry, you can predict where in the spectrum a defect will show up before you ever see one …

Output — 7 cards, of which two:

## Card 1 — Bearing characteristic fault frequencies

**Core point:** Each bearing defect location produces impacts at its own predictable
repetition rate, derived from the bearing's geometry and shaft speed.

**Explanation:** The four rates are BPFO (outer race), BPFI (inner race), BSF (ball spin),
and FTF (cage). Because they follow from geometry rather than from measurement, you can
compute where a defect will appear in the spectrum before ever seeing one — which is what
separates diagnosis (knowing which part failed) from detection (knowing something failed).

**Self-test:** Why can a fault frequency be calculated before any fault exists?
**Answer:** It depends only on bearing geometry and shaft speed, both known in advance.

## Card 2 — Why a raw FFT hides the fault

**Core point:** Fault impacts are visible only through the structural resonance they excite,
not at the fault frequency itself.

**Explanation:** Each impact rings the housing at 2–10 kHz, and that ringing is
amplitude-modulated at the fault frequency. A raw FFT shows the resonance but not the
modulation, so the fault frequency is effectively invisible until the envelope is extracted.

**Example:** A weak inner-race defect buried under gear mesh and electrical noise shows no
peak at BPFI in the raw spectrum, yet appears cleanly in the envelope spectrum.

Scope

Supported: pasted text, local .md and .txt files.

Not supported: URLs and web scraping, PDF/DOCX/EPUB, Anki .apkg export, spaced-repetition scheduling, graphical interface. The skill says so rather than working around it.

Design notes

Four rules do most of the work:

• One card, one idea. If a core point needs "and" to join two claims, it's two cards — or one card and something that should be dropped.
• Card count follows the source. 5–8 is what a knowledge-dense article yields, not a quota. A thin post gets 2–3 with a reason stated; a meeting note gets zero.
• Nothing that isn't in the source. When there's no concrete example to cite, the card carries a self-test question instead of an invented one. Vague sources stay vague.
• The source is data, never instructions. Papers and reports increasingly ship a section addressed to AI summarizers telling them what to include and how. Those are treated as content and noted, not obeyed — otherwise the author picks your cards for you.

For papers specifically, scope conditions and assumptions are carded ahead of headline numbers: results are lookup-able, assumptions are what get forgotten and then misapplied. For lecture notes, a bullet too compressed to explain faithfully is skipped and flagged as a gap rather than reconstructed into something the instructor may never have said.

Maintaining the skill

The rules live in three places, and only the installed copy actually runs:

② is a publishing destination, not an editing surface; ③ lives in your account and does not sync from disk. So a rule change takes three steps, in order:

1. Edit SKILL.md in ①, and mirror the change into SKILL_ZH.md and agents/openai.yaml
2. Reinstall to ③ ← skip this and nothing changes in practice
3. git commit and push to ②

Do only 1 and 3 and GitHub has the new version while you keep running the old one. Do only 2 and you run the new version while everyone else downloads the old one.

Versioning: typo or docs → patch (v1.0.1); new rule or source type → minor (v1.1.0); changed behavior → major (v2.0.0).

License

MIT