DeepTutor PDF Skill
A sandbox-based office skill that lets an agent read, extract, create, merge, watermark, and fill PDFs by writing and running Python scripts against .pdf files.
Skill runs in a sandboxed shell with preinstalled libraries only, explicitly forbids pip install and network OCR; data flow is transparent (read input PDFs, write relative-path outputs), no credentials or external side effects. Deducted for: no explicit user-confirmation step, no rollback guidance, publisher unverified, and password handling in the encrypt example lacks sensitive-data prompts.
Instructions are self-consistent with a clear library-selection decision tree, failure-diagnosis guidance (read stderr, change strategy, no blind retries), and verification steps (reopen output, confirm fields/word counts). Deducted for: static-only review without execution; edge cases (corrupt PDFs, very large files, multi-subfont .ttc compatibility) are untested; failure-feedback quality rests on documentation claims alone.
Triggers are clear (user uploads a .pdf or asks to produce/edit/extract), and capability boundaries are unusually honestly declared: no OCR, network off, graceful degradation when soffice/pandoc are missing. Chinese use is well served by a concrete CJK TrueType font-registration routine (wqy paths). Deducted for: core function depends on sandbox-preinstalled fonts/libraries whose actual availability is unverified; the frontmatter requires declaration is thin.
Well-layered: task-sectioned with progressive disclosure, abundant examples, and proactive known-limitation disclosure (no OCR, CFF fonts unsupported, missing converters). Dependencies are explicitly declared in pyproject (pypdf/pdfplumber/reportlab/PyMuPDF) and the Apache-2.0 license is clear. Deducted for: SKILL.md itself carries no version or changelog, limitations are scattered rather than summarized, and maintenance responsibility is only inferable at the repository level.
Covers the main PDF workflow tasks (extraction, tables, merge, encrypt, forms, rendering) with directly reusable examples and actionable handling of hard cases (CJK output, scanned files, flat forms), giving clear marginal value. Deducted for: static review cannot verify output quality, examples assume library-version behavior, outputs still require runtime verification, and comparative benefit is inferential.
Code examples are concrete and auditable, dependency claims cross-check against pyproject, and the repository has CI workflows and a test directory — but no committed tests cover this skill's key paths. Deducted for: all claims are author-written with no third-party execution evidence; scanned-file behavior and font-fallback claims cannot be statically reproduced, capping at 5.
- Static review only — no code was executed; examples (especially form filling and CJK font registration) depend on sandbox library/font versions and should be validated in the target environment before use.
- Scanned/image-only PDFs cannot be OCR'd; inputs containing scanned pages will yield only partial results — verify input type in advance.
- Encrypt/decrypt examples pass plaintext passwords as parameters; for sensitive documents, ensure passwords do not leak into logs or session records.
- SKILL.md has no version or changelog; example API behavior may shift with dependency versions across DeepTutor upgrades.
What does this skill do, and when should you use it?
This is the built-in PDF skill of the DeepTutor repository (deeptutor/skills/builtin/pdf/SKILL.md), part of its bundled office skill set (docx/pdf/pptx/xlsx). It contains no executable code itself; it is an instruction playbook that teaches the model to pick the right preinstalled Python library per task — pdfplumber for text/table extraction, pypdf for merge/split/rotate/watermark/encrypt/forms, reportlab for creating PDFs from scratch, and PyMuPDF (fitz) for rendering pages to images. It triggers whenever a user uploads a .pdf or asks to produce, edit, or pull data out of one. It explicitly requires a shell sandbox, notes that OCR and network are unavailable, and instructs the model to admit failure honestly on scanned documents rather than fabricate content.
When a .pdf is uploaded or requested, the model runs complete Python scripts via the exec tool to produce files or data: pdfplumber extracts layout-aware text and tables (including exporting to Excel worksheets and tuning strategies for messy tables); pypdf merges, splits per page, rotates, crops, reads metadata, encrypts/decrypts, and stamps watermarks; it detects AcroForm fields and fills them, or overlays text via FreeText annotations at pdfplumber-derived coordinates for flat forms; reportlab builds new reports with styled tables (Platypus) or absolute-placed text (Canvas), registering a CJK-capable TrueType font first so Chinese/Japanese/Korean text does not render as tofu; PyMuPDF rasterizes each page to PNG. The skill also demands verification (count requested words, reopen the file to confirm form values landed), and on failure requires diagnosing stderr and changing strategy instead of retrying identical code or silently reducing scope.
- A researcher or student uploads a data-heavy PDF report and needs its tables batch-extracted into an Excel workbook for analysis.
- An office or finance worker needs to merge several PDFs, split by page, rotate, or password-protect files before distribution.
- A user must complete a government or institutional form: detect whether it has fillable AcroForm fields, otherwise overlay text at correct coordinates.
- A content creator asks for a styled report PDF containing Chinese text — the skill registers a CJK font first to avoid empty glyph boxes.
- A developer or teacher wants PDF pages rendered to images to hand off to an image-capable step.
- A scanned PDF with no extractable text is encountered — the skill instructs the model to say OCR is unavailable rather than invent content.
What are this skill's strengths and limitations?
- Assigns the right library per task (pdfplumber/pypdf/reportlab/PyMuPDF), preventing arbitrary tool choice or redundant installs.
- Covers the common PDF lifecycle: read, extract, create, merge, split, rotate, watermark, encrypt/decrypt, fill forms, render to image.
- Codifies real-world gotchas — CJK fonts, scanned PDFs, flat-form coordinate conversion — with strict honesty rules against fabrication.
- Requires output verification (word counts, reopening files to confirm form values) and strategy changes on failure rather than blind retries.
- No OCR and no network in the sandbox: text on scanned PDFs is unrecoverable — a hard limitation.
- Depends on specific Python libraries preinstalled in the sandbox; elsewhere you must install pdfplumber, pypdf, reportlab, and PyMuPDF yourself.
- External Markdown/HTML-to-PDF converters (soffice/pandoc) are usually absent, forcing a reportlab rebuild path.
- It is an instruction document only — no packaged scripts or test suite; real-world quality depends on how faithfully the host LLM follows it.
How do you install this skill?
The skill ships with the main DeepTutor project and needs no separate installation: after cloning the repo (git clone https://github.com/HKUDS/DeepTutor.git) or running pip install -U deeptutor, the built-in skills live under deeptutor/skills/builtin/. DeepTutor skills can also be managed via deeptutor skill commands or Learning Space → Skills from hubs like EduHub. The repo provides no documented steps for copying this single skill into other clients such as Claude Code; since it is a standard SKILL.md, it can in principle be placed manually into any compatible client's skill directory, but exact paths are client-specific and undocumented in the source.
How do you use this skill?
In DeepTutor, simply upload a .pdf in chat or say "export this PDF's tables to Excel" or "merge these two PDFs and encrypt them" — the skill triggers automatically; the model runs Python via exec and returns a download link. A code-execution sandbox must be active: local/container deployments run a restricted subprocess sandbox by default, docker-compose routes to a hardened runner sidecar; if sandbox_allow_subprocess is set to false, office skills cannot produce files. Example flow for tables-to-Excel: pdfplumber's extract_tables() per page, then openpyxl writes each table to its own worksheet in tables.xlsx.