syuan03/skill-anything

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

---

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

---

Output Structure

Every source generates a study pack by default. You can also export the same pack as a SKILL.md directory for AI tools.

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

Use --format all to generate both the study pack and the agent skill export 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
• all is for teams or workflows that want both

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 both study pack + skill export
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 + .png)
engine.write(pack, "./output")

# 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_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)
│   └── 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.