syuan03/skill-anything

v0.4.1 • v0.4 • v0.3 • v0.2 • Quick Start • Demo • Output • Skill Export • Config • CLI • API • FAQ

---

v0.4.1 — Trust & Coverage

v0.4.1 hardens the generated material so a successful command means more than valid JSON:

• Every LLM-generated quiz question, flashcard, and exercise must include a verbatim source quote. Skill-Anything verifies the quote against the supplied text and rejects unsupported items.
• Citations survive YAML round-trips and appear in Markdown, offline sites, Anki cards, and exported Skill assets.
• Oversized chapters are split into ordered prompt windows instead of silently discarding everything after the first 5–6K characters.
• sa audit pack.yaml --strict provides a deterministic CI gate for citation coverage, duplicates, malformed options, and missing answers or solutions.
• GitHub Actions now tests Python 3.10–3.13, runs Ruff, and builds a wheel on every push and PR.
• Inline source text is no longer copied into source_ref, and cache writes are atomic.

sa audit output/transformer-learning-pack.yaml --strict
sa audit output/transformer-learning-pack.yaml --strict --json

Read the complete v0.4.1 release notes.

---

📣 What’s New in v0.4 — Share & Learn

🌈 Turn any study pack into something you can actually hand to another person.

v0.4 adds portable outputs that work outside the Skill-Anything CLI. A recipient does not need Python, an API key, or an internet connection.

• 🌐 Offline interactive learning site — one self-contained index.html with searchable notes, glossary, quiz mode, flip cards, exercises, dark mode, printing, and progress saved locally in the browser
• 📦 One-command share bundle — sa share pack.yaml creates the site plus a ready-to-send ZIP; the same site can be hosted directly on GitHub Pages, Cloudflare Pages, or Netlify
• 🧠 Anki integration — --format anki exports flashcards and quiz questions as an import-ready UTF-8 TSV with HTML fields and useful tags
• ✨ A real --format all — now produces the study guide, structured YAML, agent Skill, offline site, and Anki deck together
• 🛠️ Reliability polish — caches now follow --output, unknown formats fail clearly, portable exports avoid unnecessary image API calls, CLI dependencies support modern Click, FAST/SMART model routing now reaches the real API calls, and the documented/default concurrency is consistently 6; long inline text is also handled safely
• 🎯 More grounded generation — quiz/card/exercise counts scale to the available source evidence, and prompts explicitly reject unsupported facts instead of padding short notes

# Existing pack → offline site + ZIP. Send the ZIP to anyone.
sa share output/transformer-learning-pack.yaml

# Generate every human-, browser-, Anki-, and agent-ready format in one run.
sa repo . --format all

# Or choose one portable integration.
sa export output/transformer-learning-pack.yaml --format web
sa export output/transformer-learning-pack.yaml --format anki

The web export contains no CDN scripts, fonts, trackers, or runtime API calls. It is a single portable file, so private study material stays local unless you choose to publish it.

Read the complete v0.4 release notes.

---

What’s New in v0.3

v0.3 makes Skill-Anything actually usable on long sources — books, multi-hour talks, large repos.

v0.1 and v0.2 silently degraded on anything past ~15K characters: the knowledge generator truncated input, quiz/flashcard generation hit hard per-call caps before reaching later chapters, and every LLM call was sequential with no caching. v0.3 introduces a section-aware, map-reduce pipeline with concurrency and a disk cache, so a 12-chapter book produces a study pack that actually covers every chapter.

• Section-aware parsing across every source type (PDF uses the embedded outline; text/web split by headings; video/audio bucket transcripts into 5-min sections; repos produce one Section per file)
• Map-reduce knowledge generation — per-section map calls produce local summary/concepts/notes; a single reduce call synthesizes the global summary, cheat sheet, takeaways, and learning path. detailed_notes is assembled deterministically with no truncation.
• Per-section quota allocation for quiz/flashcards/exercises — largest-remainder weighting by section size with a guaranteed minimum per section, so every chapter gets coverage even on a small total budget
• Concurrent LLM execution + disk cache — ThreadPoolExecutor map runner with rich progress bars, per-section failure isolation, and a sha256(prompt+model+version) cache so second runs of the same source skip every cached call
• Two-tier model routing — SKILL_ANYTHING_MODEL_FAST for map calls, SKILL_ANYTHING_MODEL_SMART for reduce
• New CLI flags — --concurrency / -c (default 6) and --no-cache on every source command

sa pdf book.pdf --format all --concurrency 8        # long PDF, parallel map
sa pdf book.pdf --format all --concurrency 8        # second run: cache hits, finishes in seconds
sa text long-notes.md --no-cache                    # bypass cache for a clean run

v0.3 Case Study

A 12-chapter distributed-systems primer processed end-to-end with --concurrency 6 (sa text dist-systems-book.md --format all):

Chapter coverage verified by keyword matching across the generated quiz / flashcards / exercises:

Every chapter (1–12) is represented, including narrower topics like CRDTs and messaging semantics that v0.2 routinely dropped once the per-call cap was hit at chapter 2.

If v0.2 was “any source -> study pack -> reusable skill toolchain”, v0.3 is “any source, including long ones, with caching and concurrency built in”.

---

What’s New in v0.2

v0.2 turns Skill-Anything into a lightweight repo-to-skill toolchain.

• sa repo scans a local repo or public GitHub repo and builds an onboarding-ready study pack
• sa import-skill imports an existing SKILL.md package back into a reusable study pack / YAML pack
• sa lint validates a skill package and fails on blocking packaging or asset errors

Best for in v0.2

• turning a codebase into onboarding notes, glossary, quiz, and learning path
• importing external SKILL.md packages back into your own workflow
• checking a skill package before you share, publish, or re-export it

sa repo . --format all
sa repo https://github.com/openai/openai-python --format study
sa import-skill ./output/my-skill --format study
sa lint ./output/my-skill

If v0.1 was “any source -> study pack”, v0.2 is “any source -> study pack -> reusable skill toolchain”.

v0.2 Mini Demo

Turn a repo into a reusable pack, re-import it, and validate it before sharing:

# 1) Generate from a repo
sa repo https://github.com/openai/openai-python --output ./output/openai-python --format all

# 2) Bring the exported skill back into your own workflow
sa import-skill ./output/openai-python/skill --output ./output/openai-python-reimported --format study

# 3) Validate the package before publishing
sa lint ./output/openai-python/skill

output/openai-python/
├── study_guide.md
├── pack.yaml
├── quiz.md
├── flashcards.md
└── skill/
    ├── SKILL.md
    ├── assets/
    ├── references/
    └── scripts/

This is the v0.2 advantage in one loop: generate from repos, reuse existing skills, and catch packaging problems before re-exporting.

Real Output Case

Transformer Architecture is a good showcase because it makes both sides of Skill-Anything obvious: deep study-pack output for humans, and clean SKILL.md export for AI tools.

Case 1: a full study guide with summary, notes, glossary, cheat sheet, quiz, flashcards, exercises, and learning path.

Case 2: the same pack exported as a reusable SKILL.md directory with references, assets, and scripts.

Why Skill-Anything?

AI agents are getting smarter, but humans still learn the same broken way — read, forget, re-read, forget again. Research shows passive reading retains ~10% of information, while active recall (quizzes, flashcards, spaced repetition) pushes retention to 80%+. Creating those materials manually? Nobody has time.

Skill-Anything automates the entire pipeline. One command. Any source. Structured study pack by default, optional AI skill export when you need it.

---

Positioning

Skill-Anything has two layers of output:

1. Study Pack (default): a structured learning package built from raw source material
2. Agent Skill Export (optional): a SKILL.md directory generated from that pack for Claude Code, Cursor, or Codex

That distinction matters:

• A PDF, video, or webpage is not a skill by itself
• Skill-Anything first turns it into a study pack: notes, quiz, flashcards, exercises, glossary, and structured YAML
• If you want, that pack can then be exported into an agent-ready skill artifact

If you remember only one sentence, remember this:

Skill-Anything converts source material into a reusable study pack, and can optionally export that pack as an AI-tool-compatible skill.

---

Demo

▶ Open Interactive Demo (GitHub Pages)

Full interactive demo with generation pipeline animation, quiz session, and output explorer.

The demo showcases:

• Generation Pipeline — sa auto transformer-paper.pdf extracts, generates, and outputs a complete study pack
• Interactive Quiz — Hard-difficulty quiz with scenario, comparison, and fill-in-the-blank questions
• Output Explorer — Browse the 12-section study guide, key concepts, glossary, flashcards, and exercises

---

Quick Start

1. Install

Recommended for local use and development:

git clone https://github.com/SYuan03/Skill-Anything.git
cd Skill-Anything
pip install -e ".[all,dev]"

2. Configure LLM

cp .env.example .env
# Edit .env — set your API key and model

Skill-Anything works with any OpenAI-compatible API:

No API key? Skill-Anything still works — it falls back to rule-based generation. All features function, just with lower quality.

3. Generate a Study Pack

sa pdf textbook.pdf                                    # PDF → Study Pack
sa video https://www.youtube.com/watch?v=dQw4w9WgXcQ   # Video → Study Pack
sa web https://example.com/article                     # Webpage → Study Pack
sa text notes.md                                       # Text → Study Pack
sa audio lecture.mp3                                   # Audio → Study Pack
sa repo .                                              # Local repo → Study Pack
sa repo https://github.com/openai/openai-python        # Public GitHub repo → Study Pack
sa auto anything                                       # Auto-detect source type

3.5. v0.2 Fast Paths

sa repo . --format all                                # repo -> study pack + SKILL.md export
sa import-skill ./external-skill --format study       # existing skill -> YAML + study guide
sa lint ./external-skill                              # validate before re-exporting or sharing

4. Import or Validate Existing Skills

sa import-skill ./output/my-skill --format study
sa lint ./output/my-skill

5. Learn Interactively

sa quiz output/my-skill.yaml       # Take an interactive quiz (6 types, graded A-F)
sa review output/my-skill.yaml     # Flashcard review (multi-round spaced repetition)
sa info output/my-skill.yaml       # View full pack details

6. Export as an AI Skill When Needed

sa export output/my-skill.yaml --format skill
sa auto textbook.pdf --format all

7. Share It or Move It to Anki

# Builds output/my-skill-site/index.html and a ready-to-send ZIP
sa share output/my-skill.yaml

# Import the generated TSV from Anki's File → Import menu
sa export output/my-skill.yaml --format anki

---

Output Structure

Every source generates a study pack by default. The same pack can also become an agent Skill, an offline interactive site, or an Anki deck.

Study Format (default)

output/
├── my-skill.yaml              # Structured pack data (quiz/review/info commands use this)
├── my-skill.md                # Complete study guide (12 sections, read directly)
└── my-skill-concept-map.png   # AI-generated visual concept map

Agent Skill Format (--format skill)

output/my-skill/
├── SKILL.md                   # Claude Code / Cursor / Codex compatible
├── references/                # Detailed notes, glossary, learning path
├── assets/                    # Quiz, flashcards, exercises (YAML), concept map
└── scripts/                   # Standalone quiz runner

Offline Web Format (--format web)

output/my-skill-site/
└── index.html                 # Complete app + content; no server or internet required

Open the file directly, send it to someone, or deploy the directory to any static host. Quiz and flashcard progress is stored in that browser’s localStorage.

Anki Format (--format anki)

output/my-skill-anki.tsv       # Flashcards + quiz questions + topic/type/difficulty tags

In Anki, choose File → Import and select the TSV. Separator, HTML mode, and column names are embedded in the file, so no add-on is required.

Use --format all to generate the study pack, agent Skill, web site, and Anki deck at once.

The 12-Section Study Guide

The .md file is a self-contained learning package:

YAML Data Format

The .yaml file contains the full structured data, consumable by sa quiz, sa review, sa info, or any downstream tool:

 title: "Transformer Learning Pack"
source_type: pdf
source_ref: "transformer-paper.pdf"
summary: "..."
detailed_notes: "..."
key_concepts:
  - "Self-attention mechanism"
  - "Multi-head attention"
  - ...
glossary:
  - term: "Attention"
    definition: "A mechanism that computes relevance weights..."
    related_terms: ["Self-Attention", "Cross-Attention"]
  - ...
quiz_questions:
  - question: "What is the purpose of positional encoding?"
    options: ["A) ...", "B) ...", "C) ...", "D) ..."]
    answer: "B) ..."
    explanation: "..."
    difficulty: medium
    type: multiple_choice
  - ...
flashcards:
  - front: "Why divide by sqrt(d_k) in scaled dot-product attention?"
    back: "Large dot products push softmax into vanishing gradient regions..."
    tags: ["attention", "math"]
  - ...
practice_exercises:
  - title: "Implement Multi-Head Attention"
    description: "..."
    difficulty: hard
    hints: [...]
    solution: "..."
  - ...
learning_path:
  prerequisites: [...]
  next_steps: [...]
  resources: [...]

---

Skill Export

Skill-Anything can export the generated pack as a SKILL.md directory — the format used by Claude Code, Cursor, and Codex.

This is the key mental model:

• study is for humans learning from the material
• skill is for AI tools loading the material as a reusable artifact
• web is for sharing an interactive, installation-free learning site
• anki is for spaced repetition in the Anki ecosystem
• all is for teams or workflows that want every output

Generate as Agent Skill Export

# Generate from any source and export directly as a skill
sa auto paper.pdf --format skill
sa pdf textbook.pdf --format skill
sa web https://example.com/article --format skill

# Or export an existing pack
sa export output/my-skill.yaml --format skill

# Generate every output format
sa auto paper.pdf --format all

Skill Directory Structure

output/my-skill/
├── SKILL.md              # Frontmatter + core knowledge (key concepts, cheat sheet, takeaways)
├── references/
│   ├── detailed-notes.md # Comprehensive structured notes
│   ├── glossary.md       # Domain terms and definitions
│   └── learning-path.md  # Prerequisites, next steps, resources
├── assets/
│   ├── quiz.yaml         # 20-40 quiz questions (6 types, 3 difficulty levels)
│   ├── flashcards.yaml   # 25-50 spaced-repetition cards
│   ├── exercises.yaml    # Hands-on practice exercises
│   └── concept-map.png   # AI-generated visual concept map
└── scripts/
    └── quiz.py           # Standalone CLI quiz runner

Use as AI Skill

# Claude Code
cp -r output/my-skill/ ~/.claude/skills/

# Cursor
cp -r output/my-skill/ ~/.cursor/skills/

# Project-level (any tool)
cp -r output/my-skill/ .claude/skills/

The generated SKILL.md follows the standard format with YAML frontmatter (name, description, version) and uses progressive disclosure: compact core knowledge in SKILL.md, detailed references and structured assets alongside it.

---

Quiz Types

6 question types designed to test different cognitive levels:

Example quiz session:

$ sa quiz output/transformer.yaml --difficulty hard --count 10

--- Q1/10 ---  HARD  (Scenario)

  You're designing a search engine where queries are short
  but documents are long. How would you adapt the standard
  Transformer attention for efficiency?

  Answer > Use cross-attention with query as Q, chunked docs as K/V...

  Reference answer: Apply asymmetric attention — short queries attend
  to long documents via cross-attention with linear-complexity
  approximations like Linformer or chunked processing...

  Did you get it right? (y/n) > y

╔═══════════════════════════════════╗
║  Score: 9/10 (90%)  Grade: A      ║
╚═══════════════════════════════════╝

---

Supported Sources

PDF

• Extracts text page-by-page with layout-aware parsing
• Backend priority: pdfplumber → pymupdf (fitz) → pypdf
• Chapters/sections auto-detected from content structure
• Install: pip install skill-anything[pdf]

Video

• YouTube URLs: Auto-fetches transcript via youtube-transcript-api or yt-dlp
• Local subtitle files: .srt and .vtt formats
• Local video files: Requires a .srt/.vtt file alongside (use Whisper to generate)
• Timestamps preserved in the generated outline
• Install: pip install skill-anything[video]

Webpage

• Fetches and extracts article content from any URL
• Uses BeautifulSoup for clean text extraction, with regex fallback
• Page title auto-detected for the generated pack
• Install: pip install skill-anything[web]

Audio

• Transcribes audio files using local Whisper or OpenAI Whisper API
• Supported formats: .mp3, .wav, .m4a, .aac, .flac, .ogg, .wma
• Local Whisper is tried first (free, offline); falls back to Whisper API if not installed
• Timestamps preserved in the generated outline
• Install: pip install skill-anything[audio] (for local Whisper)
• Or just set SKILL_ANYTHING_API_KEY to use the Whisper API without installing the model

Text / Markdown

• Reads any UTF-8 text file (.txt, .md, etc.)
• Also accepts inline text strings directly
• Sections detected from headings and structure
• No extra dependencies needed

Repo

• Accepts a local repository path or a public GitHub repo URL
• Uses a docs-first scan: README, docs, manifests/config, then a small slice of key source files
• Designed for onboarding packs, architecture summaries, glossary extraction, and contributor quizzes

Skill Import / Lint

• sa import-skill restores an existing SKILL.md package back into a reusable YAML/study pack
• sa lint checks frontmatter, referenced files, and asset YAML integrity before sharing or re-exporting
• Useful for normalizing and validating externally created skills

Auto-Detection

sa auto determines the type automatically:

---

CLI Reference

Source Conversion Commands

Interactive Commands

Export Command

Utility

Common Options

---

Python API

from skill_anything import Engine

engine = Engine()

# Generate from any source
pack = engine.from_pdf("textbook.pdf", title="ML Fundamentals")
pack = engine.from_video("https://youtube.com/watch?v=xxx")
pack = engine.from_web("https://example.com/article")
pack = engine.from_text("notes.md")
pack = engine.from_repo(".")
pack = engine.from_skill("./output/my-skill")
pack = engine.from_source("auto-detect.pdf")  # auto-detect

# Write to disk (creates .yaml + .md and an optional concept-map image)
engine.write(pack, "./output")

# Portable v0.4 outputs
engine.write_web(pack, "./output")   # self-contained -site/index.html
engine.write_anki(pack, "./output")  # Anki-compatible TSV
engine.write(pack, "./output", format="all")

# Load an existing pack
pack = Engine.load("output/my-skill.yaml")

# Inspect the contents
print(f"Title:      {pack.title}")
print(f"Source:     {pack.source_type.value} — {pack.source_ref}")
print(f"Concepts:   {len(pack.key_concepts)}")
print(f"Glossary:   {len(pack.glossary)} terms")
print(f"Quiz:       {len(pack.quiz_questions)} questions")
print(f"Flashcards: {len(pack.flashcards)} cards")
print(f"Exercises:  {len(pack.practice_exercises)} tasks")

# Access individual components
for q in pack.quiz_questions[:3]:
    print(f"[{q.question_type.value}] {q.question}")

for card in pack.flashcards[:3]:
    print(f"Q: {card.front}")
    print(f"A: {card.back}\n")

# Export to dict / JSON
import json
data = pack.to_dict()
print(json.dumps(data, indent=2, ensure_ascii=False))

---

Environment Variables

All configuration is done through environment variables (set in .env or your shell):

The .env file is loaded automatically from the current working directory or the project root. Example:

SKILL_ANYTHING_API_KEY=sk-your-api-key-here
SKILL_ANYTHING_API_BASE=https://api.openai.com/v1
SKILL_ANYTHING_MODEL=gpt-4o
# SKILL_ANYTHING_MODEL_FAST=gpt-4o-mini
# SKILL_ANYTHING_MODEL_SMART=gpt-4o
# SKILL_ANYTHING_CONCURRENCY=6
SKILL_ANYTHING_IMAGE_API_BASE=https://api.openai.com/v1
SKILL_ANYTHING_IMAGE_MODEL=dall-e-3
# SKILL_ANYTHING_PROXY=http://127.0.0.1:7890

---

Project Structure

Skill-Anything/
├── skill_anything/
│   ├── __init__.py
│   ├── cli.py                  # Typer CLI entry point (sa / skill-anything)
│   ├── engine.py               # Core orchestration: Parser → Generators → SkillPack
│   ├── llm.py                  # OpenAI-compatible API client (chat + image)
│   ├── models.py               # Data models: KnowledgeChunk, SkillPack, QuizQuestion, ...
│   ├── parsers/
│   │   ├── base.py             # Abstract base parser
│   │   ├── pdf_parser.py       # PDF extraction (pdfplumber / pymupdf / pypdf)
│   │   ├── video_parser.py     # YouTube transcript / subtitle parsing
│   │   ├── web_parser.py       # Webpage scraping (httpx + BeautifulSoup)
│   │   ├── text_parser.py      # Plain text / Markdown reading
│   │   └── audio_parser.py     # Audio transcription (Whisper local / API)
│   ├── generators/
│   │   ├── knowledge_gen.py    # Summary, notes, glossary, cheat sheet, learning path
│   │   ├── quiz_gen.py         # 6 quiz question types
│   │   ├── flashcard_gen.py    # Spaced-repetition flashcards
│   │   ├── practice_gen.py     # Hands-on exercises
│   │   └── visual_gen.py       # AI-generated concept map images
│   ├── exporters/
│   │   ├── __init__.py         # Exporter registry
│   │   ├── skill_exporter.py   # SKILL.md export (Claude Code / Cursor / Codex)
│   │   └── portable_exporter.py # Offline web site + Anki TSV exports
│   └── interactive/
│       ├── quiz_runner.py      # CLI interactive quiz with grading
│       └── review_runner.py    # CLI flashcard review with multi-round repetition
├── tests/
│   ├── conftest.py
│   └── test_*.py
├── assets/
├── pyproject.toml              # Package config, dependencies, scripts
├── requirements.txt
├── .env.example                # Environment variable template
└── LICENSE

---

Use Cases

---

FAQ

---

Contributing

Contributions are welcome. To set up the development environment:

PR must pass pytest & ruff checks

git clone https://github.com/SYuan03/Skill-Anything.git
cd Skill-Anything
pip install -e ".[all,dev]"

Run tests:

pytest

Run linting:

ruff check .

---

MIT License — free to use, modify, and distribute.

Skill-Anything — Turn source material into reusable learning systems.