Make Knowledge Cards

---
name: make-knowledge-cards
description: Convert a pasted article or a local Markdown/TXT file into up to 128 knowledge cards, each carrying exactly one idea with a title, the core knowledge, a plain explanation, and either a concrete example drawn from the source or a self-test question. This skill should be used when the user asks to turn an article, blog post, report, documentation, or reading notes into knowledge cards, flashcards, 知识卡片, 读书卡片, or asks to "make cards out of this article", "做成一组卡片", "生成知识卡". Applies to text pasted in the conversation and to .md or .txt files on disk. Long sources are split into themed batches so no single reply is overwhelming. It does not fetch web pages, does not process PDF or office documents, and does not write .apkg or flashcard-app files itself — the repository's bundled GUI handles Anki/JSON/Obsidian export and spaced review. It does not build graphical interfaces.
---

# Make Knowledge Cards

## Overview

Turn one source text into a small deck of knowledge cards. Each card carries exactly one idea, states only what the source supports, and is self-verifying through an example or a self-test question.

The hard part is not formatting. It is selection: deciding what is worth remembering, and refusing to invent what the source does not contain. **The deck length follows the source.** A long chapter may fill 128 cards; a short note may yield 2. Never add a card to make the deck look complete, and never split one idea to fill a quota.

## Scope

**In scope**

- Text pasted directly into the conversation
- Local `.md` / `.markdown` / `.txt` files the user points to
- Deciding what to keep, how to split it, and in what order to present it

**Out of scope** — name the unsupported part and stop; do not improvise a workaround

- Web page fetching or URL scraping
- PDF, DOCX, XLSX, PPTX, image, or audio input
- Writing `.apkg` files or flashcard-app import files. **This skill outputs Markdown only.** When the user wants Anki, JSON, or Obsidian output, say that the bundled GUI does it: the same cards can be exported from the local app without regenerating them. Do not hand-roll a CSV or `.apkg` in chat output.
- Graphical interfaces, web pages, or interactive apps

When the input is out of scope, name the limitation and ask the user to paste the text or point to a Markdown/TXT file instead.

## What Counts as a Knowledge Point

A candidate qualifies only if it can be **disputed on its own** — a reader could point at the source and say "that part is wrong." This admits claims, mechanisms, procedures, rules, and hard numbers. It excludes:

| Source element | Card-eligible | Why |
|---|---|---|
| A stated fact, mechanism, rule, or figure | Yes | Can be checked against the source |
| A conclusion the source argues for | Yes | Same test as any claim |
| A plan, to-do, or intention ("next week we will add...") | No | Nothing is asserted yet, so nothing can be disputed |
| An open question with no answer in the source | No | Same reason |
| A promise or forecast about the future | No | Not yet true or false |
| Author framing, transitions, background padding | No | Carries no information |

Plans and open questions are not dropped silently. Mention them in the footer's `未收录 / Omitted` line so the reader knows they were seen and why they produced no card.

## Workflow

### Step 1: Obtain the source and judge whether it qualifies

If the user pasted the text, use it. If the user gave a file path, read it with the Read tool; if the path does not exist, ask rather than guessing. Read long files in full before selecting — never choose cards from a partial read.

If the user described an article but did not provide it, ask for the text. Do not generate cards from a description of an article.

Then check two things before selecting anything:

1. **Is there at least one disputable claim?** If the source is only plans and open questions, say so, produce no cards, and ask for material with actual content.
2. **Does the source carry its own disclaimers?** Fiction markers ("this article is fictional"), "data as of" notices, "for reference only" lines, and sourcing notes must survive into the output. Do not drop them as scaffolding — a deck stripped of its disclaimer reads as fact.

When a disclaimer exists, it applies to **every card that carries any figure or named entity from the source**. Cards carrying only mechanism or terminology do not need it. Put it in each qualifying card's Caveat field as the caveat's first sentence, and repeat it verbatim in the footer's disclaimer line.

### Step 2: Survey before selecting

Read the whole source once and build an internal candidate list. This list is a working note for Step 2 rules and Step 5 — it is **not** part of the delivered output. For each candidate record:

- Where it appears (heading or paragraph)
- Its type: claim, mechanism, procedure, rule, number, or anecdote
- Whether it repeats an earlier candidate
- Whether the source's own disclaimer qualifies it

Then pick the candidates worth cards, using these rules **in this order**:

1. **Load-bearing first.** Claims the rest of the source depends on: definitions, core mechanisms, stated conclusions, rules the source operates by.
2. **Consequences over trivia.** What changes if the reader acts on this.
3. **Specific over general.** A concrete number, mechanism, or procedure beats a vague summary sentence.
4. **Drop the scaffolding.** Skip author framing, transitions, background padding, and self-promotion unless they carry content themselves. Keep the source's disclaimers — see Step 1.
5. **Merge duplicates.** See the merge test below.

Rule 1 is a filter, rules 2 and 3 rank within what survives it. A candidate is **strong** when rule 1 or rule 2 keeps it and rule 3 finds something concrete in it. When two strong candidates tie, break the tie in this order:

1. Prefer the one other candidates depend on.
2. Prefer the one the source itself flags as a conclusion or a rule.
3. Prefer the one carrying more of the source's own specific figures or conditions.
4. If still tied, keep the earlier one in source order and list the other in the footer's Omitted line.

**The merge test.** Two candidates are one card when either holds:

- They restate the same claim, even in different words.
- One is meaningless without the other's sentence to make sense of it.

Two candidates that **share a sentence but each carry a payload the other lacks** stay as two cards. Shared material may appear in both, unexpanded; each card states only its own payload. If either card has no payload of its own after the split, they must merge.

**The payload test.** Whether a payload is "independent enough" to justify its own card is decided by one question: **could a reader dispute this claim on its own, without also disputing the other?** Apply it in this order:

1. If the second claim would be false whenever the first is false, they are one card. (A mechanism and its stated consequence are one card; a rule and its justification are one card.)
2. If the second claim stands even if the first were removed, it is its own card. (Two independent reasons for the same conclusion are two cards; two different figures in one sentence are two cards.)
3. A figure that only quantifies the first claim ("60% of the cache") stays inside the first card. It is a payload, not a separate card.

A large ceiling does not relax this test. Splitting is warranted by the source, never by spare room.

**Enumerations.** A list under one sentence ("three numbers decide...", "the causes are A, B, and C") splits into separate candidates — each item is independently disputable. Keep it as one card only when no item stands on its own without the others, such as a rule whose parts define each other.

### Step 3: Set the card count and batching

The ceiling is **128 cards total**. There is no floor and no quota. Count only the candidates that passed the Step 2 rules, then place them:

- **128 or fewer strong candidates** — one card each, nothing omitted. How the deck is *delivered* depends on how many cards that is: see the table below.
- **More than 128 strong candidates** — see long-source batching below.

Then set the delivery shape, because a 100-card deck dumped into one reply is unreadable. The thresholds below are exact, not approximate:

| Total cards | Delivery |
|---|---|
| 1 to 25 | One deck, no batching |
| 26 to 60 | One deck, but grouped under the source's own section headings |
| 61 to 128 | **Themed batches.** Split by the source's own sections or topic boundaries, deliver each batch as its own titled group with continuous card numbering across batches |

When batching, tell the reader up front how many cards the source yields and how many batches to expect, then deliver the batches in source order. Never truncate a batch to save space — finish the current batch and continue in the next reply if the user keeps reading.

**Long-source batching.** When a source yields more than 128 cards:

1. Split at the source's own section boundaries first. A section that does not fit whole goes into the next batch at an internal topic boundary.
2. Keep card numbering continuous across batches (`卡片 1 / Card 1` through `卡片 128 / Card 128`). Batches are transport, not separate decks — the whole output is one deck that arrives in pieces.
3. Deliver batches in order, and state after each batch which one comes next.
4. After the final batch, emit the footer once.

**0 candidates** — produce no cards. Say the source contains only plans or open questions and ask for material with actual content.

Never invent a card to reach any number. A fabricated card is a worse failure than a short deck.

### Step 4: Write each card

A card has four required fields and one conditional field, in this order:

```markdown
### 卡片 N / Card N. <specific title>

**核心知识 / Core knowledge**
<One to three sentences. The claim itself, with the source's own numbers, names, and conditions.>

**简明解释 / Plain explanation**
<Two to four sentences, or fewer when the source supports no more. Unpack the mechanism or define terms the core knowledge uses. No new facts.>

**口径提示 / Caveat** *(optional, only when needed)*
<Source contradictions, inconsistent measurement scope, or the source's own uncertainty. Omit the field entirely when there is nothing to flag.>

**例子 / Example** *or* **自测题 / Self-test** *(exactly one)*
<Example: a case, code snippet, log line, command, or worked calculation taken from the source.>
<Self-test: a question answerable from this card alone, answer on the next line.>
```

**Card grammar**

- `### 卡片 N / Card N.` — keep the bilingual prefix so numbering is scannable across languages.
- Field labels stay bilingual in every language.
- Use the self-test answer prefix `Answer:` for English cards and `答案：` for Chinese cards.
- The Caveat field is the only sanctioned place for contradiction flags. When a source disagrees with itself, keep both statements and put the disagreement here — never reconcile them silently.

**Field rules**

- **Title** names the specific idea ("Cold start kills collaborative filtering"), not the topic area ("Recommendation systems").
- **Core knowledge** is testable on its own: a reader who disputes it can point at the source sentence. Keep it to the source's own facts. Keep the source's own time references ("上周", "today") rather than converting them to calendar dates, unless the source supplies the date. Identifiers, error codes, and commands that belong inside the claim appear here as inline code — see the artifact rule below for when an artifact moves to the Example slot instead.
- **Plain explanation** unpacks the mechanism; it never restates the core knowledge in different words. Readability means the reader can follow the reasoning, not that they master every term — see the term rule below.
- **Caveat** appears only when needed. Use it for source-internal disagreement, mismatched measurement scope, or an unresolved alternative the source leaves open.
- **Example** and **Self-test** are mutually exclusive. One artifact per card. When the source offers both a snippet and a question, keep the snippet and drop the question.

**Where non-prose artifacts go**

Two placements, decided in this order:

1. **Default — Example**, as a fenced block, verbatim: code snippets, commands, config fragments, log lines, error messages, and figures that are themselves the clearest case.
2. **Core knowledge, inline code — only when the Example slot is already taken** by a snippet, or when the artifact is error/terminal output that appears immediately after the claim it proves and is what makes the claim checkable.

That order is absolute: check slot availability before choosing a placement. When both slots are free, the artifact goes to the Example. When the source's only concrete artifact is a code snippet, it is the Example and the card then has no self-test.

Compiler error codes and terminal output that prove a claim are the common case for placement 2 — they are evidence, not illustration.

**The term rule**

The source often does not define its own jargon. The test for whether a word is a term: a reader who knows the source's other content would still be blocked by this word. Apply the rule only to words that pass that test — ordinary words, and words the source itself defines or uses self-explanatorily, are left alone.

1. Ground it with the source's own usage — quote or paraphrase how the source uses the term elsewhere in the text, including a different section. A fact that exists in the source only to make this term usable is explanatory material for this card, not a card of its own.
2. If the source gives nothing, do not supply a textbook definition. Explain by unpacking the concrete facts the source does give. Close the explanation with the gap marker as its last sentence: "原文未定义 X，本卡只用它在原文中的具体表现" (or "The source does not define X; this card uses only how it shows up concretely"). When the source does supply enough to unpack, no marker is needed.
3. Reaching outside the source for a definition breaks the anti-fabrication rule and is not allowed, even when the definition is textbook-correct.

Readability is judged as "the reader can follow what this claim is doing," not "the reader could pass an exam on the jargon."

**Quoting figures from a merged or deferred candidate.** A candidate that got merged away may still have its figures quoted inside another card's explanation, under the same rules as any other source material — stated inline, not expanded, and never as a derived calculation. This is how a merged idea still reaches the reader. The same applies to a candidate deferred to a later batch: quote it where it belongs, not early in whichever batch happens to come first.

**Derived figures**

Arithmetic on the source's own figures is allowed, because a shown calculation is auditable:

- Permitted: sums, differences, ratios, percentages, and unit conversions over figures present in the source.
- Show the calculation inline (`1850 − 1540 = 310`).
- Not permitted: introducing a figure the source does not contain and extrapolating from it, or chaining calculations into an estimate the source never makes.

Derived figures belong in the Example field, never in the core knowledge.

### Step 5: Run the fidelity check

Before delivering, check each card against these. Any "no" means rewrite or cut the card; do not ship it.

1. Is every factual statement traceable to a specific line in the source?
2. Did any number, date, name, or causal claim appear that the source does not contain? (Derived figures shown with their calculation are exempt; see the rule above.)
3. Does the card cover one idea, or did two get fused?
4. Does another card say substantially the same thing — sharing a claim, not merely a topic?
5. Can a reader follow the reasoning in the plain explanation without the original article?
6. Does the Example or the self-test answer point back into this same card?
7. Did any term get a definition the source does not supply?
8. Did the source's disclaimer survive into the output?
9. If the deck is batched, is every batch present with continuous numbering and no duplicates across batches?

**Cutting a card.** When the core knowledge survives but the plain explanation cannot be written without inventing facts, do not pad and do not fabricate. Cut the card and lower the count, then note it in the footer. A deck of 4 honest cards beats a deck of 6 with 2 invented explanations.

**Checking a long deck.** For decks over 25 cards, do not rely on a single read-through. Verify in this order: count the cards (the numbering must be continuous and match the stated total), scan for duplicate claims across batches, then spot-check every card against items 1 and 2 above. A single sweep misses things at this length.

This check is an internal step. Do not show it to the user unless they ask.

### Step 6: Deliver

Output the cards in Markdown as rendered text, not wrapped in a code fence, with no extra top-level heading. Order them by the source's own section order; within one section, order by importance.

Follow with a footer of at most four lines:

```markdown
---
**卡片数 / Cards**: N
**来源 / Source**: <file name or "pasted text">
**未收录 / Omitted**: <ideas dropped as duplicates, and ideas deferred past the 128-card ceiling — name them; write "无" only when nothing was dropped at all>
**来源声明 / Source disclaimer**: <verbatim disclaimer — this line is included only when the source carries one, and is omitted entirely otherwise>
```

Write the footer in the card language. Omit the disclaimer line when there is no disclaimer; do not write 无. When the source is thin, say so in the `未收录` line. When the deck is batched, state the batch index in the `卡片数` line (`卡片数 / Cards`: 32 of 128, batch 2/4). Distinguish the two omission reasons when both apply:

```
**未收录 / Omitted**: 合并——C 与 D 讲同一机制，保留 C。超上限——E、F 未收录，因为候选超过 128 张。
```

## Anti-Fabrication Rules

Hard constraints, not preferences.

- **No outside knowledge.** Every fact comes from the source. Do not add the textbook explanation of a concept, real-world statistics, or names the source omitted. If the source is thin on a point, the card is thin.
- **No invented examples.** Examples come from the source, or are shown calculations over the source's figures.
- **No invented authority.** Do not attribute claims to researchers, standards bodies, or papers the source does not cite.
- **No reclassification.** Repackaging a plan, a to-do, or an open question as a card adds no false fact yet still inflates the deck. See the eligibility table.
- **No filling the count.** Short output with an honest note beats padded output.
- **Mark the gaps.** When something is missing, name it. Non-numeric gaps use the term rule's phrasing; numeric gaps use `原文未给出具体数值` / `The source gives no figure for this`.
- **Keep contradictions.** Two conflicting statements stay, with the conflict flagged in the Caveat field.
- **Keep disclaimers.** Fiction markers and sourcing notices reach the footer verbatim.

## Language

Match the source's language: a Chinese source produces Chinese cards, an English source produces English cards, a mixed source follows the majority language. Field labels stay bilingual in every case. The self-test answer prefix and the gap-marker phrases follow the card language, not the label language.

## Anti-Patterns

| Symptom | Cause | Fix |
|---|---|---|
| 8 cards, all vague | Vague candidates selected | Re-select from the Step 2 candidate list |
| Two cards covering one idea | Splitting happened before merging | Apply the merge test |
| One idea split across two cards to reach a number | The ceiling was treated as a target | Merge them; the ceiling never justifies a split |
| Examples with numbers absent from the source | A plausible case was invented | Delete it; use a self-test instead |
| Core knowledge is a specific number the source never states | A figure was extrapolated | Delete it, or show the calculation over source figures |
| Explanation restates the core knowledge | Paraphrase written instead of unpacking | Explain the mechanism or ground the term |
| A textbook definition appears in the explanation | Term rule ignored | Ground it in the source's own usage, or name the gap |
| Titles like "Introduction to X" | Topic instead of specific claim | Name the claim |
| "The author argues that..." framing | Scaffolding leaked in | State the knowledge directly |
| Plans and open questions became cards | Eligibility table ignored | Move them to the footer's Omitted line |
| Padding to reach a target number | Count treated as a quota | Cut to the real count and note it |
| One 100-card reply | The batching rule was skipped | Split at the source's section boundaries |
| Disclaimer dropped as scaffolding | Step 1 check skipped | Carry it into the footer verbatim |
| Disagreement silently resolved | Caveat field skipped | Keep both, flag in the Caveat field |