agentleFS
hiteshbandhuhiteshbandhu/skills-i-use/skills/pdf-report/SKILL.md

pdf-report

Skill1 starsChanged 5 months agoMITView on GitHub

Produce a client-ready PDF — proposal, audit, brief, one-pager — by authoring HTML/CSS and rendering with headless Chrome. Covers the print-CSS traps that silently clip content, inline SVG diagrams that survive print, hitting an exact page count, and the evidence discipline that keeps a client document defensible. Triggers on "make a PDF", "client proposal", "audit report", "one-pager", "deck for the client", "print this", "turn this into a document", "5 page report", "professional report". Use when the deliverable leaves your team — a document a client, board or admin reads. Not for READMEs, internal notes, or web pages that stay on screen.

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Someone must edit it: If the client will rewrite half of it, send the source format they use.

    line 40
  2. Distinctive:

    Ask, or decide explicitly and say so:

    line 65
  3. Very specific:

    Write a single .html file with inline <style>.

    line 77
  4. Distinctive:

    Read print-css.md before writing the CSS.

    line 81
  5. Distinctive:

    Look → list every problem → fix them together → re-render → verify once.

    line 99
  6. Very specific:

    When patching HTML with a script, assert each replacement matched, and write the file after each change or in a way that survives a …

    line 127
  7. Distinctive:

    Verify before asserting: If you can check a claim with one API call or one query, check it.

    line 144
  8. Distinctive:

    Check whether a pattern has a boring explanation: before presenting it as a finding.

    line 149
  9. Distinctive:

    Read document-craft.md for structure, tone and the sections a client document needs.

    line 153

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PDF Report — Client Documents That Survive Contact With A Printer

A PDF is not a web page that happens to be saved. It has a fixed canvas, no scrollbar to rescue overflow, no hover to hide detail behind, and no second chance once it is emailed. Content that overflows is silently cut off at the page edge — the reader sees a table missing its last column and assumes you are sloppy.

This skill is the pipeline (HTML → headless Chrome → PDF), the traps that cost real rework, and the content rules that keep a client document defensible when someone challenges a number in it.

Supporting files:

  • print-css.md — the CSS that behaves differently on paper, and the clipping bugs
  • diagrams.md — inline SVG that survives print, and when a diagram earns its place
  • render.md — the Chrome pipeline, exact flags, and how to verify the output
  • document-craft.md — structure, audience, and evidence discipline
  • template.html — a working starter with the traps already handled

Output: {SKILL_OUTPUT_DIR}/pdf-report/ — see ../OUTPUT.md


When NOT to use this

  • It stays on screen. A web page, dashboard or artifact wants different craft — use ui-ux.
  • It is internal. A note for your own team does not need a cover, sources or page discipline.
  • Someone must edit it. If the client will rewrite half of it, send the source format they use. A PDF is a final form, not a working draft.
  • It is one paragraph. Say it in the message.

The process

1. Decide the page budget first

The page count is a hard constraint you design against, not an outcome you discover. It changes what the document can be:

PagesWhat fitsWhat it is
1One argument, one diagram, five numbersA one-pager that gets read in a meeting
4–6One idea per page, diagram-ledA brief an executive actually finishes
12–20Sections, contents page, worked examplesA reference document people dip into

A 20-page document nobody reads is worth less than a 5-page one they finish. If you are asked to cut length, cut prose and let diagrams carry the argument — do not shrink type until it is unreadable.

2. Establish the reader before writing a word

Ask, or decide explicitly and say so:

  • Who reads this? A technical lead and a non-technical admin need different documents. For a non-technical reader, define every term of art the first time it appears, and put a short glossary near the front.
  • What must they do after reading? Approve something, confirm something, decide something. That action belongs in the document, near the end, stated plainly.
  • What will they push back on? Pre-answer it with evidence. "No new software needed" invites "are you sure?" — so check the licence tier and print the answer.

3. Author HTML, not a PDF library

Write a single .html file with inline <style>. Reasons: you can see it in a browser instantly, the CSS is real CSS, and diagrams are inline SVG you fully control. PDF libraries (reportlab, fpdf) cost more effort for a worse result on anything with layout.

Read print-css.md before writing the CSS. The grid-overflow trap in there has cost multiple rebuild cycles and is invisible in the browser.

4. Render, then look at it

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --headless=new --disable-gpu --no-sandbox --no-pdf-header-footer \
  --virtual-time-budget=15000 \
  --print-to-pdf="Report.pdf" "file://$PWD/report.html"

Then actually look at the rendered pages — read the PDF back as images. Do not trust that it rendered correctly because the HTML was well-formed. Clipping, page breaks and font fallbacks are only visible in the output. See render.md.

5. Fix in one pass, re-render, stop

Look → list every problem → fix them together → re-render → verify once. Do not iterate one fix at a time; each render cycle is slow and the reader is waiting.


The five failures that actually happen

1. Right-edge clipping from grid children. CSS grid items default to min-width: auto and refuse to shrink below their content. On a fixed page they overflow the printable width and the right-hand item loses its border — or its whole column — off the page edge. Always minmax(0, 1fr), never bare 1fr.

2. Backgrounds and colours dropping out. Print stylesheets strip background colours by default. Without print-color-adjust: exact your coloured callouts, filled table headers and chart bars render white on white.

3. A figure alone on an empty page. break-inside: avoid on a tall figure pushes it whole to the next page, leaving 60% of the previous page blank. Either shrink the figure to fit the remaining space, or move it to the top of the next section deliberately.

4. Web fonts silently falling back. Headless Chrome will render before Google Fonts arrive unless you give it --virtual-time-budget. The PDF then ships in Times New Roman and looks amateur. Always declare a real fallback stack too.

5. Edit scripts that lose their work. When patching HTML with a script, assert each replacement matched, and write the file after each change or in a way that survives a mid-script failure. A script that applies twelve edits and crashes on the thirteenth before write_text() loses all twelve, and the failure looks like the edits were applied.


Evidence discipline

A client document gets challenged. Every number in it should survive the question "how do you know that?"

  • Separate what you were told, what you concluded, and what you measured. Keep them visually distinct in the document. A reader who cannot tell your inference from your measurement will not trust either.
  • State the limits. Sample sizes, what you could not access, where a match is probable rather than confirmed. A limits paragraph makes the rest more credible, not less.
  • Verify before asserting. If you can check a claim with one API call or one query, check it. Asserting something the client knows is wrong costs the whole document.
  • Do not name individuals as the problem. Attribute to roles, systems and processes. "Records are assigned to a closed account" not "X never cleaned up their leads." A named person in a client document turns a systems review into a performance review.
  • Check whether a pattern has a boring explanation before presenting it as a finding. One account owning thousands of records usually means an integration authenticating as that user — not a heroic employee. Ask the obvious question first.

Read document-craft.md for structure, tone and the sections a client document needs.


Design defaults that read as professional

  • Monotone plus one or two accents. A grey scale with a single considered accent colour, plus one semantic warning tone, reads more expensive than a palette. Avoid corporate blue; pick something specific to the subject.
  • Three type roles. A serif for headings (authority), a humanist sans for body (legibility at small sizes), a mono for numbers and labels (alignment, and it signals "measured"). Set font-variant-numeric: tabular-nums anywhere digits stack.
  • Let structure encode meaning. Numbered sections only if order matters. A coloured edge only on the thing that needs attention. If every block has a border and a shadow, nothing stands out.
  • 9–10pt body on A4. Smaller reads as dense and cheap; larger wastes the page budget.
  • Print in greyscale before sending. Many clients do. If your amber warning and your green success become the same grey, the document stops working.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.