anki — flashcard generation skill

When invoked, follow this workflow exactly. Do not improvise structure — the value of the skill is in its discipline.

0. Prerequisites

• Anki Desktop must be running with the AnkiConnect add-on (port 8765). If python anki_connect.py version fails, stop and tell the user to start Anki Desktop.
• Custom note types Claude Cloze and Claude Basic and parent deck Claude must exist. If python anki_connect.py model_names does not include both, run python bootstrap.py first.

All paths in this file are relative to the skill directory: ~/.claude/skills/anki/.

1. Parse the user's request

Extract from the user's natural-language input:

• topic — the subject they want cards on. Usually present. (May be empty if the URL alone is the brief.)
• url (optional) — a URL anywhere in the prompt → triggers URL-grounded mode. If no URL, topic-only mode.
• deck_path_hint (optional) — phrases like "place inside of rust/functions", "in the rust deck", "under functions". Normalize to a path under Claude::....
• card_count (optional) — phrases like "10 cards", "give me 30", "~50", "comprehensive", "just 5". Default: 10.

2. Query Anki state

Run these read-only calls via the helper to gather context for generation:

python anki_connect.py deck_names    # existing decks
python anki_connect.py get_tags      # existing tags

If a deck_path_hint is given, normalize it to Claude::<...> form and check whether it exists in the deck list.

Query existing card fronts in the target deck for duplicate avoidance (only if the deck already exists):

python anki_connect.py find_notes 'deck:"Claude::Whatever"'
python anki_connect.py notes_info '[id1, id2, ...]'

Extract the Text (cloze) or Front (basic) fields — these are the existing_fronts you pass to the generation prompt.

3a. URL-grounded mode (if a URL is present)

Fetch the source

Use the WebFetch tool to retrieve the URL. Ask WebFetch for the page's full content with a prompt like "Return the complete article or paper content verbatim, including all sections, equations described in text, and any abstract/conclusion. Preserve exact wording for quotability."

If WebFetch returns very little content, or content that looks like a paywall/login wall/JS-only skeleton, stop and tell the user — surface what came back and ask whether to abort, retry, or fall back to topic-only mode using the URL as descriptive text.

Keep the returned text as source_text. You will need it twice: for generation, and again for verification.

Generate cards (Layer 1)

Read prompts/generate_url.md. Apply its instructions to produce a single JSON object. Inputs:

• topic: parsed from step 1 (may be empty)
• url: parsed from step 1
• source_text: from the WebFetch above
• card_count: parsed from step 1 (default 10)
• deck_path_hint: parsed from step 1
• existing_decks, existing_tags, existing_fronts: from step 2
• today: current ISO date

Do not call an external LLM API — you ARE the LLM. Produce the JSON in your own response, following the prompt's rules strictly.

Verify cards (Layer 3)

Read prompts/verify.md. Apply its instructions over the source and the generated cards. Inputs:

• source_text: same text used for generation
• cards: the cards array from Layer 1's output

Produce the verification JSON array. For each fail, drop that card from the set. Track the drops — you will surface them in the preview.

If more than 50% of cards failed verification, treat that as a signal the source was a bad fit. Surface a warning at preview and ask the user whether to proceed with the survivors or abort.

Tag policy (URL mode)

The orchestrator adds these tags to every URL-mode card:

• claude-generated
• source-mode-url

URL-mode cards do NOT get unverified-source.

3b. Topic-only mode (if no URL is present)

Read prompts/generate_topic.md. Apply its instructions to produce a single JSON object. Inputs:

• topic: parsed from step 1
• card_count: parsed from step 1 (default 10)
• deck_path_hint: parsed from step 1
• existing_decks, existing_tags, existing_fronts: from step 2
• today: current ISO date

No verification pass — there's no source to verify against.

Tag policy (topic mode)

The orchestrator adds these tags to every topic-mode card:

• claude-generated
• source-mode-topic
• unverified-source

4. Pre-commit checks

• If the user gave card_count > 50, warn that AnkiDroid's default new-card daily cap is 20 and confirm before proceeding.
• If the generation output's warnings array is non-empty, surface each warning at preview.
• In URL mode, if any cards were dropped by verification, surface the count and the reasons.

5. Preview

Show the user this format (replace <...> with real values):

Plan: <deck path> <(NEW) or (existing)>
Tags: <topic tags joined, with (NEW) flagged> + auto: <auto tags for this mode>
Count: <surviving N> cards (<cloze count> cloze, <basic count> basic)
Mode: <"url-grounded ✓ verified" or "topic-only ⚠ unverified-source">
<for URL mode>  Source: <url>
<for URL mode>  Verification: <P passed, F failed/dropped>

<any warnings, one per line, prefixed with "⚠ ">
<if URL mode and cards were dropped: list the drop reasons indented>

Sample (1 of <N>):
  <render card 1>

Sample (2 of <N>):
  <render card 2>

[y] commit  [n] discard  [a] show all  [r N] regenerate card #N  [d N N ...] drop cards N,N

Rendering rules:

• Cloze cards: show the Text field (with {{c1::...}} syntax visible) plus, in URL mode, a one-line Quote: "..." directly below.
• Basic cards: show Q: <Front> then A: <Back>, plus the quote line in URL mode.
• Flag any (NEW) deck or (NEW) tag so the user can catch typos before they proliferate.

6. Wait for the user's response

Handle these affordances:

• y / yes / commit → proceed to step 7.
• n / no / discard → stop; do not call AnkiConnect; tell the user nothing was committed.
• a / all → re-render preview with all cards visible, then re-show affordances and wait.
• r N → regenerate card #N. Ask one short clarifying question about what was wrong, then re-emit only that card (preserving Source URL, Source Quote rules in URL mode), slot it back, re-show preview.
• d N N N ... → drop those cards, renumber the rest, re-show preview.

Any unrecognized response: ask for clarification.

7. Commit

Once the user confirms with y:

1. Ensure deck exists. If deck_existed is false:

   python anki_connect.py create_deck "Claude::Whatever"

2. Build the notes payload. For each surviving card:

   {
     "deckName": "<the deck>",
     "modelName": "Claude Cloze" or "Claude Basic",
     "fields": <the card's fields>,
     "tags": [<topic tags>, ...<auto tags for this mode>],
     "options": {"allowDuplicate": False}
   }

3. Add the notes. Write the notes JSON to a temp .py script in the skill directory (handles Windows quoting cleanly), import anki_connect as ac, call ac.add_notes(notes), print the result, then delete the temp script. The return value is a list of note IDs with None for any failures (e.g., real duplicates Anki rejected).
4. Report results.
   • Added: <N> cards to <deck>
   • If any returned None: Skipped: <K> duplicates
   • In URL mode, also: Dropped at verification: <V> (already reported at preview, but worth restating in the final summary).
   • Sync: open AnkiDroid on your phone and pull-to-sync to see the cards.
5. Do not trigger AnkiWeb sync automatically. The user controls when sync happens. (The sync() helper exists if you ever want it explicitly.)

Deferred (NOT in this skill yet)

• Video sources (yt-dlp + Whisper)
• Audio sources (Whisper)
• PDF sources at URLs (need PDF text extraction; treat as out of scope until added — if WebFetch returns useless content for a PDF URL, surface that and offer topic-only fallback)
• Local file sources
• GitHub repo / codebase analysis
• /anki-fix regeneration mode