repo-cards

Generate and maintain spaced-repetition Q&A card decks capturing load-bearing codebase knowledge.

Updated Sep 15, 2026
One-click install
npx skills add https://github.com/MitchellNeedham/repo-cards --skill repo-cards-mitchellneedham
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: repo-cards
Source: https://github.com/MitchellNeedham/repo-cards/tree/main/skills/repo-cards
Command: npx skills add https://github.com/MitchellNeedham/repo-cards --skill repo-cards-mitchellneedham

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml.

What problem does it solve? Re-entering a repository after time away means reconstructing why constraints and decisions exist, which is the expensive part of a context switch. This Skill writes and maintains a spaced-repetition card deck of the facts where being wrong is costly, so a repo can be re-entered without re-reading it. ## Core Features & Use Cases - Deck generation: Registers a repo and writes a deck.yaml of cards covering invariants, load-bearing boundaries, decision reasoning, rejected alternatives, and counter-intuitive mechanics, each with an anchor path, look routes, priority, and tags. - Drift-aware updates: Runs drift detection against commits since the last update, verifies cards whose anchors moved, retires dead facts, fixes broken routes and topics, and stamps added/updated dates. - Spaced-repetition review: Reviews cards on a Leitner schedule (boxes 1-5, 1-16 day intervals) via the repo-cards CLI, with filters by repo, tag, topic, priority, and computed topics like last-week. - Use Case: Before a meeting about a feature, run a curated topic brief to rebuild the mental model of how that area works end to end. ## Quick Start Ask the assistant to generate repo cards for the current repository so its load-bearing knowledge is captured in a reviewable deck.

Frequently Asked Questions about repo-cards

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a flashcard deck for a codebase?

Run the generate workflow, which registers the repo with repo-cards register, reads CLAUDE.md, README, docs and ADR folders, then writes a deck.yaml of cards to the data home directory. Each card needs an id, question, answer, anchor path, and tags.

How do I update repo cards after new commits?

Run repo-cards drift --repo NAME to see commits since the last update, cards whose anchors changed, and uncovered files. Verify flagged cards against the current code first, then add new cards, fix broken look routes and topics, and bump last_update_sha.

What belongs on a code knowledge flashcard?

Include facts where being wrong is expensive: invariants, load-bearing component boundaries, decision reasoning, rejected alternatives, and counter-intuitive mechanics. Exclude anything grep answers quickly, API listings, and facts that change under ordinary refactoring.

Does regenerating a deck lose my review progress?

No. Content and state are separate files: deck.yaml holds the cards while state.json holds Leitner review state keyed by card id. A card that keeps its id keeps its box, so regenerating the deck never costs review progress.

What are the limitations of spaced repetition for codebase knowledge?

Decks drift as code changes, so cards need periodic verification via the drift command rather than blind trust. Past roughly 60 commits or when a quarter of anchor paths are dead, a full regeneration beats incremental updates.