---
name: pdf-to-agent-skill
description: Convert PDF documents into one or more high-quality reusable Agent Skills. Use when the user wants the knowledge, procedures, rules, standards, or methods in a PDF turned into agent capabilities — "skill-ify this PDF", "turn this manual into a skill", "make yourself able to do what this document teaches" — even when they don't use the word "skill". Not for merely summarizing, translating, or answering questions about a PDF.
---

# PDF to Agent Skill

Turn a source PDF into skills that make an agent better at real tasks.
The output is agent behavior — workflows, decisions, constraints — never a summary.

**Hard rules:**

- Never present knowledge that is not in the PDF as if it came from the PDF.
- Never map chapters to skills mechanically. Skill boundaries follow capabilities.
- Never paste large verbatim PDF passages into a generated skill.
- If part of the PDF cannot be read reliably, say so. Do not silently fill gaps.

## Workflow

Track these steps explicitly (e.g. in your task list):

1. Read the PDF and verify extraction quality
2. Build a capability map (working file)
3. Decide skill boundaries
4. Write the skill(s)
5. Grounding check
6. Final review and report

### Step 1: Read the PDF

Use the most reliable reading method available in this environment — direct PDF
reading, `pdftotext`, a Python library, page rendering plus image reading, or OCR.
No specific tool is required.

Verify extraction before trusting it:

- Compare extracted content volume against the page count; large gaps mean extraction failure.
- If text is garbled or missing, or the PDF is scanned, switch method (render pages as images, OCR).
- If tables, diagrams, or layout carry meaning that plain text loses, view those pages as images.

**Large documents (books, ~100+ pages): do not read linearly at uniform depth.**

- First pass: table of contents, preface, and chapter openings — classify each
  chapter as actionable (procedures, decisions, how-to) or background (theory,
  history, motivation).
- Deep-read actionable chapters. Skim background chapters only for definitions
  and constraints the actionable parts depend on.
- If the document exceeds what you can hold in context, work in passes and keep
  running notes: extend the capability map (Step 2) incrementally per chapter
  batch, but decide skill boundaries (Step 3) only after covering the whole book.
- Expect a book to yield several candidate capabilities; the capability map
  becomes more important, not less. Do not let early chapters dominate.

While reading, collect with page references:

- tasks and procedures (order, preconditions)
- rules and their strength (must / should / may), with exceptions and qualifiers
- decision criteria, thresholds, and definitions needed for decisions
- checklists, worked examples, warnings, failure and recovery paths
- which parts are actionable knowledge vs background reference

### Step 2: Build a capability map

Before writing any skill, answer:

> What should an agent be able to do better after learning this document?

Write a capability map to a working file (not part of the final deliverable).
For each candidate capability record:

| Field       | Content                                        |
| ----------- | ---------------------------------------------- |
| capability  | what the agent becomes able to do              |
| trigger     | user requests / situations where it applies    |
| inputs      | what the agent needs to start                  |
| workflow    | ordered steps                                  |
| decisions   | judgment points and their criteria             |
| constraints | rules, exceptions, qualifiers                  |
| output      | what gets produced                             |
| sources     | PDF sections / pages this rests on             |

Chapter titles are not capabilities. Background knowledge that only supports a
capability attaches to it as reference material; it does not become its own skill.

### Step 3: Decide skill boundaries

Default to one skill per coherent job an agent would be invoked to do.
Read [references/decomposition.md](references/decomposition.md) when the map has
more than one candidate capability, or when you are unsure whether to split or merge.

### Step 4: Write the skill(s)

Read [references/skill-spec.md](references/skill-spec.md) first — it defines the
format constraints every generated skill must satisfy and how to write its
description. Apply [references/skill-design.md](references/skill-design.md) for
content quality.

For each generated skill:

- `SKILL.md` carries the core workflow, decisions, constraints, and gotchas needed on every use.
- Detailed lookup material (large rule tables, terminology, per-case detail) moves to
  `references/` files, each cited from SKILL.md with an explicit load condition
  ("Read references/X.md when Y").
- Add `scripts/` only when the PDF prescribes genuinely deterministic, repeatable
  computation an agent should not re-derive; otherwise create none.
- Write generated skills to `./skills/<skill-name>/` under the current working
  directory unless the user specifies a destination.

### Step 5: Grounding check

Read [references/grounding.md](references/grounding.md). Classify every important
instruction in the generated skills as source-derived, structural, or external,
and fix violations before finishing.

### Step 6: Final review and report

Read [references/evaluation.md](references/evaluation.md) and run its checklist.
Fix clear defects, then report to the user:

- generated skills: name, purpose, file tree
- why these boundaries: how many skills and the split/merge reasoning
- reading limitations or uncertainty (unreadable pages, ambiguous source statements)
- how to install the skills for their agent (install paths are in skill-spec.md)
- two or three example prompts that should trigger each generated skill