Anki Flashcards Skill

A Claude skill that makes it negligibly easy to create high-quality Anki flashcards. The goal is expert-level cards with minimal user effort.

Why This Exists

Spaced repetition is one of the most effective learning techniques we have. The research is clear: active recall with expanding intervals beats passive review for long-term retention. Anki is the gold standard tool for this.

But Anki has an adoption problem. The card-creation process is slow and requires expertise most people don't have. What makes a good flashcard? How do you break down complex topics? When should you use cloze deletions vs. basic cards? These questions stop people before they start.

This skill removes that bottleneck. A user can say "make me a vocab card for ephemeral" and get an expert-quality card in seconds, packaged and ready for Anki. The vision is that card quality and creation speed should never be the reason someone doesn't use spaced repetition.

Design Philosophy

Expert quality by default

Every card should be as good as what a spaced repetition expert would create. This means:

  • Atomic — One concept per card. No compound questions.
  • Precise — Questions have one unambiguous answer.
  • Self-contained — The answer makes sense without external context.
  • Right type — The card format matches the knowledge type (vocab → bidirectional, lists → cloze, etc.).

Minimal friction

The simplest path should be the default. A vocab card shouldn't require a preview cycle. Complex document extraction might, but simple requests should complete in one turn.

Token efficiency

The skill uses a router pattern: SKILL.md is ~100 lines that routes to specific workflows. Claude only reads what it needs. Artifacts are generated from templates, not written from scratch. Commands copy and combine pre-built components rather than regenerating them.

Preview as optional safety net

The preview system exists because cards often look wrong once you see them. But it's optional—quick flows skip it entirely, and users can always download without reviewing.

Card Types

The skill supports six card types, each designed for a specific kind of knowledge:

Type Use For Cards Generated
Front-Back Questions, procedures, cause-effect 1 card
Bidirectional Concept Vocabulary, terminology 2 cards (term↔definition)
Cloze Deletion Lists of 3+ items, sequences 1 card per cloze
Image Recognition Visual ID: landmarks, species, art 1 card
Image Occlusion Labeling diagrams, anatomy, maps 1 card per region
Person Names, faces, contact details 1 card per field

Core Flows

Quick Cards (Primary)

The most common flow. User requests a simple card, Claude generates it immediately.

User: "Make a vocab card for ephemeral"
Claude: Looks up definition → Generates JSON → Creates .apkg → Done

No preview, no feedback loop. One turn. The preview can be shown alongside the download for users who want to verify, but it's not required.

Preview Cycle (For Complex Cards)

For batches of 4+ cards or complex extractions, the preview cycle helps catch issues:

Draft cards → Show preview → User reviews → Apply edits → Export

The preview artifact lets users flip cards, mark issues, and export feedback JSON. This is optional but valuable for larger batches where mistakes compound.

Document Extraction (Future)

Not yet implemented. The vision: upload a document, get a proposed card breakdown, review and refine, export. This requires intermediate analysis steps that aren't built yet.

Technical Architecture

See the Architecture section for the full breakdown.

Getting Started

To work on this skill:

  1. Read this README to understand the goals
  2. Check the Roadmap for current priorities
  3. Review Procedures for how to make common changes
  4. Use Commands for token-efficient operations

Architecture

How the pieces fit together.

Flow Overview

The skill follows a router → workflow → output pattern:

User Request
    ↓
SKILL.md (Router)
    ↓ Intent detection
Workflow File
    ↓ Card generation logic
JSON Card Data
    ↓
┌─────────────────┬─────────────────┐
│  Preview        │  Export         │
│  (optional)     │  (always)       │
└─────────────────┴─────────────────┘
    ↓                   ↓
preview.jsx         .apkg file

Key Design Decisions

Slim Router Pattern

SKILL.md is intentionally minimal (~100 lines). It detects user intent and routes to the appropriate workflow file. This keeps token costs low—Claude only reads the files it needs for the specific task.

JSON as Intermediate Format

Cards are generated as JSON, which serves as the single source of truth. The same JSON feeds both the preview artifact and the .apkg export script. This means:

  • Claude can generate JSON once and reuse it
  • Edits happen to the JSON, not to multiple outputs
  • Preview and export are always in sync

Template-Based Artifacts

The preview artifact uses a template (preview-template.jsx) with a placeholder for card data. Claude injects JSON via sed rather than generating the entire artifact. This saves significant tokens.

Theme CSS Duplication

Theme CSS is duplicated in two places: themes.py (for .apkg generation) and preview-template.jsx (for preview rendering). This is intentional—it avoids runtime CSS injection complexity and keeps the preview self-contained.

⚠️ CSS Sync Warning: If you modify theme styles, you must update both files. See Procedures for the update process.

File Structure

anki-flashcards/ ├── SKILL.md # Router (~100 lines) ├── workflows/ │ ├── quick-cards.md # Simple vocab/Q&A path │ ├── document-extraction.md # PDF/doc → cards │ ├── review-cycle.md # Preview → feedback loop │ └── batch-import.md # CSV/JSON conversion ├── references/ │ ├── apkg-export.md # Package creation details │ ├── quality-fixes.md # Common card issues │ ├── choosing-card-type.md # Type selection guidance │ ├── drafting-guidance.md # Writing good cards │ ├── image-occlusion.md # Occlusion card details │ ├── people-cards.md # Person card details │ ├── obsidian-templates.md # Obsidian export format │ └── worked-examples.md # Example transformations ├── artifacts/ │ ├── preview-template.jsx # React preview (2299 lines) │ └── onboarding.html # User help (needs work) ├── scripts/ │ ├── create_anki_package.py # .apkg generation │ └── themes.py # CSS theme definitions ├── developer/ │ ├── portal.html # This file │ └── tools/ │ ├── test-preview.sh │ └── package-skill.sh └── assets/ └── test-data/ ├── test-cards.json ├── statue-of-liberty.png └── sample-person.png

Card Expansion Rules

Different card types generate different numbers of Anki cards from a single note:

Card Type Expansion
Front-Back 1 card
Concept 2 cards (term→def, def→term)
Cloze 1 card per {{cN::...}} marker
Image 1 card
Person 1 card per populated field (up to 12)
Image Occlusion 1 card per occlusion region

The preview uses _displayId for sequential UI numbering and _originalIndex for mapping feedback back to source cards.

Defaults & Configuration

Default values used when generating cards.

Package Defaults

Field Default Value Notes
deck_name "Cards from Claude" User can override per request
theme "minimal" Options: minimal, rich, bold, ios
author "Claude" Override for book/article cards
source "General Knowledge" Override for specific sources
verify_facts false Enable for factual cards

Tagging Conventions

Cards use two levels of tags:

Batch Tags

Applied to all cards in a batch. Format: topic-YYYY-MM-DD

"batch_tags": ["python-decorators-2024-12-30"]

Card-Level Tags

Optional tags for individual cards:

"tags": ["vocabulary", "advanced"]
Future: Auto-tagging based on card content (vocabulary-specific tags, source tags, etc.) is on the roadmap but not yet implemented.

Visual Themes

Four themes are available. Each creates separate Anki note types with unique model IDs, so cards with different themes can coexist.

Theme Description
minimal Clean whitespace, system fonts, subtle colors (default)
rich Elegant serif typography, refined details
bold Strong visual hierarchy, vibrant accents
ios Native iOS/AnkiMobile appearance
Note: The current themes are too similar and need differentiation. This is on the cleanup roadmap.

Model IDs

Each card type has a fixed model ID for consistency across exports:

Card Type Model ID
Front-Back 1732590444335
Concept 1734130500288
Cloze 1761346594645
Image 1735412847293
Person 1767049421568
Image Occlusion 1735412847294

Roadmap

Current priorities and future plans.

📁 Stored Separately
The full roadmap is maintained in a separate file for token efficiency. The roadmap contains detailed phase breakdowns, status tracking, and planned features.

View the Roadmap

Ask Claude to present the roadmap file:

present /mnt/skills/user/anki-flashcards/developer/roadmap.html

Or view the raw file:

view /mnt/skills/user/anki-flashcards/developer/roadmap.html

Quick Summary

Phase Status Focus
Phase 1: Ready for Users Current Core flows, polish, onboarding
Phase 2: Feedback & Iteration Planned User feedback integration
Phase 3: Advanced Features Planned Document extraction, batch import

Procedures

Voice-optimized prompts for common skill modifications. Speak your specific request into the highlighted area, then copy the complete prompt.

Updating CSS Themes

Theme CSS lives in two places that must stay in sync:

  1. scripts/themes.py — Source of truth for .apkg generation
  2. artifacts/preview-template.jsx — Hardcoded for preview rendering
Voice Prompt — Theme Update
I need to update the CSS for a theme in the Anki skill.
Speak: which theme and what CSS changes you want
Please update both: 1. scripts/themes.py — the theme definition 2. artifacts/preview-template.jsx — the THEME_CSS object Show me the changes before applying them so I can verify they match.

Adding a New Card Type

Adding a card type requires changes in multiple places:

  1. Define the note model in create_anki_package.py
  2. Add rendering logic in preview-template.jsx
  3. Update references/choosing-card-type.md
  4. Add to SKILL.md routing table
  5. Add test data to assets/test-data/test-cards.json
Voice Prompt — New Card Type
I want to add a new card type to the Anki skill.
Speak: card type name, what it's for, its fields, and how it should look
Please walk me through all the files that need to be updated and show me the changes for each.

Updating Test Data

Test data lives in assets/test-data/test-cards.json. It should cover all card types.

Voice Prompt — Test Data
Please update the Anki skill test data.
Speak: what you want to add, fix, or change in the test data
The test data is at: /mnt/skills/user/anki-flashcards/assets/test-data/test-cards.json After updating, run the test preview to verify it works: bash /mnt/skills/user/anki-flashcards/developer/tools/test-preview.sh

Packaging for Distribution

To create a .skill package for sharing:

# Copy skill to working directory first (read-only source)
cp -r /mnt/skills/user/anki-flashcards /home/claude/anki-flashcards

# Make any modifications...

# Package it
bash /home/claude/anki-flashcards/developer/tools/package-skill.sh /home/claude/anki-flashcards

The packaged skill will be at /mnt/user-data/outputs/anki-flashcards.skill

Testing the Preview

To test the preview artifact with sample data:

bash /mnt/skills/user/anki-flashcards/developer/tools/test-preview.sh

Then present /home/claude/preview.jsx to see the rendered cards.

Modifying Workflow Logic

Workflows are in workflows/*.md. To modify one:

Voice Prompt — Workflow Modification
I want to modify a workflow in the Anki skill.
Speak: which workflow, current behavior, and desired behavior
Please read the workflow file and propose the changes.

General Skill Modification

Voice Prompt — General Change
Open the Anki skill in developer mode.
Speak: what change you want to make to the skill
When done, package the skill.

Commands

Token-efficient commands for common operations.

Principle: Use copy/sed commands rather than rewriting files. Pre-built components should be combined, not regenerated.

Developer Commands

Say these to Claude when working on the skill:

Command What It Does
"dev" or "developer" Opens this portal
"debug" or "test preview" Renders test cards in preview artifact
"package the skill" Creates .skill file for distribution
"theme designer" Launches Theme Designer for CSS iteration

User Commands

Commands for end users:

Command What It Does
"/anki-help" Shows onboarding/help artifact

Bash Commands

Token-efficient bash operations:

Generate Preview from JSON

# Save card data to file
cat > /home/claude/cards.json << 'EOF'
{"deck_name": "My Deck", "cards": [...]}
EOF

# Inject into template
cp /mnt/skills/user/anki-flashcards/artifacts/preview-template.jsx /home/claude/preview.jsx
sed -i "s|__CARD_DATA_PLACEHOLDER__|$(cat /home/claude/cards.json | tr '\n' ' ')|" /home/claude/preview.jsx

# Present the preview
# (use present_files tool)

Export to .apkg

echo '{"deck_name": "My Deck", "cards": [...]}' | \
  python3 /mnt/skills/user/anki-flashcards/scripts/create_anki_package.py \
  /mnt/user-data/outputs/flashcards.apkg

Test Preview

bash /mnt/skills/user/anki-flashcards/developer/tools/test-preview.sh
# Then present /home/claude/preview.jsx

Package Skill

cp -r /mnt/skills/user/anki-flashcards /home/claude/anki-flashcards
bash /home/claude/anki-flashcards/developer/tools/package-skill.sh /home/claude/anki-flashcards

Theme Designer

# Launch with production themes only
bash /home/claude/anki-flashcards/developer/tools/theme-designer-launch.sh
# Then: present_files(['/home/claude/theme-designer.jsx'])

# Launch with working themes for comparison
bash /home/claude/anki-flashcards/developer/tools/theme-designer-launch.sh /home/claude/working-themes.json

Skill Files

Reference view of key skill files.

Note: These are read-only references. To modify files, use the procedures in the Procedures section.

Core Files

▶ SKILL.md — Router

The main entry point. ~100 lines of intent detection and routing.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/SKILL.md

▶ create_anki_package.py — Export Script

Python script that generates .apkg files from JSON. Handles all card types, themes, and media bundling.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/scripts/create_anki_package.py

▶ preview-template.jsx — Preview Artifact

React component for card preview. 2299 lines including theme CSS and all card type renderers.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/artifacts/preview-template.jsx

Workflow Files

▶ quick-cards.md

Simple path for vocab/single cards. Minimal token usage.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/workflows/quick-cards.md

▶ review-cycle.md

Preview → feedback → revise → export loop.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/workflows/review-cycle.md

▶ document-extraction.md

PDF/doc → cards workflow. Not fully implemented yet.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/workflows/document-extraction.md

▶ batch-import.md

CSV/JSON conversion workflow.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/workflows/batch-import.md

Reference Files

▶ apkg-export.md

Complete documentation for .apkg generation including JSON schema, all card types, themes.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/references/apkg-export.md

▶ quality-fixes.md

Common card quality issues and how to fix them.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/references/quality-fixes.md

▶ choosing-card-type.md

Guidance on selecting the right card type for different knowledge.

To view: Ask Claude to view /mnt/skills/user/anki-flashcards/references/choosing-card-type.md

Test Data

Sample cards for testing the preview and export.

Test Cards

The test data at assets/test-data/test-cards.json includes examples of most card types:

Front-Back
What is the primary benefit of spaced repetition over massed practice?
Spaced repetition produces stronger long-term retention because each retrieval attempt strengthens memory traces...
Front-Back
Why does the 'testing effect' improve learning more than re-reading?
Active retrieval during testing strengthens neural pathways and reveals gaps in knowledge...
Concept (Bidirectional)
Retrieval Practice
A learning strategy where you actively recall information from memory rather than passively reviewing it...
Concept (Bidirectional)
Interleaving
A study technique where you mix different topics or problem types during practice...
Cloze Deletion
The four key principles of effective flashcards are: {{c1::focused retrieval}}, {{c2::precision}}, {{c3::consistency}}, and {{c4::effort}}.
4 cards generated (one per cloze)
Image Recognition
[Image: statue-of-liberty.png]
What landmark is this?
Statue of Liberty
Person
[Photo: sample-person.png]
Raj Patel
Senior Product Designer @ Test Corp
San Francisco
Photography, hiking

Running Test Preview

bash /mnt/skills/user/anki-flashcards/developer/tools/test-preview.sh
# Then present /home/claude/preview.jsx
Known Issue: Image cards may not render correctly in the test preview. The image paths in test-cards.json are relative and may not resolve properly. This is a Phase 1 fix item.

Raw JSON

To view the full test data:

view /mnt/skills/user/anki-flashcards/assets/test-data/test-cards.json

Changelog

Version history and changes.

📁 Stored Separately
The full changelog is maintained in a separate file for token efficiency. It contains detailed version history with all changes, dates, and migration notes.

View the Changelog

Ask Claude to present the changelog file:

present /mnt/skills/user/anki-flashcards/developer/changelog.html

Or view the raw file:

view /mnt/skills/user/anki-flashcards/developer/changelog.html

Recent Versions

Version Date Summary
v2.0 Dec 30, 2024 Developer Portal overhaul, architecture restructure
v1.x Dec 2024 Initial development: preview, 6 card types, .apkg export

Contact

Feedback and questions welcome.

Developer

Ben Bateman

ben.bateman.email@gmail.com

If you're using this skill and have feedback—what works, what doesn't, what you wish it did—please reach out. Early feedback is invaluable.

Required Claude Settings

To use this skill, users need these Claude settings enabled:

  • Settings → Capabilities → Skills — Must be on to install the skill
  • Settings → Capabilities → Code Execution & File Creation — Required for generating files
  • Settings → Capabilities → Network Egress for Package Managers — Required for installing the genanki Python package