PDF to markdown converter

Convert PDF and image documents to clean Markdown via the PDF2Markdown CLI. Use when the user wants to extract text from PDFs, convert PDFs to markdown, pars...

Security Scan

The skill's instructions and docs describe a CLI that requires an API key and can upload documents to an external service, but the registry metadata doesn't declare the required credential or an install step — these mismatches and the install instructions that can modify agent directories are concerning.

Purpose & Capability

The declared purpose (convert PDFs/images to Markdown) matches the CLI commands and options in SKILL.md and the included docs. However, the SKILL.md and rules reference an API key (PDF2MARKDOWN_API_KEY) and require the CLI to be 'pre-installed and authenticated', but the registry metadata lists no required environment variables or primary credential — a clear metadata/instruction mismatch.

Instruction Scope

Instructions stay focused on parsing and output handling, advising file-based output and incremental reads. They also instruct running commands that will upload/parse files via the external CLI (expected). A notable instruction is the CLI's 'setup skills' command which claims to install into detected agent directories (e.g., .cursor/skills, .opencode/skills) — this implies the CLI may modify local agent files, which is beyond simple PDF parsing and worth scrutiny before running.

Install Mechanism

There is no install spec in the registry (instruction-only skill), but rules/install.md suggests installing via npm/pnpm/yarn or using npx for one-off use. The referenced package (pdf2markdown-cli on npm) and docs URL look consistent; there's no arbitrary download URL or archive extraction. The absence of an official install entry in the skill metadata while providing full install instructions in included files is an inconsistency to be aware of.

Credentials

The runtime docs explicitly reference PDF2MARKDOWN_API_KEY (and login commands), which is the credential required to use the CLI and the external service. Yet the skill metadata declares no required env vars or primary credential. That mismatch is problematic because users won't see the credential requirement at install/permission time. No unrelated credentials are requested, but an API key is clearly required in practice and should be declared.

Persistence & Privilege

The skill itself is not 'always' included and doesn't request elevated platform privileges. However, the install docs instruct the CLI to 'install skills' into multiple detected agents and specific agent directories. If followed, those commands could change agent configuration folders or deploy code into local agent skill directories — this is a persistence/privilege consideration users should understand before running the install steps.

What to consider before installing

This skill appears to wrap an external CLI/service (pdf2markdown.io) which will require an API key and will likely upload documents to that service. Before installing or running it: 1) Verify the npm package (pdf2markdown-cli) and the domain (pdf2markdown.io) are legitimate and review their privacy/TOS to understand how uploaded documents are handled. 2) Expect to set PDF2MARKDOWN_API_KEY — treat it as sensitive and prefer npx (no global install) if you want to avoid changing system state. 3) Don't run any 'setup skills' or 'install to agents' commands unless you trust the package: those steps can modify agent/skill directories. 4) Test with non-sensitive documents first. 5) Ask the publisher to update the skill metadata to declare PDF2MARKDOWN_API_KEY (primaryEnv) and explicitly document any agent-directory modifications — that will remove the main coherence concern.

PDF2Markdown CLI

Convert PDF and image documents to Markdown. Supports both pdf2markdown and pdf2md commands.

Run pdf2markdown --help or pdf2md <command> --help for options.

Prerequisites

Install and authenticate. Check with pdf2markdown --status.

pdf2markdown login
# or set PDF2MARKDOWN_API_KEY

If not ready, see rules/install.md. For output handling, see rules/security.md.

Workflow

Need	Command	When
Convert PDF/image	parse	File under ~30MB, have path or URL
Large file (async)	parse-async	File over ~30MB, or sync returns file_too_large error

Quick start

Parse (sync, ~30MB):

pdf2markdown document.pdf -o .pdf2markdown/output.md
pdf2markdown parse --url "https://example.com/doc.pdf" -o .pdf2markdown/doc.md
pdf2markdown parse file1.pdf file2.png -o .pdf2markdown/

# JSON output
pdf2markdown parse document.pdf --format json -o .pdf2markdown/result.json

Parse-async (large files, up to 100MB):

# Submit and wait
pdf2markdown parse-async large.pdf --wait -o .pdf2markdown/output.md
pdf2markdown parse-async --url "https://cdn.example.com/big.pdf" --wait -o .pdf2markdown/doc.md

# Submit only (poll later)
pdf2markdown parse-async large.pdf  # returns task_id
pdf2markdown parse-async <task_id> --status
pdf2markdown parse-async <task_id> --result -o .pdf2markdown/output.md

Options

Command	Key options
parse	-u, --url, -o, --output, -f, --format (markdown, json, all), --page-images, --json, --pretty
parse-async	-u, --url, -o, --output, --wait, --status, --result, --poll-interval, --timeout

Run pdf2markdown <command> --help for full details.

Output & Organization

Write results to .pdf2markdown/ with -o. Add .pdf2markdown/ to .gitignore.

pdf2markdown document.pdf -o .pdf2markdown/doc.md
pdf2markdown parse file1.pdf file2.pdf -o .pdf2markdown/

Naming: .pdf2markdown/{name}.md. For large outputs, use grep, head, or incremental reads. Always quote URLs — shell interprets ? and & as special characters.

Documentation

• PDF2Markdown API Docs