Roadmap

Development priorities and feature specifications for the Anki Flashcards skill.

Last updated: December 31, 2025 · Theme Designer in progress, Image Occlusion testing

Why this is a separate file: Token efficiency. The roadmap contains detailed specifications that Claude needs to read when implementing features, but not when doing other developer tasks. Keeping it separate means we only pay the token cost when needed.
Phase 1: Ready for Users Current Focus

The minimum viable skill for getting early feedback. Users can create quality cards with minimal friction. Focus on speed, low token usage, and smooth onboarding.

Done Slim SKILL.md Router
Reduced from 726 lines to ~100. Pure intent detection and routing.
Done Developer Portal
Documentation hub for skill development with procedures, architecture, and file references.
Done Preview Artifact
React-based card preview with flip, themes, and feedback export.
Done .apkg Export Script
Python script for generating Anki packages with all card types.
Done Quick Cards Workflow
One-turn card creation for common use cases. The primary user flow—must be fast and low-token.

Design Principles

  • One turn to .apkg — User asks, gets package immediately
  • Options, not gates — Present preview alongside, offer deeper review, but don't require engagement
  • Skill read time is real cost — Quick cards logic should be in a dedicated workflow file, not bloating SKILL.md

Quick Card Types

  • Vocabulary (single or batch) — Terms/definitions → Bidirectional concept cards. Quality check: don't use term in definition.
  • Acronym unpacking — Generates 2 cards: Front-back (acronym → expansion) + Concept (term ↔ definition of the expanded term).
  • Pre-formatted cards — User provides card content, Claude assigns appropriate card type + generates .apkg. Quality check: validate card type assignment (this is error-prone—Claude sometimes picks Front-Back when it should be Concept).
  • Person (quick) — Photo + name → minimal Person card. After generating, offer to add more info ("We could also add role, location, interests—anything else you know about this person?").
  • Image recognition — Image + "reminder card for X" → Image recognition card.

Implementation Notes

  • Create workflows/quick-cards.md with inline logic for all quick types
  • SKILL.md routes to this file for quick card patterns
  • Consider: can we use bash commands to generate preview + .apkg simultaneously so user gets both without extra turns?
Done User Guide / Onboarding Artifact
Interactive HTML artifact that serves as both first-time onboarding and ongoing reference.

Implemented Features

  • Matches developer portal design (sidebar nav, dark mode, mobile-responsive)
  • "Notes vs Cards" section explaining Anki's data model
  • Detailed field tables for each note type with defaults
  • Setup checklists for Anki and Claude settings
  • Anki alternatives for users who don't want AnkiMobile ($25)
  • Links to Gwern's guide, shared decks, documentation
  • Accessible via /anki-help anytime
  • Auto-presented after first interaction, respects opt-out
In Progress Theme Designer Tool
Developer tool for rapid CSS/HTML iteration on card themes. Full-viewport preview with side panel CSS editor, card selector, and live preview. Status: Local dev support and IO theme styles added; awaiting user review and bug fixes.

Implemented Features (v3.2)

  • Full-viewport layout — Preview uses entire screen instead of narrow 500px container
  • Side panel CSS editor — 400px panel slides in from right (replaces tiny modal)
  • Card selector — Prev/next navigation to cycle through sample cards of same type
  • Live CSS preview — Changes apply immediately with "Unsaved" indicator
  • Status badges — Clear "Production" (green) vs "Working" (orange) distinction
  • Dark mode toggle — Emoji indicator (☀️/🌙), card preview background updates
  • Export — Copy-pasteable CSS formatted for themes.py
  • Responsive design — CSS editor becomes full-width overlay on narrow screens

Remaining Work

  • User testing and review of current iteration
  • Bug fixes based on testing feedback
  • Confirm IO card support in Theme Designer during testing

Launch Command

bash /home/claude/anki-flashcards/developer/tools/theme-designer-launch.sh [working_themes_file]
present_files(['/home/claude/theme-designer.jsx'])

Files

  • artifacts/theme-designer.jsx — Main React artifact (template with placeholders)
  • developer/tools/theme-designer-launch.sh — Generates artifact with production themes + sample cards
Planned Basic Theme Cleanup
Make themes actually distinct and visually appealing. Important for initial rollout—users will have cards with these themes. Depends on: Theme Designer Tool

Current State

  • Four themes exist: minimal, rich, bold, ios
  • They're too similar and not particularly pretty
  • Theme CSS is duplicated in themes.py and preview-template.jsx

Goals

  • Each theme should be visually distinct
  • Cards should look polished—this matters for user perception
  • May reduce to fewer themes if that's cleaner

Implementation

  • Update scripts/themes.py (source of truth)
  • Update artifacts/preview-template.jsx to match
  • Test in both preview and actual Anki import
Planned Preview Polish
Fix known issues and improve UX through hands-on testing.

Known Issues

  • Image cards don't render correctly in test data (paths don't resolve) — Fixed in v2.8
  • Need to verify image occlusion rendering works correctly with base64 images
  • Need to test with various card volumes
  • Various small UX issues to identify through usage

Approach

  • Sit down and run through real use cases
  • Document issues as encountered
  • Fix iteratively
Done Developer Mode Launch Pattern
Single bash command to prep and present all developer files. Efficient entry into dev mode.

Implementation

  • developer/tools/dev-launch.sh — preps all files for presentation
  • SKILL.md developer trigger runs this script
  • Present: portal, roadmap, changelog, skill package (for folder navigation)
  • Then wait for developer instructions

Rationale

  • Multiple files presented = developer can click between them without spending tokens
  • Claude only reads deeply what's needed for the specific task
  • Roadmap, changelog extracted for token efficiency
Phase 2: Polish & Feedback Planned

Improvements based on early user feedback and features that weren't critical for initial launch.

Planned Preview Responsive Design
Currently constrained to mobile-ish layout. Should adapt to different screen sizes.
In Progress Image Occlusion Support
Full support for image occlusion cards in preview and generation. OCR-based coordinate detection complete, Anki export testing pending.

Completed (v3.1)

  • OCR-based coordinate detection via detect_occlusion_regions.py
  • Automatic text label detection with Tesseract OCR
  • Multi-line label merging (e.g., "Left" + "Atrium" → "Left Atrium")
  • Grid overlay generation for unlabeled images (10x10 with row/column labels)
  • Preview image generation showing detected regions with bounding boxes
  • Comprehensive documentation update with detection strategy guidance
  • Claude's role shifted to validation/filtering rather than coordinate estimation

Completed (v3.0)

  • Preview now embeds image inside SVG — masks stay aligned when resizing
  • generateIOEmbeddedSvg() replaces old overlay approach
  • SVG viewBox uses actual image dimensions, not 0-100
  • preprocess_test_data.py extracts image dimensions via PIL
  • Rectangular masks only (cleaner appearance)
  • Heart anatomy test image added

Remaining Work

  • Validate .apkg export produces working IO cards in Anki
  • End-to-end testing with real diagrams
  • Integration: connect detection script output to card generation workflow
Planned Cloze Cards from Lists
Auto-generate cloze deletions from lists (e.g., "The four pillars of X are A, B, C, D").

Why Deferred

  • Easy to make bad cloze cards
  • Needs more guardrails than quick cards
  • May require preview/review flow rather than one-turn
Planned Structured Feedback Picklist
Replace freeform edit text in preview with common options: "too complex", "wrong card type", "add citation", etc.
Planned Deeper Quality Review Option
For pre-formatted cards, offer optional deeper review that checks card quality more thoroughly.
Planned Fact Verification Flow
"Add citation" feedback option that triggers web search and adds source to card.
Planned Auto-Tagging
Automatic tags based on content: vocabulary tags, source-based tags, topic detection.
Planned Python Package Extraction
Extract shared Python logic into a standalone pip-installable package hosted on GitHub.

Motivation

  • Better modularity — Claude skill becomes thin orchestration layer
  • Multi-agent friendly — other coding agents can work on the package with standard dev workflows
  • Versioning — pin package versions in skill, test updates separately
  • Reusability — package can be used outside Claude skills
  • Standard tooling — pytest, mypy, proper IDE support

Proposed Package Structure

anki-tools/  (GitHub repo)
├── pyproject.toml
├── src/
│   └── anki_tools/
│       ├── __init__.py
│       ├── rendering.py      # iframe rendering, base64 conversion
│       ├── preprocessing.py  # image path → data URL  
│       ├── themes.py         # theme CSS definitions
│       └── export.py         # .apkg generation
└── tests/

Migration Path

  1. Create GitHub repo with package structure
  2. Move preprocess_test_data.py logic to preprocessing.py
  3. Move theme definitions from scripts/themes.py to package
  4. Update skill scripts to pip install and import
  5. Gradually migrate more logic as needed

Installation in Skill

pip install git+https://github.com/USER/anki-tools.git --break-system-packages
Phase 3: Advanced Features Planned

Bigger features for power users and complex workflows.

Planned Document Extraction Workflow
Upload PDF/doc → analyze → propose card breakdown → review → export.

Requirements

  • Intermediate note generation step
  • User reviews proposed card breakdown before generation
  • May need chunking for large documents
Planned Batch Import
CSV/JSON structured data → card transformation.
Planned Source/Citation Cards
Cards that cite where info came from (e.g., "According to [book], X is Y"). Part of robust extraction workflow, not quick cards.
Planned Token Efficiency Audit
Systematic review of all paths. Identify where tokens are being wasted. Agent-optimized command suite.
Planned Custom Note Type Import from .apkg
Allow users to drop in existing Anki .apkg files to extract note type definitions, enabling the skill to create cards using the user's custom note types.

Concept

  • User uploads an .apkg file containing their custom note type
  • Skill extracts note type schema (fields, card templates, styling)
  • Conversational flow to confirm understanding of the note type
  • Update skill's supported card types to include the custom note type
  • Propagate support across all relevant files (card type selector, export script, preview, etc.)

Scope Considerations

  • Best suited for relatively simple/standard note types
  • Complex note types with heavy JS/CSS customization may not be practical
  • May need user guidance on which note types are "compatible"

Open Questions (Ask Ben Later)

  • What level of complexity should be supported vs. declined?
  • Should extracted note types persist across conversations (via skill update)?
  • How to handle note types that conflict with existing built-in types?