pdf-notes✓ ناجح

محتوى SKILL.md

---
name: pdf-notes
description: Use this skill to generate polished, study-ready PDF notes with charts, diagrams, math formulas, and syntax-highlighted code from any source material. Supports bar/line/pie/scatter charts, flowcharts, trees, state machines, Venn diagrams, timelines, LaTeX math, and highlighted code blocks. Trigger whenever the user wants clean, structured "notes" as a PDF rather than a raw document dump.
license: Personal use
---

# PDF Notes Generation Skill

Generate visually rich, study-ready PDFs from **notes-as-code** — a sequence of predefined helper calls. The agent never imports `reportlab`, `matplotlib`, `graphviz`, or `pygments` directly.

## Quick Start

```bash
# 1. Scaffold a run folder
uv run python runner.py init --name my_notes

# 2. Edit workspace/run1/content.py (see func.md for snippets)

# 3. Build the PDF
uv run python runner.py build \
    --content workspace/run1/content.py \
    --out workspace/run1/notes.pdf \
    --title "My Topic" \
    --subtitle "Study notes" \
    --preview

# 4. Validate layout
uv run python runner.py validate --pdf workspace/run1/notes.pdf
```

## System Dependencies

```bash
# Required for previews
sudo apt install poppler-utils
# Required for diagrams (flowcharts, trees, state machines)
sudo apt install graphviz
```

## Files

- `notes_kit.py` — all helpers (text + re-exports from graphics_kit/highlighting)
- `graphics_kit.py` — charts, diagrams, math, Venn, timeline
- `highlighting.py` — pygments syntax highlighting for `add_code(highlight=True)`
- `runner.py` — CLI: `init`, `build`, `validate`
- `func.md` — snippet library the agent copies from verbatim
- `plan.md` — full architecture and agent workflow
- `schemas/generate_spec.py` — Pydantic contracts for JSON I/O

## Agent Workflow

1. Plan outline (nested bullets: H1 -> H2 -> H3 -> content blocks).
2. Init a run folder: `uv run python runner.py init --name <topic>`.
3. Copy snippets from `func.md` into `content.py` — only edit string arguments.
4. Build: `uv run python runner.py build --content ... --out ... --title ... --preview`.
5. Parse JSON output. If `success == false`, fix errors and rebuild.
6. Validate: `uv run python runner.py validate --pdf ...`.
7. Fix any `severity: error` issues. Iterate until clean.

## Helper Categories

| Category   | Helpers                                                  | Deps        |
|------------|----------------------------------------------------------|-------------|
| Text       | `add_title_block` `add_heading` `add_paragraph` `add_bullets` `add_numbered_list` `add_code` `add_callout` `add_table` `add_divider` `add_space` `add_page_break` `add_quote` `add_image` `add_keep_together` | reportlab   |
| Charts     | `add_bar_chart` `add_line_chart` `add_pie_chart` `add_donut_chart` `add_scatter` `add_histogram` `add_box_plot` `add_area_chart` `add_heatmap` `add_radar_chart` | matplotlib  |
| Diagrams   | `add_flowchart` `add_tree` `add_state_diagram` `add_block_diagram` `add_graph` `add_call_graph` `add_venn` `add_timeline` | graphviz + matplotlib |
| Math       | `add_math`                                               | matplotlib  |
| Code       | `add_code(highlight=True, line_numbers=True)`            | pygments    |

## Key Rules

- **Never import reportlab/matplotlib/graphviz/pygments** in content.py.
- **Never use Unicode sub/super glyphs** (₀ ²). Use `<sub>`/`<super>` tags or `add_math`.
- **Always use helpers** (`kit.add_*`). Never call `story.append(...)` directly.
- **Keep code lines under ~80 chars** to avoid overflow validation errors.
- **Don't end with `add_page_break`** — creates empty trailing page.
- **Graphics helpers never raise** — they degrade gracefully with warnings.

الترخيص

الترخيص المُعلن: Personal use

النص الكامل للترخيص متاح في المستودع المصدري.

عرض الترخيص في المستودع المصدري — النسخة المنشورة هناك هي المرجع.