PDF To Markdown

Codex compatibility note: - Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references. - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes. - User-question prompts mean to ask the user directly in Codex. - Ignore Claude-specific mode-switch instructions when they appear. - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written. - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task. - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first. - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence. - If a required step/tool cannot run in this environment, stop and ask the user before adapting.

<!-- CODEX:PROJECT-REFERENCE-LOADING:START -->

Codex Project-Reference Loading (No Hooks)

Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.

Always read:

• docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)
• docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)
• docs/project-reference/lessons.md (always-on guardrails and anti-patterns)

Missing/stale context route: If docs/project-config.json, the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any task-required reference doc is missing or stale, auto-run $project-init or the narrow setup route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) before ordinary project-specific work. If Codex mirrors or AGENTS.md are missing/stale, ask the user to run $sync-codex; do not auto-run it.

Situation-based docs:

• Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): project-structure-reference.md
• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec authoring, docs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.md
• Behavior/public-contract changes or spec-test-code sync: workflow-spec-test-code-cycle-reference.md plus the spec docs above
• Derived spec indexes/ERDs/reimplementation guides: spec-system-reference.md and source Feature Specs under docs/specs/
• Integration test implementation/review: integration-test-reference.md
• E2E test implementation/review: e2e-test-reference.md
• Code review/audit work: code-review-rules.md plus domain docs above based on changed files

Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.

<!-- CODEX:PROJECT-REFERENCE-LOADING:END -->

Quick Summary

Goal: Convert PDF files to well-formatted Markdown with auto-detection of native text vs scanned documents.

Workflow:

1. Auto-Detect — Determine if PDF has native text or needs OCR
2. Convert — Run scripts/convert.cjs with input path and optional mode/output flags
3. Output — Returns JSON with success status, page count, and output path

Key Rules:

• Use --mode auto (default) to let the tool decide native vs OCR
• OCR for scanned PDFs requires additional tesseract.js setup
• Complex multi-column layouts may not preserve structure perfectly

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

pdf-to-markdown

Convert PDF files to Markdown format with automatic detection of native text vs scanned documents.

Installation Required

This skill requires npm dependencies. Run one of the following:

# Option 1: Install via ClaudeKit CLI (recommended)
ck init  # Runs install.sh which handles all skills

# Option 2: Manual installation
cd .claude/skills/pdf-to-markdown
npm install

Dependencies: @opendocsg/pdf2md (native PDFs), pdfjs-dist (PDF parsing)

Note: OCR for scanned PDFs requires additional setup (see OCR section).

Quick Start

# Basic conversion (auto-detect native vs scanned)
node .claude/skills/pdf-to-markdown/scripts/convert.cjs --input ./document.pdf

# Specify output path
node .claude/skills/pdf-to-markdown/scripts/convert.cjs -i ./doc.pdf -o ./output.md

# Force native mode (skip OCR detection)
node .claude/skills/pdf-to-markdown/scripts/convert.cjs -i ./doc.pdf --mode native

CLI Options

Features

• Auto-Detection: Automatically determines if PDF has native text or requires OCR
• Native PDFs: Fast extraction using @opendocsg/pdf2md
• Tables: Basic table structure preservation
• Cross-OS: Works on Windows, macOS, Linux
• No System Dependencies: Pure JavaScript implementation

Conversion Modes

Auto (Default)

Checks if PDF has extractable text on first page. Uses native extraction if text found, otherwise falls back to OCR warning.

Native

Fast direct text extraction. Best for PDFs with selectable text (not scanned images).

OCR (Scanned PDFs) - Coming Soon

For scanned documents. Currently not implemented - the skill will notify you if a PDF appears to be scanned.

Output

Returns JSON on success:

{
    "success": true,
    "input": "/path/to/input.pdf",
    "output": "/path/to/output.md",
    "stats": {
        "pages": 5,
        "mode": "native"
    }
}

Limitations

• Complex multi-column layouts may not preserve structure
• Scanned PDF OCR accuracy depends on image quality
• Mathematical formulas may not convert perfectly
• First-run OCR downloads language data (~15MB)

OCR Setup (Optional)

For scanned PDF support, install additional dependencies:

npm install tesseract.js pdfjs-dist canvas

Note: The canvas package may require build tools on some systems.

[IMPORTANT] Use task tracking to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.

<!-- SYNC:ai-mistake-prevention -->

AI Mistake Prevention — Failure modes to avoid on every task: Re-read files after context changes. Context compaction, resume, or long-running work can make memory stale; verify current files before acting. Verify generated content against source evidence. AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. Check downstream references before deleting or renaming. Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. Trace the full impact chain after edits. Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done.