SKILL.md
PDF accessibility reviewer
An evidence-first workflow to review a PDF for tags, reading order, language, text alternatives, forms, and contrast.
- Revision
- 2
- Verified
- 2026-10-20
Compatibility and paths
Codex
skills/pdf-accessibility/SKILL.mdClaude Code
.claude/skills/pdf-accessibility/SKILL.mdVS Code
.github/skills/pdf-accessibility/SKILL.mdTrust and provenance
Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.
Generated assetReady to copy or download
---
name: pdf-accessibility
description: Reviews PDF logical structure, reading order and language with rendered and structural evidence. Use when extractable text or a polished page is being mistaken for accessible tagged output; report actual assistive-technology coverage and missing repair checks.
license: CC-BY-4.0
compatibility: Complete Python3.11+ original PDF example uses tested reportlab4.4.9 and pypdf6.10.0, installed in your chosen environment. Creates only one fresh owned temp PDF. A PDF renderer and real supported reader/AT/checker are separate verification requirements.
metadata:
author: oneliners
version: "2.0.0"
---
# PDF accessibility reviewer
## Inspect the artifact through separate evidence layers
Identify source/output versions, pages, intended reading flow and supported reader/assistive technology. Render the actual pages, inspect text extraction and catalog/tag tree, then test keyboard/reading order and applicable forms/alternatives. A screenshot, selectable text, OCR or metadata title does not prove semantics. Treat embedded content/actions/attachments as untrusted; do not execute scripts, open external attachments or upload private documents without authority.
## Complete original PDF counterexample
Use an owned Python environment with reportlab==4.4.9 and pypdf==6.10.0 (the tested versions; no automatic installer is included). Save the complete block as pdf-evidence.py and run python pdf-evidence.py. It creates and reopens only a new temporary negative-control file and prints its exact path. All content, dimensions and instructions are included; no sample PDF/download is missing.
```python
import json, tempfile
from pathlib import Path
import pypdf, reportlab
from reportlab.pdfgen import canvas
from pypdf import PdfReader
directory = Path(tempfile.mkdtemp(prefix="oneliners-owned-pdf-"))
path = directory / "owned-negative-control.pdf"
c = canvas.Canvas(str(path), pagesize=(612,792), pageCompression=0, invariant=1)
c.setTitle("Owned PDF evidence exercise")
c.setFont("Helvetica-Bold",20)
c.drawString(54,730,"Owned PDF evidence")
c.setFont("Helvetica",11)
c.drawString(54,704,"Original negative control. Visible text alone does not prove accessibility.")
# Intentionally paint right column before left. This is not a recommended reading order.
c.setFont("Helvetica-Bold",15)
c.drawString(324,650,"2. Verify")
c.setFont("Helvetica",12)
c.drawString(324,622,"Confirm the result")
c.drawString(324,600,"Keep rollback evidence")
c.setFont("Helvetica-Bold",15)
c.drawString(54,650,"1. Prepare")
c.setFont("Helvetica",12)
c.drawString(54,622,"Check owner scope")
c.drawString(54,600,"Use an owned target")
c.setFont("Helvetica",10)
c.drawString(54,72,"Exercise page 1. No form, image, script, customer record or external link.")
c.showPage()
c.save()
reader=PdfReader(str(path))
root=reader.trailer["/Root"]
text=reader.pages[0].extract_text()
assert len(reader.pages)==1
assert "1. Prepare" in text and "2. Verify" in text
assert text.index("2. Verify") < text.index("1. Prepare")
assert "/StructTreeRoot" not in root
assert root.get("/Lang") is None
print(json.dumps({"pdf":str(path),"pages":len(reader.pages),"extractableText":True,"extractedVerifyBeforePrepare":True,"tagTreePresent":"/StructTreeRoot" in root,"catalogLanguage":root.get("/Lang"),"title":reader.metadata.title,"versions":{"pypdf":pypdf.__version__,"reportlab":reportlab.Version},"decision":"HOLD_ACCESSIBILITY_ACCEPTANCE","scope":"Actual created/reopened negative-control PDF and extraction/catalog observations. No screen reader, keyboard tab order, repair, PDF/UA checker, OCR or full accessibility conformance verified."},indent=2))
```
To view the whole page with an installed Poppler renderer, run pdftoppm -singlefile -png followed by the printed PDF path and a new owned output prefix. Quote paths appropriately for your shell. Do not use text extraction as the visual review.
## Worked structural finding and remediation boundary
The actual generated/reopened PDF has one page, a title and extractable text. Visually its numbered columns suggest Prepare before Verify, but the extractor returns Verify before Prepare because this owned negative control painted the right column first. The catalog has no StructTreeRoot and no default Lang entry. Text extraction and a neat image would not establish logical structure or a usable reading sequence.
Report these exact observations, not an invented screen-reader transcript: extraction order is an indicator to investigate, not proof every assistive technology reads the same sequence. Missing tags prevent this fixture from supplying the intended tagged-PDF structure. Adding a title, OCR text, MarkInfo flag or a guessed language alone would not construct the semantic heading/paragraph/order tree. This program does not repair the PDF or claim PDF/UA/WCAG conformance.
Remediate in the actual editable source with meaningful headings/structure, correct column sequence, document language and tagged export; inspect the written tag tree/content associations and validate the output with the appropriate checker plus the supported reader/assistive technology. Check alternatives/tables/forms/links and keyboard order when those exist. This page deliberately has no forms/images/links, so their absence here does not test them. Render/review the whole original page, then re-extract and manually retest the repaired real file; an export success or checker green result alone is incomplete evidence. Preserve the source and do not flatten interactive or signed PDFs as a convenience.
The file is original fictional content created only in a fresh temp directory, retained for inspection. The code reads no existing PDF/customer file and sends nothing externally. Its actual tested libraries are ReportLab4.4.9 and pypdf6.10.0; later library versions need their own output verification. Record native/AT/checker gaps explicitly rather than relabeling this negative control as an accessible deliverable.
## Validate the repaired source and written PDF
[W3C current PDF3 guidance](https://www.w3.org/WAI/WCAG22/Techniques/pdf/PDF3) addresses logical reading/tab order; [PDF16](https://www.w3.org/WAI/WCAG22/Techniques/pdf/PDF16) addresses default language. These techniques inform relevant checks rather than certifying this file. [pypdf extraction documentation](https://pypdf.readthedocs.io/en/stable/user/extract-text.html) describes extraction limits and [ReportLab canvas documentation](https://docs.reportlab.com/reportlab/userguide/ch2_graphics/) the original drawing primitives. Return page/element, observed visual/structure/interaction evidence, user consequence, source-level remediation and explicit revalidation gaps. Do not claim accessibility from missing-error counts, add empty tags as a cosmetic pass or discard form/signature behavior.
Real example
Input
Run the complete original PDF negative-control program in SKILL.md in the stated environment. Render the printed file and compare visible numbered columns, extraction order and actual catalog tags/language. Report real observations and source-level remediation without inventing AT/PDF-UA conformance or a completed repair.
Expected result
The actual generated/reopened PDF has one page, a title and extractable text. Visually its numbered columns suggest Prepare before Verify, but the extractor returns Verify before Prepare because this owned negative control painted the right column first. The catalog has no StructTreeRoot and no default Lang entry. Text extraction and a neat image would not establish logical structure or a usable reading sequence. Report these exact observations, not an invented screen-reader transcript: extraction order is an indicator to investigate, not proof every assistive technology reads the same sequence. Missing tags prevent this fixture from supplying the intended tagged-PDF structure. Adding a title, OCR text, MarkInfo flag or a guessed language alone would not construct the semantic heading/paragraph/order tree. This program does not repair the PDF or claim PDF/UA/WCAG conformance. Remediate in the actual editable source with meaningful headings/structure, correct column sequence, document language and tagged export; inspect the written tag tree/content associations and validate the output with the appropriate checker plus the supported reader/assistive technology. Check alternatives/tables/forms/links and keyboard order when those exist. This page deliberately has no forms/images/links, so their absence here does not test them. Render/review the whole original page, then re-extract and manually retest the repaired real file; an export success or checker green result alone is incomplete evidence. Preserve the source and do not flatten interactive or signed PDFs as a convenience. The file is original fictional content created only in a fresh temp directory, retained for inspection. The code reads no existing PDF/customer file and sends nothing externally. Its actual tested libraries are ReportLab4.4.9 and pypdf6.10.0; later library versions need their own output verification. Record native/AT/checker gaps explicitly rather than relabeling this negative control as an accessible deliverable.