class-skipper

中文说明

A portable agent skill that turns lecture slides (PDF/PPTX) and optional transcripts (DOCX/TXT/MD), in Chinese or English, into Chinese Obsidian study notes. It works in Codex and Claude Code, on Windows and macOS.

The skill runs four steps in the current agent session, delegating independent work to native subagents when available:

1. Read and plan: read every extracted unit, view labeled slide contact sheets to catch diagrams and scanned pages, and plan 4–8 chapters with figure candidates and concept ownership.
2. Write chapters: writers follow a fixed template: key-point summary, motivation → definition → mechanism → example → pitfalls, Mermaid diagrams for source-described processes, labeled supplement callouts, and hidden-answer self-tests.
3. Add visuals: crop and verify slide figures, and (with web access) add verified links to external visualizations or interactive demos.
4. Revise once: one editor fixes coverage, accuracy, repetition and format; a mechanical check lists Markdown problems to fix in the same pass.

Local Python helpers only parse documents, render pages, cache responses and publish files. No API key, .env, model SDK or external OCR is used; the host's normal sign-in and usage limits apply.

Install

Python 3.11+ is required. From this repository:

# Windows (PowerShell)
py -3 tools/install_skill.py

# macOS
python3 tools/install_skill.py

By default the installer copies skills/class-skipper to both hosts:

Host	Default location
Codex	$CODEX_HOME/skills/class-skipper, else ~/.agents/skills/class-skipper
Claude Code	$CLAUDE_CONFIG_DIR/skills/class-skipper, else ~/.claude/skills/class-skipper

Use --host codex or --host claude for one host, or --destination for an exact folder (for example a project's .claude/skills/class-skipper). A differing installed copy is preserved; --update renames it to class-skipper.backup* and installs the new version. Copying the folder by hand also works.

Use

Start the agent in your notebook (Obsidian vault) root or a course folder, then:

# Codex
Use $class-skipper to make notes for every lecture in computer-organization-and-architecture/input.

# Claude Code
/class-skipper make notes for every lecture in computer-organization-and-architecture/input

Claude Code also loads the skill automatically when you ask for lecture notes. The skill checks Python with scripts/local.py doctor and installs only missing parser packages (pypdfium2, Pillow, python-docx, python-pptx) into <course>/workspace/.venv.

Layout

The notebook root keeps .obsidian/; each course folder has its own input/, workspace/ and output/. Helper --root is the course folder.

<notebook-root>/                         Obsidian vault root
  .obsidian/                             Untouched
  computer-organization-and-architecture/   Course root (--root)
    input/course.yaml                    Optional manifest (lecture pairing/order)
    input/L02.pdf, input/L02.docx        Slides and transcripts
    workspace/L02/<run-id>/              Materials, plan, requests, chapters,
                                         sheets/crops, draft, revision, cache
    output/index.md                      Course directory
    output/L02/index.md                  Chapter links with summaries, synthesis
    output/L02/chapters/01-performance-metrics.md  One note per chapter (English file name)
    output/L02/assets/l02-isa-formats.png Referenced figures only

File and folder names are English; note content is Chinese. Each chapter note has YAML properties (with its Chinese title as an alias for link completion), previous/next and directory navigation at top and bottom, a key-point callout, concept sections with formulas, examples, figures and Mermaid diagrams, collapsed self-tests, footnotes on key results and a collapsed source list with merged page ranges. Publication preserves manual edits: a conflicting file is left untouched and the new version is saved as a candidate in workspace. Earlier runs keep their original paths and section-N.md filenames.

Cross-chapter links use relative Markdown paths to the actual English filenames, with Chinese display text. Writers reference stable chapter IDs; publication resolves them and reports unknown or ambiguous targets. Math uses LaTeX in prose, summaries, tables and figure captions. Image alt text stays short and plain; the complete caption is a paragraph below the image so formulas render.

See SKILL.md, the workflow contract, the note style and visuals guide.

Development

python -m venv .venv
.venv/bin/python -m pip install pypdfium2 python-docx python-pptx Pillow ruff   # Windows: .venv\Scripts\python
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m ruff check skills tools tests
.venv/bin/python -m ruff format --check skills tools tests

Tests use real small PDF/DOCX/PPTX/TXT fixtures and labeled response doubles; they do not call a model. Real-run evidence is recorded separately in CODEX_SKILL_REPORT.md; the architecture is in DESIGN.md.