Anki Skill

Manage Anki flashcards via AnkiConnect HTTP API.

⛔ MANDATORY: Pre-Add Checklist (READ THIS FIRST)

You MUST NOT call addNote or addNotes until ALL steps below are completed. No exceptions. No defaults. No shortcuts.

Step 1 — Fetch available models: Call modelNames to get the full list of note types from the user's Anki.

Step 2 — Ask the user to choose a model: Present the available models to the user via AskUserQuestion and let them pick one. NEVER default to "Basic" or any other model without explicit user selection.

Step 3 — Verify field mapping: After the user selects a model, call modelFieldNames with that model to inspect its fields. Map the card content to the correct fields and show the mapping to the user for confirmation.

Step 4 — Confirm deck, model, and tags: Present a final summary of deck name, chosen model, field mapping, and tags. Wait for user approval before proceeding.

Only after the user explicitly confirms ALL of the above may you call addNote or addNotes.

Skipping any step (e.g., adding cards without asking for model selection) is a rule violation.

Prerequisites

•Anki desktop must be running
•
AnkiConnect plugin installed (code: 2055492159)
- •In Anki: Tools → Add-ons → Get Add-ons… → enter 2055492159

Helper Script

macOS / Linux (Bash)

scripts/anki-connect.sh wraps curl for convenience:

bash

# Basic usage
bash scripts/anki-connect.sh <action> [params_json]

# Examples
bash scripts/anki-connect.sh version
bash scripts/anki-connect.sh deckNames
bash scripts/anki-connect.sh createDeck '{"deck":"MyDeck"}'

Windows (PowerShell)

scripts/anki-connect.ps1 wraps Invoke-RestMethod for convenience:

powershell

# Basic usage
pwsh scripts/anki-connect.ps1 <action> [params_json]

# Examples
pwsh scripts/anki-connect.ps1 version
pwsh scripts/anki-connect.ps1 deckNames
pwsh scripts/anki-connect.ps1 createDeck '{"deck":"MyDeck"}'

Platform Detection

Choose the correct script based on the current OS:

•Windows ($env:OS -eq 'Windows_NT' or os.platform() === 'win32'): use anki-connect.ps1
•macOS / Linux: use anki-connect.sh

Override the endpoint with ANKI_CONNECT_URL env var (default: http://127.0.0.1:8765).

You can also call AnkiConnect directly with curl:

bash

curl -s http://127.0.0.1:8765 -X POST -d '{"action":"version","version":6}'

API Reference

All requests use POST to http://127.0.0.1:8765 with JSON body:

json

{"action": "<action>", "version": 6, "params": { ... }}

Response format:

json

{"result": <value>, "error": <null or string>}

Connection Check

bash

bash scripts/anki-connect.sh version
# → {"result": 6, "error": null}

Deck Operations

List all decks:

bash

bash scripts/anki-connect.sh deckNames
# → {"result": ["Default", "Japanese::JLPT N5"], "error": null}

List decks with IDs:

bash

bash scripts/anki-connect.sh deckNamesAndIds
# → {"result": {"Default": 1}, "error": null}

Create a deck:

bash

bash scripts/anki-connect.sh createDeck '{"deck":"Spanish::Vocabulary"}'

Get deck statistics:

bash

bash scripts/anki-connect.sh getDeckStats '{"decks":["Default"]}'
# Returns: new_count, learn_count, review_count, total_in_deck

Model (Note Type) Operations

List all models:

bash

bash scripts/anki-connect.sh modelNames
# → {"result": ["Basic", "Basic (and reversed card)", "Cloze"], "error": null}

Create a custom model:

bash

bash scripts/anki-connect.sh createModel '{
  "modelName": "MyModel",
  "inOrderFields": ["Front", "Back", "Extra"],
  "css": ".card { font-family: Arial; font-size: 20px; text-align: center; }",
  "isCloze": false,
  "cardTemplates": [
    {
      "Name": "Card 1",
      "Front": "{{Front}}",
      "Back": "{{FrontSide}}<hr id=answer>{{Back}}<br><small>{{Extra}}</small>"
    }
  ]
}'

Note Operations

⛔ STOP: Before using addNote or addNotes, you MUST complete the Pre-Add Checklist above. Do NOT call these APIs until the user has confirmed model, field mapping, deck, and tags.

Add a single note:

bash

bash scripts/anki-connect.sh addNote '{
  "note": {
    "deckName": "Default",
    "modelName": "Basic",
    "fields": {"Front": "What is photosynthesis?", "Back": "The process by which plants convert light energy into chemical energy"},
    "tags": ["biology", "ai-generated"],
    "options": {"allowDuplicate": false, "duplicateScope": "deck"}
  }
}'

Add multiple notes (batch):

bash

bash scripts/anki-connect.sh addNotes '{
  "notes": [
    {
      "deckName": "Default",
      "modelName": "Basic",
      "fields": {"Front": "Q1", "Back": "A1"},
      "tags": ["batch"]
    },
    {
      "deckName": "Default",
      "modelName": "Basic",
      "fields": {"Front": "Q2", "Back": "A2"},
      "tags": ["batch"]
    }
  ]
}'

Find notes:

bash

bash scripts/anki-connect.sh findNotes '{"query":"deck:Default"}'
bash scripts/anki-connect.sh findNotes '{"query":"tag:biology"}'
# Query syntax: https://docs.ankiweb.net/searching.html

Update note fields:

bash

bash scripts/anki-connect.sh updateNoteFields '{
  "note": {
    "id": 1514547547030,
    "fields": {"Front": "updated front", "Back": "updated back"}
  }
}'

Card Operations

Find cards:

bash

bash scripts/anki-connect.sh findCards '{"query":"deck:Default"}'
# → {"result": [1494723142483, 1494703460437], "error": null}

Get card details:

bash

bash scripts/anki-connect.sh cardsInfo '{"cards":[1498938915662]}'
# Returns: question, answer, deckName, modelName, fields, interval, reps, lapses, etc.

Statistics

Cards reviewed today:

bash

bash scripts/anki-connect.sh getNumCardsReviewedToday
# → {"result": 42, "error": null}

Cards reviewed by day:

bash

bash scripts/anki-connect.sh getNumCardsReviewedByDay
# → {"result": [["2025-01-15", 124], ["2025-01-14", 261]], "error": null}

Review history for a deck:

bash

bash scripts/anki-connect.sh cardReviews '{"deck":"Default","startID":0}'
# Returns: [reviewTime, cardID, usn, buttonPressed, newInterval, previousInterval, newFactor, reviewDuration, reviewType]

Review history for specific cards:

bash

bash scripts/anki-connect.sh getReviewsOfCards '{"cards":["1653613948202"]}'

Batch Operations

Use multi to combine multiple actions in one request:

bash

bash scripts/anki-connect.sh multi '{
  "actions": [
    {"action": "deckNames"},
    {"action": "modelNames"},
    {"action": "getNumCardsReviewedToday"}
  ]
}'

Flashcard Generation Guide

When generating flashcards from source material, follow this process:

Step-by-Step Process

•Rewrite the content using clear and concise language while retaining its original meaning
•Split the rewritten content into sections, each focusing on one main point
•Generate multiple flashcards from each section; for sections with more than 10 words, split and summarize before creating cards

Quality Rules

•Keep flashcards simple, clear, and focused on the most important information
•Questions must be specific and unambiguous
•Use simple and direct language for readability
•Each answer should contain only a single key fact/name/concept/term
•Avoid yes/no questions — ask "what", "where", "why", "how" instead
•Do not repeat the question stem in the answer

Example: Dead Sea

Source text:

The characteristics of the Dead Sea: Salt lake located on the border between Israel and Jordan. Its shoreline is the lowest point on the Earth's surface, averaging 396 m below sea level. It is 74 km long. It is seven times as salty (30% by volume) as the ocean. Its density keeps swimmers afloat. Only simple organisms can live in its saline waters.

Generated flashcards:

Question	Answer
Where is the Dead Sea located?	on the border between Israel and Jordan
What is the lowest point on the Earth's surface?	The Dead Sea shoreline
What is the average level on which the Dead Sea is located?	396 meters (below sea level)
How long is the Dead Sea?	74 km
How much saltier is the Dead Sea as compared with the oceans?	7 times
What is the volume content of salt in the Dead Sea?	30%
Why can the Dead Sea keep swimmers afloat?	due to high salt content
Why is the Dead Sea called Dead?	because only simple organisms can live in it
Why only simple organisms can live in the Dead Sea?	because of high salt content

Example: ECG (Electrocardiography)

Source text:

The contraction of any muscle is associated with electrical changes called 'depolarization', and these changes can be detected by electrodes attached to the surface of the body. Since all muscular contraction will be detected, the electrical changes associated with contraction of the heart muscle will only be clear if the patient is fully relaxed and no skeletal muscles are contracting. Although the heart has four chambers, from the electrical point of view it can be thought of as having only two, because the two atria contract together ('depolarization'), and then the two ventricles contract together.

Generated flashcards:

Question	Answer
What electrical changes are associated with muscle contraction?	depolarization
How can depolarization be detected?	by electrodes attached to the surface of the body
Why must the patient be fully relaxed during an ECG?	because skeletal muscle contractions would also be detected
How many chambers does the heart have from an electrical point of view?	two (atria contract together, then ventricles contract together)
What is the term for the two atria contracting together?	depolarization

Output Format

Always present generated flashcards in a table for user review before adding to Anki:

code

| Question | Answer |
|---|---|
| ... | ... |

After user confirms, use addNotes to batch-add all cards at once.

File Integration

PDF → Flashcards

•Use the pdf skill to extract text from the PDF
•Apply the flashcard generation guide above to create Q&A pairs
•Present the table to the user for review
•Confirm: target deck, note type (model), and tags
•Use addNotes to batch-add

CSV / Excel → Flashcards

•Use the xlsx skill to read and parse the file
•Inspect the columns — if data is already in Q/A format, map directly to Front/Back fields
•If not Q/A format, apply the flashcard generation guide to the content
•Present the mapping/cards to the user for review
•Confirm: target deck, note type (model), and tags
•Use addNotes to batch-add

⛔ IMPORTANT: You MUST follow the Pre-Add Checklist (at the top of this document) before adding any cards. This means: fetch models → ask user to choose → verify fields → confirm deck/model/tags. No exceptions.

Workflow Examples

1. Check Connection and List Decks

bash

bash scripts/anki-connect.sh version
bash scripts/anki-connect.sh deckNames
bash scripts/anki-connect.sh getDeckStats '{"decks":["Default"]}'

2. Generate and Add Flashcards from Text

•User provides text content
•Apply flashcard generation guide — rewrite, split, generate Q&A pairs
•Present table for review
•Follow Pre-Add Checklist: a. Fetch models: bash scripts/anki-connect.sh modelNames b. Ask user to choose model via AskUserQuestion c. Verify fields: bash scripts/anki-connect.sh modelFieldNames '{"modelName":"<user-chosen-model>"}' d. Show field mapping to user and confirm e. Confirm deck, model, and tags — present final summary
•Only after user confirms all of the above:

bash

bash scripts/anki-connect.sh addNotes '{
  "notes": [
    {"deckName":"<deck>","modelName":"<user-chosen-model>","fields":{"<field1>":"Q1","<field2>":"A1"},"tags":["ai-generated"]},
    {"deckName":"<deck>","modelName":"<user-chosen-model>","fields":{"<field1>":"Q2","<field2>":"A2"},"tags":["ai-generated"]}
  ]
}'

3. Generate Flashcards from PDF

•Use pdf skill to extract text
•Follow "Flashcard Generation Guide" on extracted text
•Present cards for review
•Follow Pre-Add Checklist (fetch models → user picks → verify fields → confirm all)
•Batch-add with addNotes

4. Import Flashcards from CSV/Excel

•Use xlsx skill to parse the file
•Map columns to Front/Back or generate cards
•Present mapping for review
•Follow Pre-Add Checklist (fetch models → user picks → verify fields → confirm all)
•Batch-add with addNotes

5. View Study Statistics

bash

# Today's review count
bash scripts/anki-connect.sh getNumCardsReviewedToday

# Review history by day
bash scripts/anki-connect.sh getNumCardsReviewedByDay

# Detailed review history for a deck
bash scripts/anki-connect.sh cardReviews '{"deck":"Default","startID":0}'

# Deck stats (new/learn/review counts)
bash scripts/anki-connect.sh getDeckStats '{"decks":["Default"]}'