Turn a PDF Guide Into a Skill by Deleting Most of It

The sentence that should govern every document-to-skill conversion sits in the Claude Code docs, in one line about the body of a SKILL.md: "State what to do rather than narrating how or why." The reason is mechanical — once a skill loads, its content stays in the conversation for the rest of the session, so "every line is a recurring token cost."

Now open the PDF you were about to convert and count how much of it is narration of how and why. The intro. The paragraph reassuring you this is easier than it looks. The definition of a term. The aside listing three tools you could use instead. That material is exactly what makes it a good document — and exactly what makes a faithful conversion a bad skill.

So converting is mostly a deletion job, and the compression ratio is your quality signal. My working number: if the skill comes out longer than about a quarter of the source, I didn't convert it, I reformatted it. Reformatted documents are the files sitting in .claude/skills/ doing nothing.

Read the source once — it's the most expensive thing you'll do

Before you attach anything, know what a PDF costs. Anthropic's PDF docs describe the pipeline plainly: the system converts each page into an image, and the text from each page is extracted and provided alongside that image. You pay for both. Their comparison of the two document-processing modes on Bedrock puts a 3-page PDF at roughly 1,000 tokens with text extraction only, and roughly 7,000 tokens with full visual understanding — a 7× difference for the same three pages. The hard ceilings are 32 MB per request and 600 pages (100 when the request's context window is under 1M tokens), and the docs warn that dense PDFs "can fill the context window before reaching the page limit," recommending you split the document into sections.

Two practical consequences. If the tables, screenshots and diagrams carry the procedure, attach the real PDF and pay for vision. If it's prose with a couple of code blocks, extract the text first and spend a seventh of the budget. And either way: read it once. The entire point of the conversion is that the expensive read never has to happen again.

The document's genre decides the skill's shape

The Claude Code docs split skill content into two kinds, and your source is already one of them. Reference content adds knowledge Claude applies to whatever you're working on — conventions, patterns, domain knowledge. Task content gives step-by-step instructions for a specific action. Reading your document as the wrong one is the most common conversion mistake I see.

• A procedure — runbook, deploy checklist, migration guide, the five-step tutorial — becomes task content: a numbered workflow. For anything with more than a few steps, the authoring guide recommends embedding a literal checklist that Claude copies into its response and ticks off as it goes. That's the cheapest known fix for a model skipping the validation step in the middle.
• A standard — style guide, spec, review rubric, policy — becomes reference content plus a feedback loop. The docs' code-free example is the one to copy: draft, review against the checklist, note each issue with its section reference, revise, re-check, and only proceed when every requirement is met. As they put it, "the 'validator' is STYLE_GUIDE.md, and Claude performs the check by reading and comparing." Your standards document doesn't become the instructions — it becomes the thing the instructions check against.

The four cuts

Anthropic's engineering post frames a skill as "an onboarding guide for a new hire." Keep that literal: you're writing for someone competent who is about to act, not someone deciding whether to care.

1. The reader-orientation layer. Every intro, motivation section and "why this matters" paragraph goes. The authoring guide's default assumption is that Claude is already very smart, so "only add context Claude doesn't already have," and it hands you the test to apply line by line: "Does this paragraph justify its token cost?"
2. Explanations of things the model already knows. The docs price this one. A concise PDF-extraction section runs about 50 tokens; the same section padded with what a PDF is and why that library was chosen runs about 150. Three times the cost, zero extra instruction.
3. Options presented neutrally. A good document is fair to its reader and lists the alternatives. A skill has to choose. The guidance is to "provide a default (with escape hatch)" — one recommended path, plus at most one named exception for the case that genuinely breaks it.
4. The narrative order. Documents teach in a build-up order: concepts, then context, then steps. Agents execute. Reorder into execution order, and demote the "Prerequisites" section into step 0 checks.

What survives is the part a competent stranger could still get wrong: exact commands, exact thresholds and limits, named gotchas, the always/never rules, and any table of real values.

Set the freedom level per step, not per document

This is the thing prose physically cannot express: in a document every sentence carries the same weight. In a skill you choose. The authoring guide calls it degrees of freedom, with an analogy worth stealing — a narrow bridge with cliffs on both sides needs exact instructions and guardrails; an open field with no hazards needs general direction and trust. Their low-freedom example is literally "Run exactly this script" followed by "Do not modify the command or add additional flags."

My rule of thumb converts mechanically: every place the document said "be careful here" or "make sure you" is a low-freedom step. Rewrite it as one exact command with an explicit prohibition next to it. Everywhere the document was describing judgment, leave four bullets and trust the model. Fragility decides, not importance.

What moves out of the body

The routing rule is one question: would I look this up, or follow it? Followed → the body. Looked up → its own file next to SKILL.md. Appendix tables, the complete option reference, the long example collection, the fill-in template.

The economics make this nearly free. Bundled files cost nothing until read, Claude loads only the one file a task actually needs, and a bundled script's code never enters context at all — only its output does. So the 40-page PDF becomes a SKILL.md you can read on one screen plus two or three siblings.

Three details decide whether those files get read. Keep every reference one level deep from SKILL.md — the docs warn that Claude may only partially read files it reaches through a chain of references, previewing with something like head -100. Name them for their contents (form_validation_rules.md, not doc2.md) and organize by domain (reference/finance.md, reference/sales.md) so an unrelated task never loads them. And if the document shipped a template or a script, bundle it and point at it with ${CLAUDE_SKILL_DIR}, which expands to the skill's own directory — the path then holds regardless of where the skill is installed or which directory you started Claude in.

The one field your document cannot give you

Everything above is extraction. The description is authorship, because no sentence in your PDF was ever written to match how you'll ask for this work at 9pm on a Tuesday. It has to carry two things at once — the capability, plus the situations that should reach for it — and it does real work: Claude uses it to pick the right skill from potentially 100+ available ones. The shape in the docs is worth copying literally — capability first, then triggers: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

Same for the name. A document title tends to convert into a vague noun — documents, helper, guide — and those are on the docs' list of names to avoid. Prefer gerund form: processing-invoices, reviewing-migrations, writing-status-updates.

The conversion prompt

Attach the document, then paste this. It's deliberately harsher on the source than the source deserves.

You are converting a document into a Claude skill. Read the attached document once,
completely, then work from your notes — do not re-read it later in this session.

Governing rules:
- A document explains to a reader; a skill instructs an agent whose every line is a
  recurring token cost. Delete anything that only orients a human.
- Assume the reader is a competent engineer. Cut definitions, background, and any
  justification of why a tool was chosen.
- Where the document lists alternatives, pick one default and name at most one exception.
- Reorder into execution order, not the order the document taught it in.

STEP 1 — CLASSIFY. In one line: is this a PROCEDURE (do these steps) or a STANDARD
(produce work that satisfies these rules)? Procedures become a numbered workflow with a
checklist. Standards become rules plus a review loop that checks output against them.

STEP 2 — INTERVIEW ME, one question at a time, only about what the document leaves
ambiguous: choices it presents without deciding, values left as placeholders, and steps
whose failure mode depends on my setup. Do not ask me anything the document answers.

STEP 3 — WRITE THE SKILL.
- name: lowercase-hyphenated, gerund form where it reads naturally.
- description: the capability AND the situations that should reach for it, as concrete
  trigger phrases a person would actually type. Ask me for the exact words I use when I
  request this work, and build the trigger from those, not from the document's title.
- Body: numbered steps (procedure) or rules + review loop (standard). Label each step's
  freedom level — fragile steps get one exact command plus an explicit "do not modify
  this"; judgment steps get a short heuristic list. Shorter is always better.
- Move anything I would look up rather than follow — tables, full option references,
  long example sets, templates — into sibling files referenced one level deep from
  SKILL.md. List each file with what it contains.

STEP 4 — REPORT, in this order:
1. Source word count vs SKILL.md word count, as a ratio.
2. A DELETION LOG: every section of the document you dropped, one line of reasoning each.
3. Anything the document assumed and never stated, that you had to guess.
4. Three requests that SHOULD trigger this skill, and two near-misses that should NOT.
5. Where to save it, and the first sentence I should type to fire it.

Then put it where it actually runs

In Claude Code it's a directory on disk: ~/.claude/skills/<name>/SKILL.md for everywhere, or the project's .claude/skills/ when a second person needs it — that's the version that goes in git. On claude.ai you zip the folder and upload it in Settings, on Pro, Max, Team or Enterprise with code execution enabled. One caveat the docs state flatly: custom skills do not sync across surfaces. Converting the document once doesn't put the skill everywhere; each surface is its own upload.

Why this matters more from São Paulo than from San Francisco

If you're a Brazilian dev or EM on a distributed US or EU team, your team's real knowledge already lives in documents — a Notion runbook, an onboarding PDF, a spec nobody opens. Those were written for a reader who could turn to a colleague for the missing half. At 3am your time you can't, and neither can an agent. Converting one into a skill forces the ambiguity out into the open, and a committed .claude/skills/ folder is one of the few artifacts that shows that judgment while you're asleep.

Today: take the one document your team keeps re-explaining, run the prompt above, and read only the deletion log. If it dropped a section that mattered, you just found the ambiguity the document was hiding — fix that line, not the skill.

Sources

• Claude Code docs — Extend Claude with skills
• Claude Docs — Skill authoring best practices
• Claude Docs — Agent Skills overview
• Claude Docs — PDF support
• Anthropic Engineering — Equipping agents for the real world with Agent Skills